feat(sdk,ci): 'rocketride validate' CLI subcommand + reusable GitHub Action to gate .pipe files in CI

[nihalnihalani]

Problem Statement

RocketRide's core wedge is that pipelines are portable, git-versioned JSON (*.pipe) living next to application code — "build, debug, and deploy production AI workflows without leaving your IDE." But today there is no way to check a .pipe file in CI or from a terminal:

• The Python CLI ships start / upload / status / stop / list / events / store — no validate (cli/main.py).
• The TypeScript CLI ships start / upload / status / stop — no validate (cli/rocketride.ts).
• Validation does exist end-to-end — rrext_validate (DAP) → pipe_Validate → the C++ validatePipeline (the 13 structural rules in pipeline_config.cpp) — and both SDKs expose it (client.validate() in Python mixins/services.py:98 and TS client.ts:987). It is simply never surfaced in either CLI.

The practical consequence: a team that reviews .pipe changes in PRs finds out a pipeline is structurally broken at run time, or has to hand-roll a WebSocket script against the DAP API. Comparable developer-first workflow tools treat this as table stakes (Windmill wmill CLI + deploy-from-repo GitHub Actions, Activepieces ap project CI flow, Kestra flow validation in git sync).

Proposed Solution

Three additive pieces, no engine changes:

1. rocketride validate <files...> in the Python CLI

• Accepts one or more .pipe paths (and shell globs); reads each JSON config; calls the existing client.validate() against the connected engine (same connection flags/env vars as the other subcommands).
• --source <id> override mirroring the SDK parameter; --json for machine-readable output (per-file errors/warnings); human-readable summary by default via the existing CLI UI helpers.
• Exit codes: 0 all valid · 1 at least one file failed validation · 2 usage/connection error — so CI can gate on it.

2. rocketride validate in the TypeScript CLI

• Same surface as above, implemented with the existing client.validate() in packages/client-typescript/src/client/client.ts.

3. Reusable composite GitHub Action (.github/actions/validate-pipes/action.yml)

• Boots the published engine image (ghcr.io/rocketride-org/rocketride-engine) as a service, waits for /ping, then runs the CLI against the repo's .pipe files (default: files changed in the PR; input to override the glob).
• Referencable from any consumer repo as rocketride-org/rocketride-server/.github/actions/validate-pipes@develop, and documented with a copy-paste workflow snippet — "broken pipelines never reach develop."

Alternatives Considered

• Re-implement validation offline in Python/TS — rejected: it would duplicate and inevitably drift from the C++ validator, which is the single source of truth for the 13 pipeline rules. Engine-backed validation keeps one implementation.
• Document the SDK-only path — status quo; every team writes the same ad-hoc script.
• MCP-only surface — useful for coding agents but does not serve CI gates or terminals.

Affected Modules

• client-python (new validate subcommand)
• client-typescript (new validate subcommand)
• server (C++ engine) — no changes; consumes existing rrext_validate
• docs (CLI reference + CI guide)
• CI/CD (new composite action; no changes to existing workflows)

Acceptance Criteria

• rocketride validate examples/rag-pipeline.pipe reports success against a running engine; a structurally broken pipe (unknown provider, missing lane, cycle) exits 1 with the engine's error list.
• Multi-file + glob input; --json output; --source override; exit codes 0/1/2 as above.
• Feature parity between the Python and TypeScript CLIs.
• Composite action validates changed .pipe files in a PR using the published engine image; example workflow documented.
• Unit tests for both CLIs (arg parsing, JSON/exit-code behavior, validate-call wiring with mocked client), following the existing test layouts under packages/client-python/tests/ and packages/client-typescript/tests/.
• Docs: docs/README-python-client.md, docs/README-typescript-client.md, and a short "Validate pipelines in CI" guide.

Happy to implement this — PR to follow shortly.

[github-actions]

🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

[nihalnihalani]

Implementation is up in #1573 (all acceptance criteria covered — both CLIs, the composite action, docs, and unit tests, plus live end-to-end verification against the published engine image).

Two findings from the live verification worth recording on this issue:

1. rrext_validate was broken server-side for every caller. The DAP handler passed the pipeline config flat to rocketlib validatePipeline, which requires the {'pipeline': <config>} envelope (the HTTP path modules/pipe/pipe_Validate already wraps it). Result: every rrext_validate call — including SDK client.validate() — failed with ccode 40 "'pipeline' is missing or invalid" regardless of the config, on the published image (v3.3.1.35) and current develop alike. It went unnoticed because nothing in-repo exercises rrext_validate with real payloads (the VS Code extension does its own client-side config checks). #1573 fixes the handler to mirror pipe_Validate and adds a regression test pinning the wire shape — the "Server bug found and fixed" section there has the A/B evidence (unpatched image fails, patched image validates real examples and correctly rejects broken ones).

2. /ping is not reachable on published engine images. server.py registers /ping behind the standardEndpoints gate, and on ghcr.io/rocketride-org/rocketride-engine:latest it 404s even with valid auth; /version is the only unconditionally-public route. The action therefore health-checks /version. Note the Helm chart's liveness/readiness probes point at /ping:5565 — they may deserve the same fix (happy to file separately if maintainers agree).

Also for anyone wiring the action into CI immediately: examples/n8n-roundtrip.pipe and examples/document-processor.pipe fail validation on the current published engine build with "references a provider with no registered service definition" (tool_n8n_1, anonymize_1) — a build-content limitation independent of this feature.