From 59ca36e55b99ca1dbe42642b3d901da35e14b2e8 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 18 Nov 2026 02:15:41 +0100 Subject: [PATCH] G1: tools runner_start, runner_run, runner_accept, runner_ask_again over the runner's seat verbs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each tool asks its served verb with the same arguments and answers its answer; the verb records the hand act, as for runner_rerun. Declared in the manifest. The seat has no verb release: no tool for it. Lead answer A-486 (G-22-lead-answers-2.md): tools are how a module is spoken to. Builds: design 47 G §83, §84, A-486 --- .../cmd/mesh-delivery-pipeline-tools/main.go | 1 + .../mesh-delivery-pipeline-tools/main_test.go | 5 +- .../mesh-delivery-pipeline-tools/verbtools.go | 81 +++++++++++++++++++ .../verbtools_test.go | 59 ++++++++++++++ .../mesh-delivery-pipeline/manifest_test.go | 1 + modules/mesh-delivery-pipeline/module.json | 4 + 6 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go create mode 100644 modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go index 3a4f3e7b..f185e5c4 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go @@ -152,6 +152,7 @@ func main() { tools = append(tools, UnloggedTools(stdio.State(seat.StatePipelines), stdio.Log(seat.StateStepLog), meshhandactsclient.Recorder{Ask: stdio.Ask}, func(f string, a ...any) { fmt.Fprintf(os.Stderr, "[mesh-delivery-pipeline-tools] "+f+"\n", a...) })...) tools = append(tools, CancelTool(r.List, stdio.Ask), RerunTool(stdio.Ask)) + tools = append(tools, VerbTools(stdio.Ask)...) tools = append(tools, TestRunsTools(stdio.Ask)...) tools = append(tools, HealthTool(r.Pipelines, kept{stdio.State(pipeline.StateConsumers)}, time.Now)) if err := stdio.Serve("", tools); err != nil { diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go index 6b708df0..29dfdcc8 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go @@ -32,13 +32,16 @@ func TestTools(t *testing.T) { names = append(names, tl.Name) } names = append(names, CancelTool(nil, nil).Name, RerunTool(nil).Name) + for _, tl := range VerbTools(nil) { + names = append(names, tl.Name) + } // RN25 (§468, §76; A-164): the health check is the bundle's runner_health. names = append(names, HealthTool(none{}, none{}, nil).Name) // §606, §549: the unlogged entries are listed and appended by hand. for _, tl := range UnloggedTools(stdio.State("pipelines"), stdio.Log("step-log"), nil, nil) { names = append(names, tl.Name) } - want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_health runner_unlogged runner_unlogged_append" + want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_start runner_run runner_accept runner_ask_again runner_health runner_unlogged runner_unlogged_append" if got := strings.Join(names, " "); got != want { t.Errorf("tools %q, want %q", got, want) } diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go new file mode 100644 index 00000000..4899f6aa --- /dev/null +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go @@ -0,0 +1,81 @@ +package main + +import ( + "encoding/json" + "errors" + "strings" + + seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner" + stdio "git.novox.be/novox/mesh-sdk/go" +) + +// VerbTools are runner_start, runner_run, runner_accept and runner_ask_again: the runner's seat verbs start, run, accept and +// ask-again, reachable as tools (design 47 G §83, §482), as runner_rerun reaches rerun. Each asks its verb over the bus with +// the arguments it was given and answers the verb's answer; the verb records the hand act and refuses what it refuses. +func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.Tool { + str := map[string]any{"type": "string"} + obj := func(required []string, props map[string]any) map[string]any { + return map[string]any{"type": "object", "properties": props, "required": required} + } + return []stdio.Tool{ + verbTool[seat.StartInput](ask, "start", seat.VerbStart, + "Start by hand the delivering pipeline of the head of a watched branch for a module, by the seat verb start: the branch, the module and why. A head whose pipeline is written already is refused by the verb, naming it.", + obj([]string{"branch", "module", "why"}, map[string]any{"branch": str, "module": str, "why": str}), + func(in seat.StartInput) string { + if in.Branch == "" || in.Module == "" { + return "start names the watched branch and the module" + } + return whyOf(in.Why) + }), + verbTool[seat.RunInput](ask, "run", seat.VerbRun, + "Start a run on request by the seat verb run: the members (module, branch, commit as the seat's Member) and optionally why.", + obj([]string{"members"}, map[string]any{"members": map[string]any{"type": "array", "items": map[string]any{"type": "object"}}, "why": str}), + func(in seat.RunInput) string { + if len(in.Members) == 0 { + return "run names its members" + } + return "" + }), + verbTool[seat.AcceptInput](ask, "accept", seat.VerbAccept, + "Accept one step of a pipeline by hand by the seat verb accept: the pipeline's key, the step, the artifact where the step is per artifact, and why.", + obj([]string{"pipeline", "step", "why"}, map[string]any{"pipeline": str, "step": str, "artifact": str, "why": str}), + func(in seat.AcceptInput) string { + if in.Pipeline == "" || in.Step == "" { + return "accept names the pipeline and the step" + } + return whyOf(in.Why) + }), + verbTool[seat.AskAgainInput](ask, "ask_again", seat.VerbAskAgain, + "Ask a declined approval step of a pipeline once more by the seat verb ask-again: the pipeline's key and why.", + obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "why": str}), + func(in seat.AskAgainInput) string { + if in.Pipeline == "" { + return "ask-again names the pipeline" + } + return whyOf(in.Why) + }), + } +} + +func whyOf(why string) string { + if strings.TrimSpace(why) == "" { + return "a hand act names why" + } + return "" +} + +// verbTool is one tool over one seat verb: it decodes the arguments into the verb's input, refuses what the check refuses +// before asking, and answers the verb's answer. +func verbTool[T any](ask func(string, any) (json.RawMessage, error), name, verb, description string, input map[string]any, check func(T) string) stdio.Tool { + return stdio.Tool{Name: Prefix + "_" + name, Description: description, Input: input, + Run: func(args map[string]any) (any, error) { + in, err := as[T](args) + if err != nil { + return nil, err + } + if msg := check(in); msg != "" { + return nil, errors.New(msg) + } + return ask("seat:"+seat.Seat+"."+verb, in) + }} +} diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go new file mode 100644 index 00000000..aa13afb8 --- /dev/null +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go @@ -0,0 +1,59 @@ +package main + +import ( + "encoding/json" + "strings" + "testing" + + seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner" +) + +// Each tool asks its seat verb with the arguments it was given and refuses, before asking, a call the verb would refuse. +func TestVerbTools(t *testing.T) { + for _, c := range []struct { + name, tool, key, refusal string + args map[string]any + body any + }{ + {"start", "runner_start", "seat:mesh-pipeline-runner.start", "", map[string]any{"branch": "main", "module": "i3", "why": "cancelled"}, + seat.StartInput{Branch: "main", Module: "i3", Why: "cancelled"}}, + {"start no why", "runner_start", "", "names why", map[string]any{"branch": "main", "module": "i3"}, nil}, + {"start no module", "runner_start", "", "branch and the module", map[string]any{"branch": "main", "why": "x"}, nil}, + {"run", "runner_run", "seat:mesh-pipeline-runner.run", "", map[string]any{"members": []any{map[string]any{}}, "why": "x"}, + seat.RunInput{Members: []seat.Member{{}}, Why: "x"}}, + {"run no members", "runner_run", "", "members", map[string]any{}, nil}, + {"accept", "runner_accept", "seat:mesh-pipeline-runner.accept", "", map[string]any{"pipeline": "p", "step": "lint", "artifact": "a", "why": "x"}, + seat.AcceptInput{Pipeline: "p", Step: "lint", Artifact: "a", Why: "x"}}, + {"accept no step", "runner_accept", "", "pipeline and the step", map[string]any{"pipeline": "p", "why": "x"}, nil}, + {"ask-again", "runner_ask_again", "seat:mesh-pipeline-runner.ask-again", "", map[string]any{"pipeline": "p", "why": "x"}, + seat.AskAgainInput{Pipeline: "p", Why: "x"}}, + {"ask-again no why", "runner_ask_again", "", "names why", map[string]any{"pipeline": "p"}, nil}, + } { + t.Run(c.name, func(t *testing.T) { + var key string + var body any + ask := func(k string, b any) (json.RawMessage, error) { + key, body = k, b + return json.RawMessage(`{"ok":1}`), nil + } + var run func(map[string]any) (any, error) + for _, tl := range VerbTools(ask) { + if tl.Name == c.tool { + run = tl.Run + } + } + out, err := run(c.args) + if c.refusal != "" { + if err == nil || !strings.Contains(err.Error(), c.refusal) || key != "" { + t.Fatalf("want refusal %q and no ask, got %v (asked %q)", c.refusal, err, key) + } + return + } + want, _ := json.Marshal(c.body) + got, _ := json.Marshal(body) + if err != nil || key != c.key || string(got) != string(want) || out == nil { + t.Fatalf("asked %q with %s, want %s, err %v", key, got, want, err) + } + }) + } +} diff --git a/modules/mesh-delivery-pipeline/manifest_test.go b/modules/mesh-delivery-pipeline/manifest_test.go index 8fd6045e..5f6dd00b 100644 --- a/modules/mesh-delivery-pipeline/manifest_test.go +++ b/modules/mesh-delivery-pipeline/manifest_test.go @@ -114,6 +114,7 @@ func TestManifest(t *testing.T) { {"uses operator-channel", equalSets(m.Uses, []string{"operator-channel"})}, // RN25 (§539): the runner's tools carry the prefix runner_. {"first-view tools", equalSets(m.Tools, []string{"runner_first_views", "runner_first_view_again", "runner_health", "runner_unlogged", "runner_unlogged_append", + "runner_start", "runner_run", "runner_accept", "runner_ask_again", "runner_test_runs", "runner_test_runs_drop"})}, // A-305 (ADR 0227 rule 8, ADR 0240 rule 2): the process is judged by its unit, as every process of mesh-delivery, // never by a tool of its own; runner_health stays a tool. diff --git a/modules/mesh-delivery-pipeline/module.json b/modules/mesh-delivery-pipeline/module.json index 13d86a9a..15910885 100644 --- a/modules/mesh-delivery-pipeline/module.json +++ b/modules/mesh-delivery-pipeline/module.json @@ -30,6 +30,10 @@ "runner_health", "runner_unlogged", "runner_unlogged_append", + "runner_start", + "runner_run", + "runner_accept", + "runner_ask_again", "runner_test_runs", "runner_test_runs_drop" ], -- 2.54.0