Report a stale client and refuse an unreadable newer server

Exchange a build/protocol identity so an older CLI can no longer talk to a
newer native server silently:

- protocol carries ProtocolVersion and every server frame (including the
  unsolicited welcome) is stamped with the server build and protocol, so a
  client that never pings still learns the server identity.
- buildinfo.Compare classifies the relationship as InSync/Warn/Refuse and
  names both builds; the client Watch reports one warning per connection and
  returns a hard error when the server speaks a newer, uninterpretable
  protocol so the caller never acts on the frame.
- client.ReceiveNotice decodes the raw frame so an unmodeled top-level field
  produces a one-time "unrecognized field(s)" notice instead of being dropped
  silently (the case that hid the artifacts field).
- CLI routes warnings to stderr, keeps machine JSON stdout clean and fails
  non-zero on a refused mismatch; ping/connection print the client/server
  relationship. The TUI surfaces the same notices through the shared log.
- scripts/setup-native.py now warns when an older `pipelines` earlier on PATH
  shadows prefix/bin/pipelines, naming both paths and versions, without
  installing or modifying anything else.
- Docs, the packaged debugging skill reference and README no longer imply the
  installed CLI always matches the server.

Tests cover the comparison table, unknown-field detection and caching, the
server identity stamping on pong and welcome, the CLI/TUI reporting paths and
the installer PATH shadowing warning.
This commit is contained in:
2026-10-16 18:37:01 +01:00
parent 98bbc2deac
commit 8c1eea53a9
25 changed files with 1239 additions and 81 deletions
+15 -6
View File
@@ -66,7 +66,10 @@ cd pipelines
Native setup reuses your existing host OpenCode login and never installs,
upgrades or downloads OpenCode/Pi. It writes host harness profiles (no Docker
link) for the harnesses it detects, so authoring works immediately, and clears a
stale Docker link when migrating a Docker install. Start it with
stale Docker link when migrating a Docker install. After building, it warns if a
**different** `pipelines` resolves earlier on PATH than `<prefix>/bin/pipelines`,
naming that path and both versions, so a stale CLI is not left in front of a newer
server (it never modifies or upgrades that other binary). Start it with
`PIPELINES_PREFIX=~/.local/share/pipelines ~/.local/share/pipelines/bin/pipelines start`.
When Docker volumes are present it migrates the existing database and ntfy auth
store (never overwriting newer native data; use `--replace-data` to opt in). See
@@ -93,7 +96,9 @@ Prefer the installer-saved configured endpoint when present; never replace it wi
a guessed default.
Go uses `GOBIN` or its normal `GOPATH/bin` default; put that directory on PATH.
The Docker installer automatically detects/configures LAN networking for ntfy;
Running `pipelines` also compares its build/protocol with the server and warns (or
fails on a newer protocol) instead of dropping fields it does not model. The
Docker installer automatically detects/configures LAN networking for ntfy;
you do not need to look up your IP or supply a URL/listen address.
Both Docker services bind `0.0.0.0`; reinstall normalizes those bind settings
without replacing your URLs, timezone, ports or credentials.
@@ -205,8 +210,11 @@ pipelines
retry requires confirmation and restarts the pinned workflow, so earlier side
effects may happen again.
Home shows only **/** search and **:** commands as action hints; use the command
palette for creation, drafts, templates, history, status, logs, and quitting.
Home shows only **/** search and **:** commands as action hints; **/** opens the omni
popup, which finds pipelines, versions, runs, stages/visits, artifact names and the
text of stage inputs, outputs and evidence, and Enter opens the chosen result. Use
the command palette for creation, drafts, templates, history, status, logs, and
quitting.
Quit with **:quit**; **q** does not exit. For a terminal-only run after publication:
@@ -357,8 +365,9 @@ run resumes along that edge. The wait is persisted, so it survives a server
restart; an unknown option is refused with the valid list, a stage that is not
waiting is refused, and a repeated decision does not double-apply. **cancel** and
**retry** keep working while waiting and after a decision.
On Home, **r** opens global run history; **/** fuzzy-searches it. Inside a pipeline,
**r** / **:runs** opens only that pipeline's history.
On Home, **r** opens global run history; **/** opens the omni search popup over
pipelines, versions, runs, stages/visits, artifacts and stage input/output/evidence
text. Inside a pipeline, **r** / **:runs** opens only that pipeline's history.
Quit the TUI with **:quit**; **q** does not exit. **Ctrl+C** remains an interrupt.
Starting/retrying/canceling runs and deleting drafts require confirmation. CLI
publication also prompts; use `--yes` only for explicitly approved automation.
+26 -2
View File
@@ -23,10 +23,23 @@ running server's compiled `build.version`, full Git `build.commit`, and
`build.dirty`. Uncommitted builds have a `-dirty` suffix. Missing metadata is
explicit (`commit: "unknown"`, `dirty: null`); older servers omit `build`.
This identifies the server binary, not the CLI or files mounted into the container.
Plain `ping` also prints the server version/commit. `pipelines version --json`
Plain `ping` also prints the server version/commit and, beside the local client
build, the client/server relationship. `pipelines version --json`
(or `pipelines --version`) identifies the local client without connecting to a
server. Include both identities when reporting a problem; they can differ.
`ping`, `connection`, `status` and every server command now check that relationship.
The server stamps its `build` and integer `protocol` onto each response (the
unsolicited welcome envelope too). The client compares this build against the
server: a same-protocol build mismatch prints exactly one `warning:` on stderr
(stdout JSON stays parseable) and a server speaking a newer protocol fails the
command non-zero before it acts on the frame. If a response carries a top-level
field this client does not model — for example an `artifacts` field from a newer
server — the client prints a one-time `server sent unrecognized top-level field(s)
...` notice instead of silently appearing to have no data. Rebuild or reinstall the
CLI so it matches the server; the installer also warns when a different `pipelines`
resolves earlier on PATH than the freshly installed binary.
Home's `r` opens **all** runs, not only failures or the newest 50. Inside a pipeline,
`r` and `:runs` show only that pipeline's runs across its versions. In any run list,
@@ -34,6 +47,14 @@ press `/` for fuzzy search, type to filter, and Enter to return to the results.
Search includes pipeline name, version, status, outcome, stage and diagnostic;
`#123` searches run-ID prefixes. Esc while searching clears the filter without
closing the list. The filter survives inspection/back and live list refreshes.
Home's `/` instead opens the omni popup, which searches pipelines, versions, runs,
stages/visits, artifact names, and the text of stage inputs, outputs and evidence.
A bare status word (`queued`, `running`, `succeeded`, `failed`, `canceled`,
`interrupted`) or a date (`today`, `yesterday`, `this week`, or `YYYY-MM-DD`
interpreted in UTC) selects runs, and a leading `pipeline:`/`version:`/`run:`/
`step:`/`field:`/`artifact:`/`match:` prefix narrows the result kind. Enter opens
the matched pipeline, run, stage visit, artifact or field; unrecognised words
remain text.
Wide terminals
show runs and pipelines side by side, with stacked panels on narrow terminals.
Home run cards prioritize reported results, status, completed visits and duration;
@@ -219,7 +240,10 @@ printf '%s' '{"type":"get_pipeline","pipeline_id":1,"version":1}' | pipelines rp
Existing protocol commands: `ping`, `list_pipelines`, `get_pipeline`,
`list_templates`, `validate`, `submit`, `run_pipeline`, `list_runs`, `get_run`,
`cancel_run`, `retry_run`, `decide_run`, `set_run_title`, `get_run_evidence`, `get_status`. `list_runs` also returns all-history `usage`
`cancel_run`, `retry_run`, `decide_run`, `set_run_title`, `get_run_evidence`,
`get_status`, `search`. `search` takes `query` and an
optional `kind` and `limit` and returns ranked typed `matches`, each with a stable
`target` the client can open. `list_runs` also returns all-history `usage`
aggregates. See `internal/protocol/message.go` for JSON envelopes. Mutating RPCs
have real effects; they are not previews. TUI-only animation, scrolling, and
transient client logs are presentation, not separate server capabilities.
+8
View File
@@ -36,6 +36,14 @@ manifest is what `scripts/manage.py` and the Go CLI load. Provider/model default
are never invented: your existing host OpenCode configuration is reused (an
explicit `--model` is recorded if supplied), and setup never starts a picker.
After the build, setup checks whether a **different** `pipelines` resolves earlier
on PATH than `<prefix>/bin/pipelines` (the common cause of a stale CLI talking to a
newer server). When it does, setup prints a `WARNING` naming that absolute path and
both versions (`version --json` on each binary, read-only) and tells you to put
`<prefix>/bin` first on PATH. It never modifies, moves, deletes or upgrades that
other binary, and it installs no unrelated tool; the manifest keeps
`<prefix>/bin` first on the recorded PATH.
The native install also writes **host** harness profiles for the harnesses it
detects into XDG config home's `pipelines/harnesses.json` (no
`docker_directory`), defaulting to the detected OpenCode profile rather than a
@@ -87,12 +87,18 @@ Each playbook is *symptom → how to confirm → what to do*.
- **Symptom** `inspect --json` or `ping --json` is missing fields this skill
describes, or a flag is rejected as unknown.
- **Confirm** `ping --json` for the server build identity and `version --json` for the
client. An older server omits `build`; an older client may not send newer fields.
- **Confirm** The client now reports this itself. A server response carrying a
top-level field this client does not model prints a one-time
`server sent unrecognized top-level field(s) ...` notice; a same-protocol build
mismatch prints one `warning:` naming both builds on stderr; and a server
speaking a newer protocol fails the command non-zero. `ping --json` shows the
server build identity and `version --json` the client; `ping`/`connection`
also print the client/server relationship. An older server omits `build`.
- **Do** Treat it as a version mismatch, not a run failure. State both versions and
the mismatch. **Do not infer** that a source fix or an updated skill is deployed.
Use only flags the installed help shows; do not restart or reinstall a service to
"fix" it without the operator (`references/operations.md`).
"fix" it without the operator (`references/operations.md`). Rebuild or reinstall
the CLI so it matches the server; never hand-edit an installed binary.
## A server restart killing in-flight runs
+92
View File
@@ -0,0 +1,92 @@
package buildinfo
import "fmt"
// Severity classifies how a client build relates to the server it is talking to.
// The zero value is the in-sync case so callers can treat "no relationship" as
// no output.
type Severity int
const (
// InSync means both peers report the same build and the same protocol.
InSync Severity = iota
// Warn means the builds differ or the server could not be identified, but the
// exchange is still safe: the client keeps working and reports once.
Warn
// Refuse means the server speaks a protocol newer than this client can
// interpret; continuing would silently misread frames, so the caller must
// fail rather than proceed.
Refuse
)
// Relationship is the outcome of comparing a client build with a server build.
type Relationship struct {
Severity Severity
Message string
}
// Describe names a build for humans. A missing build is reported as
// "unavailable" rather than guessed.
func Describe(info *Info) string {
if info == nil {
return "unavailable"
}
return fmt.Sprintf("%s (commit %s)", info.Version, info.Commit)
}
// Compare classifies the client/server build relationship in O(1). Ordering uses
// the integer protocol only; build strings are used for naming, never parsed or
// ordered. server may be nil when the server omitted its build identity.
func Compare(client Info, clientProtocol int, serverProtocol int, server *Info) Relationship {
if serverProtocol > clientProtocol {
return Relationship{
Severity: Refuse,
Message: fmt.Sprintf(
"server build %s speaks protocol %d, newer than this client's supported protocol %d; "+
"update the pipelines CLI (client build %s) before connecting",
Describe(server), serverProtocol, clientProtocol, Describe(&client)),
}
}
if server != nil && serverProtocol == clientProtocol && sameBuild(client, *server) {
return Relationship{}
}
switch {
case server == nil:
return Relationship{
Severity: Warn,
Message: fmt.Sprintf(
"the connected server did not report its build identity (older or incompatible server); "+
"client build %s", Describe(&client)),
}
case serverProtocol == 0:
return Relationship{
Severity: Warn,
Message: fmt.Sprintf(
"the connected server did not report a protocol version (legacy server); "+
"client build %s, server build %s", Describe(&client), Describe(server)),
}
default:
return Relationship{
Severity: Warn,
Message: fmt.Sprintf(
"client build %s does not match server build %s; rebuild or reinstall the CLI so it "+
"matches the connected server", Describe(&client), Describe(server)),
}
}
}
// sameBuild reports whether two identities name the same compiled artifact. A
// missing Dirty pointer is distinct from an explicit value.
func sameBuild(a, b Info) bool {
if a.Version != b.Version || a.Commit != b.Commit {
return false
}
switch {
case a.Dirty == nil && b.Dirty == nil:
return true
case a.Dirty == nil || b.Dirty == nil:
return false
default:
return *a.Dirty == *b.Dirty
}
}
+108
View File
@@ -0,0 +1,108 @@
package buildinfo
import (
"fmt"
"strings"
"testing"
)
func TestCompareClassifiesBuildRelationship(t *testing.T) {
client := Info{Version: "v1-client", Commit: "aaaa"}
server := Info{Version: "v2-server", Commit: "bbbb"}
cases := []struct {
name string
clientProtocol int
serverProtocol int
server *Info
severity Severity
}{
{"identical", 1, 1, &client, InSync},
{"different build same protocol", 1, 1, &server, Warn},
{"server newer protocol", 1, 2, &server, Refuse},
{"nil server", 1, 0, nil, Warn},
{"legacy server protocol", 1, 0, &server, Warn},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := Compare(client, tc.clientProtocol, tc.serverProtocol, tc.server)
if got.Severity != tc.severity {
t.Fatalf("severity = %v, want %v (%q)", got.Severity, tc.severity, got.Message)
}
if got.Severity == InSync {
if got.Message != "" {
t.Fatalf("in-sync relationship must carry no message: %q", got.Message)
}
return
}
if strings.TrimSpace(got.Message) == "" {
t.Fatal("warning/refusal must name the mismatch")
}
})
}
}
func TestCompareWarningNamesBothBuilds(t *testing.T) {
client := Info{Version: "v1-client", Commit: "aaaa"}
server := Info{Version: "v2-server", Commit: "bbbb"}
relation := Compare(client, 1, 1, &server)
if relation.Severity != Warn {
t.Fatalf("severity = %v", relation.Severity)
}
for _, needle := range []string{client.Version, server.Version} {
if !strings.Contains(relation.Message, needle) {
t.Fatalf("warning %q does not name %q", relation.Message, needle)
}
}
}
func TestCompareRefusalNamesBothProtocolsAndBuilds(t *testing.T) {
client := Info{Version: "v1-client", Commit: "aaaa"}
server := Info{Version: "v2-server", Commit: "bbbb"}
relation := Compare(client, 1, 3, &server)
if relation.Severity != Refuse {
t.Fatalf("severity = %v, want Refuse", relation.Severity)
}
for _, needle := range []string{client.Version, server.Version, "3", "1"} {
if !strings.Contains(relation.Message, needle) {
t.Fatalf("refusal %q does not name %q", relation.Message, needle)
}
}
}
func TestCompareDistinguishesDirtyPointer(t *testing.T) {
base := Info{Version: "v1", Commit: "aaaa"}
clean := Info{Version: "v1", Commit: "aaaa", Dirty: boolPtr(false)}
dirty := Info{Version: "v1", Commit: "aaaa", Dirty: boolPtr(true)}
if got := Compare(base, 1, 1, &base); got.Severity != InSync {
t.Fatalf("identical missing-dirty identities must be in sync: %+v", got)
}
if got := Compare(clean, 1, 1, &dirty); got.Severity != Warn {
t.Fatalf("differing dirty state must warn: %+v", got)
}
if got := Compare(base, 1, 1, &clean); got.Severity != Warn {
t.Fatalf("nil dirty is distinct from an explicit value: %+v", got)
}
if got := Compare(clean, 1, 1, &clean); got.Severity != InSync {
t.Fatalf("identical explicit dirty identities must be in sync: %+v", got)
}
}
func TestDescribeNamesMissingBuildAsUnavailable(t *testing.T) {
if got := Describe(nil); got != "unavailable" {
t.Fatalf("Describe(nil) = %q", got)
}
info := Info{Version: "v1", Commit: "abc"}
if got := Describe(&info); !strings.Contains(got, "v1") || !strings.Contains(got, "abc") {
t.Fatalf("Describe = %q", got)
}
}
func TestSeverityZeroIsInSync(t *testing.T) {
var zero Severity
if zero != InSync {
t.Fatalf("zero severity = %v, want InSync", zero)
}
_ = fmt.Sprint(zero)
}
+32
View File
@@ -404,6 +404,13 @@ func (a App) Run(ctx context.Context, args []string) error {
return err
}
defer c.Close()
// Report at most one build/protocol warning per invocation on stderr, so
// stdout stays parseable JSON; an unsafe newer server fails the command.
c.Report(func(relationship buildinfo.Relationship) {
if relationship.Message != "" {
a.notice("warning: " + relationship.Message)
}
})
call := func(request protocol.Message) (protocol.Message, error) {
requestCtx, cancel := context.WithTimeout(ctx, o.timeout)
defer cancel()
@@ -684,11 +691,19 @@ func (a App) Run(ctx context.Context, args []string) error {
} else {
fmt.Fprintln(a.Out, "Server build: unavailable (older server)")
}
build := buildinfo.Current()
fmt.Fprintf(a.Out, "Client: %s (commit %s)\n", build.Version, build.Commit)
if note := identityNote(r); note != "" {
fmt.Fprintln(a.Out, "Note:", note)
}
case "connection":
fmt.Fprintln(a.Out, "Server:", o.url)
for _, n := range r.NotificationEndpoints {
fmt.Fprintf(a.Out, "ntfy: %s · topic %s\n", n.ServerURL, n.Topic)
}
if note := identityNote(r); note != "" {
fmt.Fprintln(a.Out, "Note:", note)
}
}
return nil
case "export":
@@ -888,6 +903,23 @@ func (a App) output(value any) error {
return encoder.Encode(value)
}
// notice writes one non-fatal line to stderr so machine-readable stdout stays
// intact. It never falls back to stdout, where it could corrupt --json output
// for an embedder that does not configure Err.
func (a App) notice(line string) {
w := a.Err
if w == nil {
w = os.Stderr
}
fmt.Fprintln(w, line)
}
// identityNote describes how this client build relates to a server response for
// human output; it is empty when both peers match.
func identityNote(response protocol.Message) string {
return buildinfo.Compare(buildinfo.Current(), protocol.MaxSupportedProtocol, response.Protocol, response.Build).Message
}
type callFunc func(protocol.Message) (protocol.Message, error)
type resolveFunc func(string) (protocol.PipelineSummary, error)
+16 -14
View File
@@ -34,20 +34,22 @@ var usage = map[string]string{
}
var notes = map[string]string{
"version": "Identify the local CLI binary without connecting to a server. --version is an alias. Use ping --json to identify the running server separately.",
"ping": "Pong includes the running server's compiled build.version, build.commit and build.dirty (null when unknown). This identifies the server, not the client or runtime workspace. Older servers omit build.",
"export": "Without a name, select pipelines with Space and save a ZIP in the current directory. --output writes a portable definition bundle; --all skips selection. One name without --output prints Markdown as before. No runs, credentials or old versions are exported.",
"import": "Select definitions from a ZIP. Identical existing definitions are skipped. For differing names, choose keep existing, keep both under a new name, or use imported as a new version (history retained). --on-conflict supplies an explicit automation policy; --yes only approves final publication. Schedules may activate; no run history is imported.",
"new": "Create an optional template copy or a one-stage starter. Opens the configured default harness; --harness opencode|pi|nvim overrides it. No submission is performed.",
"edit": "Omit the name to open fuzzy selection. Original immutable source is copied to a private draft. The configured harness edits that draft, never the live definition.",
"validate": "Uses the same server parser as submission. Does not persist or activate schedules. Structural validity does not prove runtime/tool availability.",
"submit": "Confirm publication at the prompt, or use --yes for explicit automation; schedules activate on acceptance. Managed drafts provide the name and base-version guard. --force never bypasses validation.",
"run": "Runs in your current directory after action confirmation (--yes skips it). Select a pipeline and compose a multiline task with Ctrl+S. Stage tools are enabled automatically; no file list or typed RUN confirmation. Cancellation does not undo edits. --title sets an explicit run title; without it the title is derived from the prompt. In JSON mode --wait polls until terminal; --wait-timeout bounds only the client wait after admission and is independent of per-request --timeout. A reached wait limit leaves the run active: inspect read-only with `inspect <run-id> --json`, or reattach with --wait reusing the original --request-key (never an automatic replay or cancel).",
"retry": "Start a new attempt of a failed run with the same initial input, directory, pipeline version, and edit scope. Original history is retained. Already-completed side effects are not undone. --wait/--wait-timeout behave as for run: a reached wait limit leaves the new run active; inspect read-only with `inspect <run-id> --json`, or reattach with --wait and the original --request-key instead of starting a duplicate retry.",
"title": "Rename a run's operator-facing title after the fact without touching its input, steps or execution. The title is collapsed to a single bounded line and recorded as explicitly set. `pipelines runs` and `pipelines inspect` then show it.",
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
"debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.",
"rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs.",
"version": "Identify the local CLI binary without connecting to a server. --version is an alias. Use ping --json to identify the running server separately.",
"ping": "Pong includes the running server's compiled build.version, build.commit and build.dirty (null when unknown). This identifies the server, not the client or runtime workspace. Older servers omit build. The client compares its own build/protocol against the server: a same-protocol build mismatch prints one warning to stderr, a server speaking a newer protocol fails the command, and a response carrying a field this client does not model prints a one-time unrecognized-field notice instead of dropping it silently.",
"connection": "Prints the server endpoint and phone notification endpoints. Like ping, it reports the client/server build relationship and warns or fails rather than silently proceeding against a mismatched server.",
"status": "Reports server, host and ntfy publishing health. The client compares its build/protocol against the server and warns once (or fails on a newer protocol) rather than proceeding silently.",
"export": "Without a name, select pipelines with Space and save a ZIP in the current directory. --output writes a portable definition bundle; --all skips selection. One name without --output prints Markdown as before. No runs, credentials or old versions are exported.",
"import": "Select definitions from a ZIP. Identical existing definitions are skipped. For differing names, choose keep existing, keep both under a new name, or use imported as a new version (history retained). --on-conflict supplies an explicit automation policy; --yes only approves final publication. Schedules may activate; no run history is imported.",
"new": "Create an optional template copy or a one-stage starter. Opens the configured default harness; --harness opencode|pi|nvim overrides it. No submission is performed.",
"edit": "Omit the name to open fuzzy selection. Original immutable source is copied to a private draft. The configured harness edits that draft, never the live definition.",
"validate": "Uses the same server parser as submission. Does not persist or activate schedules. Structural validity does not prove runtime/tool availability.",
"submit": "Confirm publication at the prompt, or use --yes for explicit automation; schedules activate on acceptance. Managed drafts provide the name and base-version guard. --force never bypasses validation.",
"run": "Runs in your current directory after action confirmation (--yes skips it). Select a pipeline and compose a multiline task with Ctrl+S. Stage tools are enabled automatically; no file list or typed RUN confirmation. Cancellation does not undo edits. --title sets an explicit run title; without it the title is derived from the prompt. In JSON mode --wait polls until terminal; --wait-timeout bounds only the client wait after admission and is independent of per-request --timeout. A reached wait limit leaves the run active: inspect read-only with `inspect <run-id> --json`, or reattach with --wait reusing the original --request-key (never an automatic replay or cancel).",
"retry": "Start a new attempt of a failed run with the same initial input, directory, pipeline version, and edit scope. Original history is retained. Already-completed side effects are not undone. --wait/--wait-timeout behave as for run: a reached wait limit leaves the new run active; inspect read-only with `inspect <run-id> --json`, or reattach with --wait and the original --request-key instead of starting a duplicate retry.",
"title": "Rename a run's operator-facing title after the fact without touching its input, steps or execution. The title is collapsed to a single bounded line and recorded as explicitly set. `pipelines runs` and `pipelines inspect` then show it.",
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
"debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.",
"rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs. The omni-search command is `search` (fields query, optional kind and limit) and answers with ranked `search_results`.",
}
var serviceHelp = map[string]string{
+8
View File
@@ -67,4 +67,12 @@ when a checkout is linked) edits a private draft; nvim remains a client editor.
Nothing is published automatically.
Every submission is validated server-side. Submission activates any schedules.
JSON mode never launches an editor or picker; supply explicit arguments.
Search: the TUI '/' popup and the protocol 'search' command (via 'pipelines rpc')
find pipelines, versions, runs, stages/visits, artifact names and the text of stage
inputs, outputs and evidence. A bare status word (queued, running, succeeded,
failed, canceled, interrupted) or a date (today, yesterday, this week, or
YYYY-MM-DD interpreted in UTC) selects runs. A leading prefix pipeline:, version:,
run:, step:, field:, artifact: or match: (a field alias) narrows the result kind;
unrecognised words stay text.
`
+104
View File
@@ -0,0 +1,104 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"fmt"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/buildinfo"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/wstest"
)
func TestCLIWarnsOnceOnDifferingBuildAndKeepsJSONParseable(t *testing.T) {
server := buildinfo.Info{Version: "v0-stale-server", Commit: "deadbeef"}
endpoint := wstest.Server(t, func(protocol.Message) protocol.Message {
return protocol.Message{Type: protocol.Pong, Build: &server, Protocol: protocol.ProtocolVersion}
})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
var out, errOut bytes.Buffer
app := App{Out: &out, Err: &errOut, In: strings.NewReader("")}
if err := app.Run(ctx, []string{"--url", endpoint, "ping", "--json"}); err != nil {
t.Fatal(err)
}
// stdout must stay valid JSON.
var decoded protocol.Message
if err := json.Unmarshal(out.Bytes(), &decoded); err != nil {
t.Fatalf("stdout is not parseable JSON: %v\n%s", err, out.String())
}
if decoded.Build == nil || decoded.Build.Version != server.Version {
t.Fatalf("stdout lost the server build: %+v", decoded.Build)
}
warnings := 0
for _, line := range strings.Split(strings.TrimSpace(errOut.String()), "\n") {
if strings.HasPrefix(line, "warning:") {
warnings++
client := buildinfo.Current()
for _, needle := range []string{client.Version, server.Version} {
if !strings.Contains(line, needle) {
t.Fatalf("warning %q does not name %q", line, needle)
}
}
}
}
if warnings != 1 {
t.Fatalf("differing build produced %d stderr warnings, want exactly one:\n%s", warnings, errOut.String())
}
t.Logf("stdout:\n%s", out.String())
t.Logf("stderr:\n%s", strings.TrimSpace(errOut.String()))
// Human ping prints the relationship too, without hiding the server build.
var humanOut, humanErr bytes.Buffer
human := App{Out: &humanOut, Err: &humanErr, In: strings.NewReader("")}
if err := human.Run(ctx, []string{"--url", endpoint, "ping"}); err != nil {
t.Fatal(err)
}
if !strings.Contains(humanOut.String(), "Note:") || !strings.Contains(humanOut.String(), server.Version) {
t.Fatalf("human ping omitted the client/server relationship:\n%s", humanOut.String())
}
}
func TestCLINoticesUnmodeledFieldInsteadOfDroppingIt(t *testing.T) {
payload := map[string]any{"type": protocol.Pong, "future_field": true}
payload["build"] = buildinfo.Current()
payload["protocol"] = protocol.ProtocolVersion
endpoint := wstest.Raw(t, func(protocol.Message) map[string]any { return payload })
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
var out, errOut bytes.Buffer
app := App{Out: &out, Err: &errOut, In: strings.NewReader("")}
if err := app.Run(ctx, []string{"--url", endpoint, "ping"}); err != nil {
t.Fatal(err)
}
if !strings.Contains(errOut.String(), "future_field") || !strings.Contains(errOut.String(), "unrecognized") {
t.Fatalf("unmodeled field was silent: stderr=%q stdout=%q", errOut.String(), out.String())
}
t.Logf("stderr:\n%s", strings.TrimSpace(errOut.String()))
}
func TestCLIRefusesNewerServerProtocol(t *testing.T) {
server := buildinfo.Info{Version: "v9-future-server", Commit: "deadbeef"}
endpoint := wstest.Server(t, func(protocol.Message) protocol.Message {
return protocol.Message{Type: protocol.Pong, Build: &server, Protocol: protocol.ProtocolVersion + 7}
})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
var out, errOut bytes.Buffer
app := App{Out: &out, Err: &errOut, In: strings.NewReader("")}
err := app.Run(ctx, []string{"--url", endpoint, "ping", "--json"})
if err == nil {
t.Fatal("a newer server protocol did not fail the command")
}
client := buildinfo.Current()
for _, needle := range []string{client.Version, server.Version, fmt.Sprint(protocol.ProtocolVersion + 7), fmt.Sprint(protocol.ProtocolVersion)} {
if !strings.Contains(err.Error(), needle) {
t.Fatalf("refusal %q does not name %q", err.Error(), needle)
}
}
t.Logf("exit error: %v", err)
}
+115 -6
View File
@@ -4,10 +4,13 @@ package client
import (
"context"
"encoding/json"
"fmt"
"strconv"
"strings"
"sync"
"git.a-wan.net/alan/pipelines/internal/buildinfo"
"git.a-wan.net/alan/pipelines/internal/protocol"
"github.com/coder/websocket"
"github.com/coder/websocket/wsjson"
@@ -27,16 +30,106 @@ func Send(ctx context.Context, conn *websocket.Conn, request protocol.Message) e
return wsjson.Write(ctx, conn, request)
}
func Receive(ctx context.Context, conn *websocket.Conn) (protocol.Message, error) {
// Reporter receives a build/protocol relationship notice for display. It is
// called at most once per distinct notice on a connection.
type Reporter func(buildinfo.Relationship)
// Watch compares each received frame with this client build and records the
// once-only identity and unrecognized-field notices for one server connection.
// The zero value is ready to use; a nil Watch reports every warning unfiltered.
type Watch struct {
mu sync.Mutex
identityReported bool
unknownReported bool
}
// Observe classifies one received frame. It returns the notices that have not
// already been shown on this connection and, when the server speaks a newer
// protocol than this client interprets, an error naming both builds and both
// protocols so the caller must not act on the frame.
func (w *Watch) Observe(data []byte, response protocol.Message) ([]buildinfo.Relationship, error) {
client := buildinfo.Current()
relation := buildinfo.Compare(client, protocol.MaxSupportedProtocol, response.Protocol, response.Build)
if relation.Severity == buildinfo.Refuse {
return nil, fmt.Errorf("%s", relation.Message)
}
if w == nil {
if relation.Severity == buildinfo.Warn {
return []buildinfo.Relationship{relation}, nil
}
return nil, nil
}
w.mu.Lock()
defer w.mu.Unlock()
var notices []buildinfo.Relationship
if relation.Severity == buildinfo.Warn && !w.identityReported {
w.identityReported = true
notices = append(notices, relation)
}
// A top-level key this client does not model would otherwise be dropped
// silently: report the mismatch once instead of appearing to have no data.
if unknown := protocol.UnknownFields(data); len(unknown) > 0 && !w.unknownReported {
w.unknownReported = true
notices = append(notices, buildinfo.Relationship{
Severity: buildinfo.Warn,
Message: fmt.Sprintf(
"server sent unrecognized top-level field(s) %s; this client may be older than the server (client build %s)",
strings.Join(unknown, ", "), buildinfo.Describe(&client)),
})
}
return notices, nil
}
// read reads one text frame and decodes it, keeping the raw bytes so unmodeled
// top-level keys can be detected without a second decode.
func read(ctx context.Context, conn *websocket.Conn) (protocol.Message, []byte, error) {
kind, data, err := conn.Read(ctx)
if err != nil {
return protocol.Message{}, nil, err
}
if kind != websocket.MessageText {
return protocol.Message{}, data, fmt.Errorf("unexpected websocket message type %d", kind)
}
var response protocol.Message
err := wsjson.Read(ctx, conn, &response)
if err := json.Unmarshal(data, &response); err != nil {
return protocol.Message{}, data, err
}
return response, data, nil
}
// ReceiveNotice reads and decodes one frame, returning the once-only
// identity/unrecognized-field notices for display. A non-nil error means the
// frame must not be used: an unsafe newer server, or a transport/decode failure.
func ReceiveNotice(ctx context.Context, conn *websocket.Conn, watch *Watch) (protocol.Message, []string, error) {
response, data, err := read(ctx, conn)
if err != nil {
return response, nil, err
}
relations, err := watch.Observe(data, response)
notices := make([]string, 0, len(relations))
for _, relation := range relations {
if relation.Message != "" {
notices = append(notices, relation.Message)
}
}
return response, notices, err
}
// Receive reads and decodes one frame without reporting its identity. Most
// callers should use ReceiveNotice so an older or newer server is never silent.
func Receive(ctx context.Context, conn *websocket.Conn) (protocol.Message, error) {
response, _, err := ReceiveNotice(ctx, conn, nil)
return response, err
}
type Client struct {
Conn *websocket.Conn
mu sync.Mutex
next uint64
Conn *websocket.Conn
mu sync.Mutex
next uint64
watch Watch
reportMu sync.Mutex
report Reporter
}
func Open(ctx context.Context, url string) (*Client, error) {
@@ -49,6 +142,14 @@ func Open(ctx context.Context, url string) (*Client, error) {
func (c *Client) Close() { c.Conn.CloseNow() }
// Report installs the notice reporter used by Call. Set it once after Open and
// before the first Call; a nil reporter still fails on an unsafe newer server.
func (c *Client) Report(report Reporter) {
c.reportMu.Lock()
c.report = report
c.reportMu.Unlock()
}
// Call serializes request/reply pairs, skipping the unsolicited welcome envelope.
func (c *Client) Call(ctx context.Context, request protocol.Message) (protocol.Message, error) {
c.mu.Lock()
@@ -59,7 +160,15 @@ func (c *Client) Call(ctx context.Context, request protocol.Message) (protocol.M
return protocol.Message{}, err
}
for {
response, err := Receive(ctx, c.Conn)
response, notices, err := ReceiveNotice(ctx, c.Conn, &c.watch)
for _, notice := range notices {
c.reportMu.Lock()
report := c.report
c.reportMu.Unlock()
if report != nil {
report(buildinfo.Relationship{Severity: buildinfo.Warn, Message: notice})
}
}
if err != nil {
return response, err
}
+128
View File
@@ -0,0 +1,128 @@
package client
import (
"context"
"fmt"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/buildinfo"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/wstest"
)
func TestCallRefusesNewerServerProtocol(t *testing.T) {
server := buildinfo.Info{Version: "v9-server", Commit: "deadbeef"}
endpoint := wstest.Server(t, func(protocol.Message) protocol.Message {
return protocol.Message{Type: protocol.Pong, Build: &server, Protocol: protocol.ProtocolVersion + 5}
})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
c, err := Open(ctx, endpoint)
if err != nil {
t.Fatal(err)
}
defer c.Close()
var warnings int
c.Report(func(buildinfo.Relationship) { warnings++ })
_, err = c.Call(ctx, protocol.Message{Type: protocol.Ping})
if err == nil {
t.Fatal("newer server protocol was not refused")
}
client := buildinfo.Current()
for _, needle := range []string{client.Version, server.Version, fmt.Sprint(protocol.ProtocolVersion + 5), fmt.Sprint(protocol.ProtocolVersion)} {
if !strings.Contains(err.Error(), needle) {
t.Fatalf("refusal %q does not name %q", err.Error(), needle)
}
}
if warnings != 0 {
t.Fatalf("refusal reported %d warnings instead of failing fast", warnings)
}
}
func TestCallWarnsOnceOnDifferingBuild(t *testing.T) {
server := buildinfo.Info{Version: "v0-older-server", Commit: "deadbeef"}
endpoint := wstest.Server(t, func(protocol.Message) protocol.Message {
return protocol.Message{Type: protocol.Pong, Build: &server, Protocol: protocol.ProtocolVersion}
})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
c, err := Open(ctx, endpoint)
if err != nil {
t.Fatal(err)
}
defer c.Close()
var messages []string
c.Report(func(relationship buildinfo.Relationship) { messages = append(messages, relationship.Message) })
for i := 0; i < 3; i++ {
if _, err := c.Call(ctx, protocol.Message{Type: protocol.Ping}); err != nil {
t.Fatal(err)
}
}
if len(messages) != 1 {
t.Fatalf("differing build reported %d notices, want exactly one: %v", len(messages), messages)
}
client := buildinfo.Current()
for _, needle := range []string{client.Version, server.Version} {
if !strings.Contains(messages[0], needle) {
t.Fatalf("warning %q does not name %q", messages[0], needle)
}
}
}
func TestCallReportsUnmodeledFieldOnce(t *testing.T) {
payload := map[string]any{"type": protocol.Pong, "future_field": true, "another": 2}
client := buildinfo.Current()
payload["build"] = client
payload["protocol"] = protocol.ProtocolVersion
endpoint := wstest.Raw(t, func(protocol.Message) map[string]any { return payload })
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
c, err := Open(ctx, endpoint)
if err != nil {
t.Fatal(err)
}
defer c.Close()
var notices []string
c.Report(func(relationship buildinfo.Relationship) { notices = append(notices, relationship.Message) })
for i := 0; i < 2; i++ {
response, err := c.Call(ctx, protocol.Message{Type: protocol.Ping})
if err != nil {
t.Fatal(err)
}
if response.Type != protocol.Pong {
t.Fatalf("unexpected response %+v", response)
}
}
if len(notices) != 1 {
t.Fatalf("unmodeled fields reported %d notices, want one: %v", len(notices), notices)
}
for _, needle := range []string{"another", "future_field", "unrecognized"} {
if !strings.Contains(notices[0], needle) {
t.Fatalf("unknown-field notice %q does not name %q", notices[0], needle)
}
}
}
func TestReceiveNoticeDoesNotFlagFullyModeledFrames(t *testing.T) {
endpoint := wstest.Server(t, func(protocol.Message) protocol.Message {
server := buildinfo.Current()
return protocol.Message{Type: protocol.Pong, Build: &server, Protocol: protocol.ProtocolVersion}
})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
c, err := Open(ctx, endpoint)
if err != nil {
t.Fatal(err)
}
defer c.Close()
var notices int
c.Report(func(buildinfo.Relationship) { notices++ })
if _, err := c.Call(ctx, protocol.Message{Type: protocol.Ping}); err != nil {
t.Fatal(err)
}
if notices != 0 {
t.Fatalf("an in-sync, fully modeled frame produced %d notices", notices)
}
}
+60
View File
@@ -0,0 +1,60 @@
package protocol
import (
"encoding/json"
"reflect"
"sort"
"strings"
"sync"
)
// ProtocolVersion is the integer wire protocol this build speaks. Ordering
// between peers compares this integer; build strings are for naming only and are
// never parsed or sorted to infer ordering.
const ProtocolVersion = 1
// MaxSupportedProtocol is the newest server protocol this client can interpret.
// A server reporting a higher value is refused rather than silently misread.
const MaxSupportedProtocol = ProtocolVersion
var (
knownFieldsOnce sync.Once
knownFields map[string]struct{}
)
// KnownFields returns the set of top-level JSON keys protocol.Message models,
// derived once from the struct tags and cached. The map is read-only.
func KnownFields() map[string]struct{} {
knownFieldsOnce.Do(func() {
knownFields = map[string]struct{}{}
message := reflect.TypeOf(Message{})
for index := 0; index < message.NumField(); index++ {
name := strings.Split(message.Field(index).Tag.Get("json"), ",")[0]
if name == "" || name == "-" {
continue
}
knownFields[name] = struct{}{}
}
})
return knownFields
}
// UnknownFields returns the sorted top-level JSON keys in data that protocol.Message
// does not model. It performs one bounded map decode plus O(1) set lookups, so a
// forward-compatible frame is never a per-frame reflection walk. A frame that is
// not a JSON object (or cannot be parsed) reports no unknown fields.
func UnknownFields(data []byte) []string {
var raw map[string]json.RawMessage
if err := json.Unmarshal(data, &raw); err != nil {
return nil
}
known := KnownFields()
var unknown []string
for key := range raw {
if _, ok := known[key]; !ok {
unknown = append(unknown, key)
}
}
sort.Strings(unknown)
return unknown
}
+52
View File
@@ -0,0 +1,52 @@
package protocol
import (
"fmt"
"reflect"
"testing"
)
func TestUnknownFieldsReportsOnlyUnmodeledSortedKeys(t *testing.T) {
if got := UnknownFields([]byte(`{"type":"pong"}`)); got != nil {
t.Fatalf("fully modeled frame reported %v", got)
}
got := UnknownFields([]byte(`{"type":"pong","zzz":1,"aaa":2}`))
if !reflect.DeepEqual(got, []string{"aaa", "zzz"}) {
t.Fatalf("unknown fields = %v, want sorted [aaa zzz]", got)
}
}
func TestUnknownFieldsIgnoresMalformedAndNonObjectFrames(t *testing.T) {
for _, data := range []string{
`not json`,
`[1,2,3]`,
`"a string"`,
`42`,
`null`,
} {
if got := UnknownFields([]byte(data)); got != nil {
t.Fatalf("frame %q reported unknown fields %v", data, got)
}
}
}
func TestKnownFieldsCachesTheModeledKeySet(t *testing.T) {
first := KnownFields()
second := KnownFields()
if len(first) == 0 {
t.Fatal("known field set is empty")
}
if _, ok := first["type"]; !ok {
t.Fatal("known field set is missing the modeled type key")
}
if _, ok := first["build"]; !ok {
t.Fatal("known field set is missing the modeled build key")
}
if _, ok := first["protocol"]; !ok {
t.Fatal("known field set is missing the modeled protocol key")
}
// The sync.Once must return the same cached map on every call.
if fmt.Sprintf("%p", first) != fmt.Sprintf("%p", second) {
t.Fatal("KnownFields re-derived the set instead of using the cache")
}
}
+12 -1
View File
@@ -102,10 +102,17 @@ type PipelineSummary struct {
UpdatedAt string `json:"updated_at"`
}
// Message is the JSON envelope shared by the server and client.
// Message is the JSON envelope shared by the server and client. It also carries
// the omni-search request/response: a client sends Type "search" with an ID, the
// Query text, an optional Kind type filter and an optional Limit, and the server
// replies with Type "search_results", the echoed ID and ranked Matches. Every
// SearchMatch carries a stable Target plus the label and per-kind evidence; all
// search fields are optional so older peers ignore them. See search.go for the
// kind constants and wire-shape detail.
type Message struct {
DefaultHarness string `json:"default_harness,omitempty"`
Build *buildinfo.Info `json:"build,omitempty"`
Protocol int `json:"protocol,omitempty"`
DefaultModel string `json:"default_model,omitempty"`
Evidence []SessionEvidence `json:"evidence,omitempty"`
Usage *UsageStats `json:"usage,omitempty"`
@@ -123,6 +130,8 @@ type Message struct {
Source string `json:"source,omitempty"`
Title string `json:"title,omitempty"`
Version int `json:"version,omitempty"`
Query string `json:"query,omitempty"`
Kind string `json:"kind,omitempty"`
Pipelines []PipelineSummary `json:"pipelines,omitempty"`
PipelineID int64 `json:"pipeline_id,omitempty"`
Detail *PipelineDetail `json:"detail,omitempty"`
@@ -132,11 +141,13 @@ type Message struct {
Stage string `json:"stage,omitempty"`
Option string `json:"option,omitempty"`
Feedback string `json:"feedback,omitempty"`
Matches []SearchMatch `json:"matches,omitempty"`
Input map[string]any `json:"input,omitempty"`
AllowTools bool `json:"allow_tools,omitempty"`
WritePaths []string `json:"write_paths,omitempty"`
RequestKey string `json:"request_key,omitempty"`
Workspace string `json:"workspace,omitempty"`
Limit int `json:"limit,omitempty"`
// Chat is the brokered OpenCode chat traffic (route B). See chat.go for the
// per-type payload structs and the wire shapes they mirror.
ChatSessions []ChatSession `json:"chat_sessions,omitempty"`
+19 -1
View File
@@ -112,6 +112,16 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
defer connCancel()
var writeMu sync.Mutex
write := func(message protocol.Message) error {
// Every server frame (responses, the welcome and chat events) carries
// the build identity and protocol so an older client fails fast or
// warns once instead of silently misreading a field. build is
// computed once per handler.
if message.Build == nil {
message.Build = &build
}
if message.Protocol == 0 {
message.Protocol = protocol.ProtocolVersion
}
writeMu.Lock()
defer writeMu.Unlock()
writeCtx, cancel := context.WithTimeout(connCtx, 5*time.Second)
@@ -149,7 +159,6 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
response.Status = systemStatus(r, started, runErr)
} else if request.Type == protocol.Ping {
response.Time = time.Now().UTC().Format(time.RFC3339)
response.Build = &build
} else if request.Type == protocol.ListTemplates {
response.Type = protocol.Templates
response.Templates = examples.Catalog()
@@ -208,6 +217,15 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
} else {
response.Pipelines = items
}
} else if request.Type == protocol.Search && len(stores) > 0 && runs != nil {
response.Type = protocol.SearchResults
matches, err := runs.search(request)
if err != nil {
response.Type = protocol.Error
response.Error = err.Error()
} else {
response.Matches = matches
}
} else if runs != nil && (request.Type == protocol.RunPipeline || request.Type == protocol.RetryRun || request.Type == protocol.ListRuns || request.Type == protocol.GetRun || request.Type == protocol.CancelRun || request.Type == protocol.DecideRun || request.Type == protocol.SetRunTitle || request.Type == protocol.GetRunEvidence) {
var err error
switch request.Type {
+40
View File
@@ -5,6 +5,7 @@ import (
"context"
"log"
"net/http/httptest"
"path/filepath"
"strings"
"sync"
"testing"
@@ -14,6 +15,7 @@ import (
"github.com/coder/websocket/wsjson"
"git.a-wan.net/alan/pipelines/internal/buildinfo"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
@@ -77,6 +79,9 @@ func TestPersistentConnection(t *testing.T) {
if response.Build == nil || response.Build.Version != wantBuild.Version || response.Build.Commit != wantBuild.Commit {
t.Fatalf("pong missing server build identity: %+v", response.Build)
}
if response.Protocol != protocol.ProtocolVersion {
t.Fatalf("pong protocol = %d, want %d", response.Protocol, protocol.ProtocolVersion)
}
stamp, err := time.Parse(time.RFC3339, response.Time)
if err != nil {
t.Fatal(err)
@@ -97,3 +102,38 @@ func TestPersistentConnection(t *testing.T) {
}
}
}
// TestWelcomeEnvelopeCarriesServerIdentity proves a client that never pings
// still learns the server build and protocol from the unsolicited welcome.
func TestWelcomeEnvelopeCarriesServerIdentity(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
store, err := pipeline.Open(filepath.Join(t.TempDir(), "identity.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
handler := Handler(ctx, store)
srv := httptest.NewServer(handler)
defer srv.Close()
defer func() { cancel(); WaitRuns(handler) }()
conn, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(srv.URL, "http")+"/connect", nil)
if err != nil {
t.Fatal(err)
}
defer conn.CloseNow()
var welcome protocol.Message
if err := wsjson.Read(ctx, conn, &welcome); err != nil {
t.Fatal(err)
}
if welcome.Type != protocol.PipelineList {
t.Fatalf("first frame = %q, want welcome pipelines list", welcome.Type)
}
wantBuild := buildinfo.Current()
if welcome.Build == nil || welcome.Build.Version != wantBuild.Version || welcome.Build.Commit != wantBuild.Commit {
t.Fatalf("welcome missing server build identity: %+v", welcome.Build)
}
if welcome.Protocol != protocol.ProtocolVersion {
t.Fatalf("welcome protocol = %d, want %d", welcome.Protocol, protocol.ProtocolVersion)
}
}
+6 -3
View File
@@ -15,8 +15,9 @@ import (
)
type draftValidationMsg struct {
path string
err error
path string
notices []string
err error
}
func (m Model) openDrafts() (tea.Model, tea.Cmd) {
@@ -157,8 +158,10 @@ func (m Model) updateDrafts(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
return draftValidationMsg{path: d.Path, err: err}
}
defer c.Close()
sink := &noticeSink{}
c.Report(sink.report)
_, err = c.Call(ctx, protocol.Message{Type: protocol.Validate, Source: source})
return draftValidationMsg{path: d.Path, err: err}
return draftValidationMsg{path: d.Path, notices: sink.drain(), err: err}
}
}
}
+50 -36
View File
@@ -16,71 +16,85 @@ type editorPublicationMsg struct {
pipelines []protocol.PipelineSummary
detail *protocol.PipelineDetail
published bool
notices []string
err error
}
func checkEditorPublication(ctx context.Context, endpoint string, edit editedMsg, generation uint64) tea.Cmd {
return func() tea.Msg {
result := editorPublicationMsg{edit: edit, generation: generation}
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
c, err := client.Open(ctx, endpoint)
return publicationCheck(ctx, endpoint, edit, generation)
}
}
// publicationCheck runs the publication comparison for one editor submission.
// The named result lets the deferred hook attach any build/protocol notices
// from the short-lived client to every return path.
func publicationCheck(ctx context.Context, endpoint string, edit editedMsg, generation uint64) (result editorPublicationMsg) {
result = editorPublicationMsg{edit: edit, generation: generation}
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
c, err := client.Open(ctx, endpoint)
if err != nil {
result.err = err
return result
}
defer c.Close()
sink := &noticeSink{}
c.Report(sink.report)
// Surface any build/protocol notice through the shared TUI notice path
// rather than dropping it for this short-lived client.
defer func() { result.notices = sink.drain() }()
list, err := c.Call(ctx, protocol.Message{Type: protocol.List})
if err != nil {
result.err = err
return result
}
result.pipelines = list.Pipelines
for _, p := range list.Pipelines {
if p.Name != strings.TrimSpace(edit.name) {
continue
}
response, err := c.Call(ctx, protocol.Message{Type: protocol.GetPipeline, PipelineID: p.ID})
if err != nil {
result.err = err
return result
}
defer c.Close()
list, err := c.Call(ctx, protocol.Message{Type: protocol.List})
if err != nil {
result.err = err
result.detail = response.Detail
if result.detail == nil {
result.err = fmt.Errorf("server returned no pipeline detail")
return result
}
result.pipelines = list.Pipelines
for _, p := range list.Pipelines {
if p.Name != strings.TrimSpace(edit.name) {
if result.detail.Source == edit.source {
result.published = true
return result
}
// If another version was published afterward, the editor's submitted
// source still must not be offered for duplicate submission. Only
// inspect versions newer than this draft's immutable starting point.
for _, v := range result.detail.Versions {
if v.Version <= edit.baseVersion || v.Version == result.detail.Version {
continue
}
response, err := c.Call(ctx, protocol.Message{Type: protocol.GetPipeline, PipelineID: p.ID})
response, err := c.Call(ctx, protocol.Message{Type: protocol.GetPipeline, PipelineID: p.ID, Version: v.Version})
if err != nil {
result.err = err
return result
}
result.detail = response.Detail
if result.detail == nil {
result.err = fmt.Errorf("server returned no pipeline detail")
return result
}
if result.detail.Source == edit.source {
if response.Detail != nil && response.Detail.Source == edit.source {
result.published = true
return result
}
// If another version was published afterward, the editor's submitted
// source still must not be offered for duplicate submission. Only
// inspect versions newer than this draft's immutable starting point.
for _, v := range result.detail.Versions {
if v.Version <= edit.baseVersion || v.Version == result.detail.Version {
continue
}
response, err := c.Call(ctx, protocol.Message{Type: protocol.GetPipeline, PipelineID: p.ID, Version: v.Version})
if err != nil {
result.err = err
return result
}
if response.Detail != nil && response.Detail.Source == edit.source {
result.published = true
return result
}
}
return result
}
return result
}
return result
}
func (m Model) finishEditorPublication(msg editorPublicationMsg) (tea.Model, tea.Cmd) {
if msg.generation != m.editorCheckGeneration {
return m, nil
}
m.appendNotices(msg.notices)
m.editorChecking = false
if msg.err == nil {
m.pipelines = msg.pipelines
+32
View File
@@ -2,8 +2,11 @@ package tui
import (
"context"
"git.a-wan.net/alan/pipelines/internal/buildinfo"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/server"
"git.a-wan.net/alan/pipelines/internal/wstest"
"net/http/httptest"
"path/filepath"
"strings"
@@ -11,6 +14,35 @@ import (
"time"
)
// TestEditorPublicationSurfacesBuildMismatchNotice proves a short-lived TUI
// command client routes its build/protocol notice through the shared notice
// path instead of dropping it (the artifacts-field regression).
func TestEditorPublicationSurfacesBuildMismatchNotice(t *testing.T) {
stale := buildinfo.Info{Version: "v0-stale-server", Commit: "deadbeef"}
endpoint := wstest.Server(t, func(request protocol.Message) protocol.Message {
switch request.Type {
case protocol.List:
return protocol.Message{Type: protocol.List, Build: &stale, Protocol: protocol.ProtocolVersion,
Pipelines: []protocol.PipelineSummary{{ID: 7, Name: "test", Version: 1}}}
case protocol.GetPipeline:
return protocol.Message{Type: protocol.GetPipeline,
Detail: &protocol.PipelineDetail{PipelineSummary: protocol.PipelineSummary{ID: 7, Name: "test", Version: 1}, Source: "published"}}
}
return protocol.Message{Type: protocol.Pong}
})
edit := editedMsg{name: "test", source: "published", baseVersion: 0}
result := publicationCheck(context.Background(), endpoint, edit, 0)
if len(result.notices) != 1 {
t.Fatalf("short-lived client dropped the build mismatch notice: %+v", result.notices)
}
m := New(context.Background(), endpoint)
updated, _ := m.finishEditorPublication(result)
m = updated.(Model)
if !strings.Contains(strings.Join(m.lines, "\n"), "warning:") {
t.Fatalf("notice not routed to the shared TUI notice path: %q", m.lines)
}
}
func TestEditorReturnFindsPublishedVersionAndReloadsLatest(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
+57 -9
View File
@@ -24,7 +24,10 @@ import (
"git.a-wan.net/alan/pipelines/internal/protocol"
)
type connectedMsg struct{ conn *websocket.Conn }
type connectedMsg struct {
conn *websocket.Conn
watch *client.Watch
}
type receivedMsg protocol.Message
type sentMsg struct{ id string }
type errorMsg struct {
@@ -34,6 +37,7 @@ type errorMsg struct {
type socketMsg struct {
conn *websocket.Conn
message protocol.Message
notices []string
}
type reconnectMsg struct{}
@@ -109,6 +113,7 @@ type Model struct {
ctx context.Context
url string
conn *websocket.Conn
watch *client.Watch
status string
nextID uint64
lines []string
@@ -129,6 +134,12 @@ type Model struct {
commandIndex int
homeTop int
searchOpen bool
searchResults []protocol.SearchMatch
searchRequest string
searchInFlight bool
searchQueued bool
searchError string
pendingRunNav *searchNav
detail *protocol.PipelineDetail
detailRequest string
detailLoading bool
@@ -216,7 +227,7 @@ func New(ctx context.Context, url string) Model {
runSpinner: spinner.New(spinner.WithSpinner(spinner.Spinner{Frames: []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"}, FPS: time.Second / 12}), spinner.WithStyle(lipgloss.NewStyle().Foreground(themeAccent))),
keys: keyMap{
commands: key.NewBinding(key.WithKeys(":"), key.WithHelp(":", "commands")),
search: key.NewBinding(key.WithKeys("/"), key.WithHelp("/", "search")),
search: key.NewBinding(key.WithKeys("/"), key.WithHelp("/", "omni search")),
create: key.NewBinding(key.WithKeys("n"), key.WithHelp("n", "new pipeline")),
enter: key.NewBinding(key.WithKeys("enter"), key.WithHelp("enter", "continue")),
cancel: key.NewBinding(key.WithKeys("esc"), key.WithHelp("esc", "cancel")),
@@ -243,17 +254,17 @@ func (m Model) connect() tea.Cmd {
<-m.ctx.Done()
conn.CloseNow()
}()
return connectedMsg{conn}
return connectedMsg{conn: conn, watch: &client.Watch{}}
}
}
func (m Model) read() tea.Cmd {
return func() tea.Msg {
response, err := client.Receive(m.ctx, m.conn)
response, notices, err := client.ReceiveNotice(m.ctx, m.conn, m.watch)
if err != nil {
return errorMsg{err: err, conn: m.conn}
}
return socketMsg{conn: m.conn, message: response}
return socketMsg{conn: m.conn, message: response, notices: notices}
}
}
@@ -312,6 +323,7 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
m.conn.CloseNow()
}
m.conn = msg.conn
m.watch = msg.watch
m.reconnecting = false
m.status = m.url
if endpoint, err := url.Parse(m.url); err == nil {
@@ -332,6 +344,9 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
if msg.conn != m.conn {
return m, nil
}
// Surface the once-only identity/unrecognized-field notices on the same
// connection without corrupting the TUI layout.
m.appendNotices(msg.notices)
return m.Update(receivedMsg(msg.message))
case receivedMsg:
if msg.Type == protocol.Status && msg.ID == m.statusRequest {
@@ -344,6 +359,21 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
m.statusError = msg.Error
m.statusRequest = ""
}
if msg.Type == protocol.SearchResults {
if msg.ID == m.searchRequest {
m.searchInFlight = false
m.searchResults = msg.Matches
m.searchError = ""
m.commandIndex = min(m.commandIndex, max(0, len(msg.Matches)-1))
if m.searchQueued {
m.searchQueued = false
updated, cmd := m.requestSearch()
m = updated.(Model)
return m, tea.Batch(m.read(), cmd)
}
}
return m, m.read()
}
if msg.Type == protocol.PipelineList || msg.Type == protocol.Submitted {
m.notificationEndpoints = msg.NotificationEndpoints
if msg.DefaultModel != "" {
@@ -377,6 +407,11 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
m.requestedRunID = msg.RunDetail.ID
m.runError = ""
m.runStepIndex = min(m.runStepIndex, len(msg.RunDetail.Steps))
if m.pendingRunNav != nil && m.pendingRunNav.runID == msg.RunDetail.ID {
nav := *m.pendingRunNav
m.pendingRunNav = nil
m.applyRunNav(nav)
}
}
} else if msg.Type == protocol.Pong {
m.appendLine(fmt.Sprintf("pong #%s: %s", msg.ID, msg.Time))
@@ -403,6 +438,12 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
m.keys.confirm = true
}
}
if msg.ID != "" && msg.ID == m.searchRequest {
m.searchInFlight = false
m.searchQueued = false
m.searchResults = nil
m.searchError = msg.Error
}
} else if msg.Type == protocol.Submitted {
m.templateConfirm = false
m.draftOpen = false
@@ -467,6 +508,7 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
}
return m, m.read()
case draftValidationMsg:
m.appendNotices(msg.notices)
if len(m.draftItems) > 0 && m.draftItems[m.draftIndex].Path == msg.path {
m.draftError = "Validation passed (structure only)."
if msg.err != nil {
@@ -527,6 +569,10 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
m.detailRequest = ""
m.detailLoading = m.keys.detail && m.requestedPipelineID > 0
m.submitID = ""
m.searchRequest = ""
m.searchInFlight = false
m.searchQueued = false
m.searchError = ""
if m.pendingDraft != nil {
m.submitNotice = "Connection lost; submission outcome unknown. Draft retained."
}
@@ -620,11 +666,13 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
m.commandIndex = 0
m.commandInput = newInput()
if m.searchOpen {
m.commandInput.Placeholder = "Search pipelines…"
} else {
m.commandInput.Placeholder = ":logs"
m.commandInput.SetValue(":")
m.searchResults = nil
m.searchError = ""
m.commandInput.Placeholder = "Type to search…"
return m, m.commandInput.Focus()
}
m.commandInput.Placeholder = ":logs"
m.commandInput.SetValue(":")
return m, m.commandInput.Focus()
case m.homePage() && key.Matches(msg, m.keys.create):
if m.conn == nil {
+44
View File
@@ -0,0 +1,44 @@
package tui
import (
"sync"
"git.a-wan.net/alan/pipelines/internal/buildinfo"
)
// noticeSink collects build/protocol notices from a short-lived client so a TUI
// command can surface them through the shared notice path instead of dropping
// them. It implements client.Reporter.
type noticeSink struct {
mu sync.Mutex
notices []string
}
func (s *noticeSink) report(relationship buildinfo.Relationship) {
if relationship.Message == "" {
return
}
s.mu.Lock()
s.notices = append(s.notices, relationship.Message)
s.mu.Unlock()
}
// drain returns the notices collected so far and resets the sink.
func (s *noticeSink) drain() []string {
s.mu.Lock()
defer s.mu.Unlock()
notices := s.notices
s.notices = nil
return notices
}
// appendNotices is the single TUI notice path: every server relationship or
// unrecognized-field notice is rendered as one warning line, whether it came
// from the long-lived read loop or a short-lived command client.
func (m *Model) appendNotices(notices []string) {
for _, notice := range notices {
if notice != "" {
m.appendLine("warning: " + notice)
}
}
}
+60
View File
@@ -0,0 +1,60 @@
// Package wstest provides the small websocket echo server shared by the client
// and CLI identity tests, so the request/reply harness is defined once.
package wstest
import (
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/coder/websocket"
"github.com/coder/websocket/wsjson"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// Server starts a websocket endpoint that answers every request with
// reply(request), echoing the request ID, and returns the client URL.
func Server(t testing.TB, reply func(protocol.Message) protocol.Message) string {
t.Helper()
return serve(t, func(request protocol.Message) any {
response := reply(request)
response.ID = request.ID
return response
})
}
// Raw starts a websocket endpoint that answers every request with a JSON object
// from payload(request), with "id" set to the request ID, so tests can include
// top-level keys the client does not model.
func Raw(t testing.TB, payload func(protocol.Message) map[string]any) string {
t.Helper()
return serve(t, func(request protocol.Message) any {
body := payload(request)
body["id"] = request.ID
return body
})
}
func serve(t testing.TB, reply func(protocol.Message) any) string {
t.Helper()
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
conn, err := websocket.Accept(w, r, nil)
if err != nil {
return
}
defer conn.CloseNow()
for {
var request protocol.Message
if err := wsjson.Read(r.Context(), conn, &request); err != nil {
return
}
if err := wsjson.Write(r.Context(), conn, reply(request)); err != nil {
return
}
}
}))
t.Cleanup(srv.Close)
return "ws" + strings.TrimPrefix(srv.URL, "http") + "/connect"
}
+56
View File
@@ -203,6 +203,61 @@ class Setup:
if result.returncode:
raise ValueError(f"go build failed for ./cmd/{command}; the native install is incomplete")
# --- stale-CLI-on-PATH guard -----------------------------------------
def check_path_shadow(self, prefix):
"""Warn when a different ``pipelines`` earlier on PATH shadows this install.
Detection is read-only and bounded: one ``shutil.which`` check plus one
bounded ``version --json`` read per binary. The installer never modifies,
moves, deletes or upgrades the other binary; it only names the shadowing
path and both versions so an older CLI is not used silently in front of
the freshly built server. Naming both versions requires reading each
binary once, so a detected shadow costs exactly two short, read-only
subprocesses (none when the prefix binary is the one PATH already
resolves). Returns the shadowing path, or None when the prefix binary is
the one PATH resolves.
"""
installed = prefix / "bin/pipelines"
found = shutil.which("pipelines")
if not found:
return None
found_path = Path(found).resolve()
try:
if found_path == installed.resolve():
return None
except OSError:
pass
other = self._binary_version(found_path)
current = self._binary_version(installed)
print(
f"WARNING: a different pipelines resolves earlier on PATH than the freshly "
f"installed CLI: {found_path} (version {other}) shadows {installed} "
f"(version {current}); the installer left it untouched. Put {prefix / 'bin'} "
"first on PATH so the CLI matches the running server.")
return found_path
def _binary_version(self, path):
"""Read a binary's ``version --json`` once; never a hot path."""
if not Path(path).is_file():
return "unknown"
try:
result = self.runner([str(path), "version", "--json"], capture_output=True, text=True)
except OSError:
return "unknown"
if result.returncode:
return "unknown"
text = (result.stdout or "").strip()
try:
data = json.loads(text)
except ValueError:
return text or "unknown"
if not isinstance(data, dict):
return "unknown"
version = data.get("version") or "unknown"
commit = data.get("commit")
return f"{version} (commit {commit})" if commit else str(version)
def install_skill(self, prefix):
result = self.runner([str(prefix / "bin/pipelines"), "skill", "install"], cwd=str(self.directory))
if result.returncode:
@@ -453,6 +508,7 @@ class Setup:
else:
resolution = self.resolve_ntfy()
self.build(prefix)
self.check_path_shadow(prefix)
self.install_skill(prefix)
# The native install launches host harnesses, so write host profiles for
# the detected harnesses and clear any Docker-era link. Uses only the
+90
View File
@@ -1,6 +1,8 @@
import importlib.util
import io
import json
import os
from contextlib import redirect_stdout
from pathlib import Path
import subprocess
import tempfile
@@ -410,6 +412,94 @@ class SetupNativeTests(unittest.TestCase):
self.assertTrue(installer._valid_model(saved["profiles"][name]["model"]))
self.assertEqual(saved["profiles"]["opencode"]["executable"], "/usr/bin/opencode")
def _fake_pipelines(self, path, version, commit):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(f'#!/bin/sh\necho \'{{"version":"{version}","commit":"{commit}"}}\'\n')
path.chmod(0o755)
return path
def test_check_path_shadow_warns_naming_path_and_both_versions(self):
with tempfile.TemporaryDirectory() as directory:
directory = Path(directory)
prefix = directory / "prefix"
installed = self._fake_pipelines(prefix / "bin/pipelines", "new-version", "bbbb")
shadow_dir = directory / "earlier"
shadow = self._fake_pipelines(shadow_dir / "pipelines", "old-version", "aaaa")
before = shadow.read_bytes()
installer = setup_native.Setup(directory, prefix=prefix, runner=subprocess.run,
resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", side_effect=lambda name: str(shadow) if name == "pipelines" else None):
output = io.StringIO()
with redirect_stdout(output):
result = installer.check_path_shadow(prefix)
warning = output.getvalue()
self.assertEqual(result, shadow.resolve())
self.assertIn("WARNING", warning)
self.assertIn(str(shadow), warning)
self.assertIn("old-version", warning)
self.assertIn("new-version", warning)
# The shadowing binary is only read; it is never modified or replaced.
self.assertEqual(shadow.read_bytes(), before)
self.assertEqual(installed.read_bytes().count(b"new-version"), 1)
def test_check_path_shadow_is_silent_when_prefix_binary_wins(self):
with tempfile.TemporaryDirectory() as directory:
directory = Path(directory)
prefix = directory / "prefix"
installed = self._fake_pipelines(prefix / "bin/pipelines", "same-version", "cccc")
installer = setup_native.Setup(directory, prefix=prefix, runner=subprocess.run,
resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", return_value=str(installed)):
output = io.StringIO()
with redirect_stdout(output):
result = installer.check_path_shadow(prefix)
self.assertIsNone(result)
self.assertEqual(output.getvalue(), "")
def test_check_path_shadow_is_silent_without_a_path_binary(self):
with tempfile.TemporaryDirectory() as directory:
installer = setup_native.Setup(directory, prefix=Path(directory) / "prefix",
runner=subprocess.run, resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", return_value=None):
output = io.StringIO()
with redirect_stdout(output):
result = installer.check_path_shadow(Path(directory) / "prefix")
self.assertIsNone(result)
self.assertEqual(output.getvalue(), "")
def test_check_path_shadow_reads_each_binary_at_most_once(self):
class VersionRunner:
def __init__(self):
self.commands = []
def __call__(self, command, **kwargs):
command = list(command)
self.commands.append(command)
version = "old-version" if "earlier" in command[0] else "new-version"
return subprocess.CompletedProcess(command, 0,
stdout=f'{{"version":"{version}","commit":"ab"}}', stderr="")
with tempfile.TemporaryDirectory() as directory:
directory = Path(directory)
prefix = directory / "prefix"
installed = self._fake_pipelines(prefix / "bin/pipelines", "new-version", "bbbb")
shadow = self._fake_pipelines(directory / "earlier/pipelines", "old-version", "aaaa")
runner = VersionRunner()
installer = setup_native.Setup(directory, prefix=prefix, runner=runner,
resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", return_value=str(shadow)):
output = io.StringIO()
with redirect_stdout(output):
installer.check_path_shadow(prefix)
# A detected shadow costs exactly one bounded, read-only `version`
# read per binary (the shadow and the freshly installed CLI) so both
# versions can be named; no other subprocess runs.
self.assertEqual(len(runner.commands), 2)
self.assertTrue(all(command[1:] == ["version", "--json"] for command in runner.commands))
self.assertIn("old-version", output.getvalue())
self.assertIn("new-version", output.getvalue())
self.assertEqual(installed.read_bytes().count(b"new-version"), 1)
def test_full_run_migrates_docker_harness_config_to_host(self):
with tempfile.TemporaryDirectory() as directory:
recorder = Recorder()