Refuse a verb argument the seat would pass over, and say a push is of the whole mesh

A push naming one machine reached the verb without it and pushed every
machine behind (hq issue 244). The controller now refuses any argument a
verb does not declare, any it composed its command line without, and a
switch that is not true or false; a push that names no machine says first
that it is the whole mesh. Tests walk every served verb: no argument is
ever ignored, and every flag of a verb's command, read from the source, is
in its schema or accounted for. plan gains files, push behind, builds and
plans limit.

internal/catalogue/verbs.go

@@ -90,6 +90,7 @@ var ControllerVerbs = []Verb{
 		Input: schema(map[string]string{
 			"module": "one module's name; every module when absent",
 			"log":    "a build's id (as `builds` lists it): print what the build machine said, line by line",
+			"limit":  "how many builds to list (default 20); not with log",
 		}, nil)},
 	{Name: "plans", Description: "What the last merges produced and where each stands (novox/hq ADR 0162): " +
 		"the tiers, the tier a plan is at, what it waits for and since when; one plan whole, given its id.",
@@ -101,9 +102,14 @@ var ControllerVerbs = []Verb{
 			"repository": "owner/repository: the plan a merge there would produce, saving nothing (what-if); with paths or modules",
 			"paths":      "with repository: the files the merge would change, comma-separated, from the repository's root",
 			"modules":    "with repository: or the modules it would change, comma-separated",
+			"limit":      "how many plans to list (default 10); only when listing",
 		}, nil)},
-	{Name: "plan", Description: "What one machine would run, and why: the declaration the mesh would send it.",
-		Input: schema(map[string]string{"node": "the machine's name"}, []string{"node"})},
+	{Name: "plan", Description: "What one machine would run, and why: the declaration the mesh would send it — " +
+		"or, with files, the files it would be given.",
+		Input: schema(map[string]string{
+			"node":  "the machine's name",
+			"files": "\"true\": the files this machine would be given, instead of the declaration as JSON",
+		}, []string{"node"}, "files")},
 	{Name: "assign", Description: "Put a module on a machine. Refused with the mesh's own words when it cannot resolve there, " +
 		"or when a seat its resources are applied through is held by nothing on the machine (novox/hq ADR 0207).",
 		Input: schema(map[string]string{"node": "the machine's name",
@@ -121,8 +127,12 @@ var ControllerVerbs = []Verb{
 		}, []string{"node", "provision", "from", "module"})},
 	{Name: "unpin", Description: "Take that choice back, putting the question to the mesh again.",
 		Input: schema(map[string]string{"node": "the machine's name", "provision": "the provision"}, []string{"node", "provision"})},
-	{Name: "push", Description: "Send a machine everything it should be — or every machine that is behind, when no machine is named.",
-		Input: schema(map[string]string{"node": "the machine's name; every machine behind when absent"}, nil)},
+	{Name: "push", Description: "Send one machine everything it should be. With no machine named it is a push of the " +
+		"WHOLE mesh — every machine that is behind — and the answer says so first; behind says that outright.",
+		Input: schema(map[string]string{
+			"node":   "the machine's name; without it, every machine that is behind",
+			"behind": "\"true\": every machine that is behind, the whole mesh — the same as naming none, said outright; not with node",
+		}, nil, "behind")},
 	{Name: "rotate", Description: "Replace a credential. A pair credential, by provision (and a consuming machine, " +
 		"else every holder): both ends are re-sent together. Or a module's own secret, by machine, module and " +
 		"name: made anew and the machine sent, so the module starts again on it — only for a secret its " +
@@ -148,8 +158,8 @@ var ControllerVerbs = []Verb{
 			"module": "the module's name",
 			"values": "the settings as a JSON object, for set",
 			"node":   "one machine; the whole mesh when absent",
-			"clear":  "\"true\" to remove the layer instead of setting it",
-		}, []string{"module"})},
+			"clear":  "\"true\" to remove the layer instead of setting it; not with values",
+		}, []string{"module"}, "clear")},
 	{Name: "command", Description: "Run one command line of the controller's own, as you would type it at its " +
 		"shell — `node account g14 jochen`, `node show ace`, `module list` — and answer what it printed. The " +
 		"generic verb beside the named ones (novox/hq ADR 0154): everything the binary can do, without a verb " +
@@ -167,7 +177,7 @@ var ControllerVerbs = []Verb{
 		Input: schema(map[string]string{"id": "the ask's build id, as `queue` lists it"}, []string{"id"})},
 	{Name: "clear", Description: "Cancel every waiting ask in the build queue — and with dead, every dead one too — each " +
 		"recorded failed, cancelled by hand. Never touches one in flight.",
-		Input: schema(map[string]string{"dead": "\"true\" to cancel the dead asks as well"}, nil)},
+		Input: schema(map[string]string{"dead": "\"true\" to cancel the dead asks as well"}, nil, "dead")},
 	{Name: "rebuild", Description: "Ask a module's current source again under a new id — the branch it follows — or, given a " +
 		"build's id, that build's repository, path and ref. A module a plan holds unbuilt or failed joins that plan. Answers the new id.",
 		Input: schema(map[string]string{"what": "a module's name, or a build's id"}, []string{"what"})},
@@ -178,7 +188,7 @@ var ControllerVerbs = []Verb{
 			"id":       "the build's id",
 			"register": "\"true\" to register what it builds",
 			"older":    "\"true\", with register: even though a newer build of the module is registered",
-		}, []string{"id"})},
+		}, []string{"id"}, "register", "older")},
 	{Name: "kill", Description: "End a build where it runs: the machine that took it stops its commands and containers and " +
 		"announces it failed, killed by hand — settled, never handed to another machine.",
 		Input: schema(map[string]string{"id": "the build's id"}, []string{"id"})},
@@ -197,11 +207,27 @@ var ControllerVerbs = []Verb{
 }
 
 // schema is a JSON schema for an object of string properties, which is every argument the verbs
-// above take. Kept small on purpose: a schema an agent cannot read is a tool it cannot call.
-func schema(properties map[string]string, required []string) map[string]any {
+// above take. Kept small on purpose: a schema an agent cannot read is a tool it cannot call. The
+// switches are the properties that are "true" or "false" and nothing else, said in the schema as an
+// enum so a caller sees it and the verb can refuse any other word rather than read it as false.
+//
+// **The schema is the whole of what a verb takes** (novox/hq issue 244): an argument it does not
+// name is refused when the verb is called, never passed over.
+func schema(properties map[string]string, required []string, switches ...string) map[string]any {
+	isSwitch := map[string]bool{}
+	for _, s := range switches {
+		if _, declared := properties[s]; !declared {
+			panic("a switch that is not a property: " + s)
+		}
+		isSwitch[s] = true
+	}
 	props := map[string]any{}
 	for name, description := range properties {
-		props[name] = map[string]any{"type": "string", "description": description}
+		p := map[string]any{"type": "string", "description": description}
+		if isSwitch[name] {
+			p["enum"] = []string{"true", "false"}
+		}
+		props[name] = p
 	}
 	out := map[string]any{"type": "object", "properties": props}
 	if len(required) > 0 {