Answer mesh-cli: the control-node's operator is the terminal, everyone else is not (hq ADR 0272)

The records send the operator to "the controller's terminal", and nothing
reached it (hq issue 343). The serving controller now answers each node's
mesh.control.<node>.cli, where only that node's engine may publish, with the
account the engine read from the kernel. A line from the control-node's
operator account runs as the terminal: a fresh process of this binary with
no MESH_VERB, whatever the serving process carries. The same account on any
other node, where agents may run as it, is an ordinary call: the generic
command verb's refusals (one function now, so the two routes cannot drift)
and MESH_VERB=mesh-cli, so a terminal-only change is refused with its
reason. Any other account, root included, runs nothing. Servers are never
run, and an answer over one bus message is cut and says so.

The terminal-only refusals and the usage now name mesh-cli on the
control-node as the way to the terminal.

cmd/mesh-controller/meshcli.go

@@ -0,0 +1,157 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"slices"
+	"strings"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// The operator's command, `mesh-cli` (alias `nox`), answered here (novox/hq ADR 0272).
+//
+// mesh-cli asks the node-engine on its own machine; the engine reads the asking account from the kernel and asks
+// this controller on its own node's subject. Here it is judged — the controller's terminal, an ordinary call, or
+// nothing — and run as every verb's line is: a fresh process of this binary, with this process's environment.
+//
+// **The terminal** is a line from a node's operator account, on the control-node (§4). Phase 2 adds a node whose
+// agents run under an account of their own, judged unable to become root (ADR 0266, not built yet); until then no
+// other node is the terminal, because agents there run as its operator. **An ordinary call** is a line from that
+// account elsewhere: it meets every refusal of the generic `command` verb and runs with `MESH_VERB=mesh-cli`, so a
+// terminal-only change is refused with its reason. **Any other account is refused**, root included: those two
+// accounts already reach the mesh's verbs through the mesh MCP server, and no other account gains anything here.
+
+// cliVerb is what a line from mesh-cli that is not the terminal runs as: the verb its process names, so every
+// terminal-only refusal applies and says it came through mesh-cli.
+const cliVerb = "mesh-cli"
+
+// cliServers are commands that serve until stopped. Run for mesh-cli they would hold a second server under this
+// one until the call's bound killed it.
+var cliServers = map[string]bool{"serve": true, "api": true, "board": true}
+
+// cliVerdict is how a line is run, or why it is not.
+type cliVerdict struct {
+	terminal bool
+	// why says why the line is or is not the terminal, in words the operator reads under the answer.
+	why string
+	// refused says why nothing runs.
+	refused string
+}
+
+// judgeCLI decides how a line from mesh-cli runs (ADR 0272 §4). nodes is every node the mesh knows; control is
+// every node the controller's module is assigned to, which is exactly one in a mesh that is well.
+func judgeCLI(node string, asked link.CLIAsked, nodes []inventory.Node, control []string) cliVerdict {
+	var record *inventory.Node
+	for i := range nodes {
+		if nodes[i].Name == node {
+			record = &nodes[i]
+			break
+		}
+	}
+	switch {
+	case record == nil:
+		return cliVerdict{refused: fmt.Sprintf("%s is not a node this mesh knows, so nothing ran", node)}
+	case asked.UID == 0 || asked.Account == "root":
+		return cliVerdict{refused: "mesh-cli answers the operator's own account, never root: run it as yourself, " +
+			"not under sudo. Nothing ran"}
+	case record.Account == "":
+		return cliVerdict{refused: fmt.Sprintf("the mesh does not know %s's operator account (`node account <node> <login>`), "+
+			"so no account there is answered. Nothing ran", node)}
+	case asked.Account != record.Account:
+		return cliVerdict{refused: fmt.Sprintf("mesh-cli answers %s's operator account (%s) only, and this line came "+
+			"from %s. Nothing ran", node, record.Account, asked.Account)}
+	}
+	if len(control) != 1 {
+		return cliVerdict{why: fmt.Sprintf("not the controller's terminal: the mesh names %d control-nodes, and the "+
+			"terminal is the one control-node's operator account", len(control))}
+	}
+	if control[0] == node {
+		return cliVerdict{terminal: true, why: fmt.Sprintf("the controller's terminal: %s on the control-node %s",
+			asked.Account, node)}
+	}
+	return cliVerdict{why: fmt.Sprintf("not the controller's terminal: agents on %s may run as %s, so a "+
+		"terminal-only change is made from the control-node %s (novox/hq ADR 0272)", node, asked.Account, control[0])}
+}
+
+// controlNodes is every node the controller's module is assigned to.
+func controlNodes(ctx context.Context, inv *inventory.Inventory, nodes []inventory.Node) ([]string, error) {
+	var out []string
+	for _, n := range nodes {
+		modules, err := inv.Assigned(ctx, n.Name)
+		if err != nil {
+			return nil, err
+		}
+		if slices.Contains(modules, controllerModule) {
+			out = append(out, n.Name)
+		}
+	}
+	return out, nil
+}
+
+// controllerModule is the module that runs the controller, and so marks the control-node.
+const controllerModule = "mesh-controller"
+
+// answerMeshCLI is the serving controller's answer to mesh-cli.
+func answerMeshCLI(inv *inventory.Inventory) link.CLIHandler {
+	return func(ctx context.Context, node string, asked link.CLIAsked) link.CLIAnswer {
+		if handingOver.Load() {
+			return link.CLIRefusal("this controller is stopping and runs no new command; ask again in a moment. Nothing ran")
+		}
+		nodes, err := inv.Nodes(ctx)
+		if err != nil {
+			return link.CLIRefusal("the mesh's nodes cannot be read, so nothing ran: " + err.Error())
+		}
+		control, err := controlNodes(ctx, inv, nodes)
+		if err != nil {
+			return link.CLIRefusal("which node is the control-node cannot be read, so nothing ran: " + err.Error())
+		}
+		return runForMeshCLI(ctx, node, asked, judgeCLI(node, asked, nodes, control))
+	}
+}
+
+// runForMeshCLI runs a judged line and answers what it said.
+func runForMeshCLI(ctx context.Context, node string, asked link.CLIAsked, v cliVerdict) link.CLIAnswer {
+	if v.refused != "" {
+		return link.CLIRefusal(v.refused)
+	}
+	if cliServers[asked.Line[0]] {
+		return link.CLIAnswer{Exit: 1, Why: v.why, Refused: fmt.Sprintf("%s serves until stopped, and is not a "+
+			"command line mesh-cli runs. Nothing ran", asked.Line[0])}
+	}
+	verb := ""
+	if !v.terminal {
+		if err := refusedAsTheGenericCommand(asked.Line); err != nil {
+			return link.CLIAnswer{Exit: 1, Why: v.why, Refused: err.Error()}
+		}
+		verb = cliVerb
+	}
+	cmd := selfCommand(ctx, asked.Line)
+	cmd.Env = commandEnvironment(fmt.Sprintf("%s through mesh-cli on %s", asked.Account, node), verb)
+	// No standard input: a command that reads one gets nothing, and fails saying so (ADR 0272 §5).
+	cmd.Stdin = nil
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	err := cmd.Run()
+	answer := link.CLIAnswer{Stdout: stdout.Bytes(), Stderr: stderr.Bytes(), Terminal: v.terminal, Why: v.why}
+	var exit *exec.ExitError
+	switch {
+	case err == nil:
+	case errors.As(err, &exit):
+		answer.Exit = exit.ExitCode()
+		if answer.Exit < 0 {
+			// Killed: by the call's bound, or by this controller stopping.
+			answer.Exit = 1
+			answer.Stderr = append(answer.Stderr, []byte(fmt.Sprintf("\nmesh-cli: the command was stopped (%v)\n",
+				exit))...)
+		}
+	default:
+		answer.Exit = 1
+		answer.Refused = fmt.Sprintf("could not run %s from this controller's own build: %v", strings.Join(asked.Line, " "), err)
+	}
+	return answer
+}