feat(sdk,ci): 'rocketride diff' — semantic .pipe diff (nodes/edges/config, layout-noise-free) + PR-comment Action

[nihalnihalani]

Problem Statement

RocketRide's whole wedge is that pipelines are portable, git-versioned JSON reviewed like code — but a reviewer looking at a .pipe change in a PR today sees raw JSON, dominated by coordinate churn. Every node carries a ui block (position, measured) that changes whenever anyone nudges the canvas, so a one-line prompt tweak can surface as a 60-line diff of x/y deltas. The signal (a model swapped, a node added, an edge rewired) is buried in noise.

This is a known, unsolved pain even for the market leader: n8n's git-sync produces notoriously noisy JSON diffs that users complain about and still pay Enterprise prices to partially manage. It is precisely the place a git-native tool can win — and RocketRide currently ships nothing here.

It also completes a coherent story with two capabilities the CLI recently gained: validate checks a pipe is well-formed and eval checks it behaves — a diff makes the change itself reviewable. Together: structure, behavior, and review, all in git/CI.

Proposed Solution

A semantic diff for .pipe files — a rocketride diff CLI subcommand plus an optional PR-comment Action.

1. Semantic model (ignore the noise, surface the meaning): match components by id, then report:

• Nodes: added / removed (id + provider); for matched ids, provider changes and a deep diff of config (parameters), rendered as readable field paths (config.model: "gpt-4" → "gpt-4o").
• Edges: derived from each component's input: [{lane, from}] — connections added, removed, or rewired (chat_1 —docs→ llm_1 added; webhook_1 —tags→ parse_1 removed).
• Ignored by default: the entire ui block (position, measured, nodeType, formDataValid), viewport, and no-op version bumps — the exact fields that make raw diffs unreadable. --include-layout opts them back in.

2. Inputs:

• rocketride diff <old.pipe> <new.pipe> — two files.
• rocketride diff --git <ref> <file.pipe> — diff a working-tree pipe against a git ref (HEAD, a branch, the PR base) via git show, so it works in CI with no engine and no server.

3. Output modes: human (colored tree, +/-/~ per change), --json (machine-readable change document), --markdown (a compact table/tree suitable for a PR comment). Exit codes mirror validate/eval: 0 no semantic changes · 1 changes present · 2 usage/parse error. (--exit-zero to always exit 0 for non-gating use.)

4. GitHub Action (.github/actions/pipe-diff): on PRs touching .pipe files, renders the semantic diff of each changed file (vs the PR base) and posts/updates a single sticky PR comment — "real diffs, real review" made visible. Pure Python, no engine required.

5. Docs + example: a diff guide and a demo showing a noisy raw JSON diff next to the semantic one.

Alternatives Considered

• A VS Code custom diff editor — valuable, but heavier (webview, React) and IDE-only; the CLI + Action serves PR review (where the pain actually is) and any editor can shell out to it. A visual editor is a natural follow-up.
• Rely on git diff with a .gitattributes textconv — a textconv can pretty-print but can't do structural (edge/config) diffing or ignore ui selectively; it also can't render a PR comment.
• Fold into validate — different job (validate = is it correct; diff = what changed) and different inputs (two versions vs one).

Affected Modules

• client-python (new diff subcommand + a small pipediff module)
• docs
• server / engine — no changes (pure client-side; no engine, no network)

Acceptance Criteria

• rocketride diff a.pipe b.pipe reports added/removed nodes, provider/config changes on matched nodes, and edge changes — with ui/layout noise excluded by default.
• --git <ref> file.pipe diffs against a git ref; --include-layout, --json, --markdown, and exit codes 0/1/2 as specified.
• Unit tests (no server): identical files → no changes; node add/remove; provider change; nested-config change; edge add/remove/rewire; layout-only change → no semantic changes by default but shown with --include-layout; malformed/one-side-missing files → exit 2 with context.
• Composite Action renders a per-file semantic diff and posts/updates one sticky PR comment on .pipe changes.
• Docs + a side-by-side example (raw vs semantic).

Happy to implement — 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 #1607 — all acceptance criteria covered: semantic node/edge/config diffing with layout noise excluded by default (--include-layout to opt in), --git <ref> mode, --json/--markdown/--exit-zero, the pipe-diff sticky-PR-comment Action, docs, and a raw-vs-semantic example.

The money demo (in the PR): a change that swaps one model, adds a node, rewires an edge, and nudges every canvas position renders as 71 lines of raw JSON diff vs 3 semantic changes with rocketride diff — the 11 position nudges collapse to a single 'layout changed' line. 79 unit tests (incl. a real tmp-repo git integration test); a devil's-advocate markdown-injection catch was fixed at the render choke point so untrusted .pipe values can't break out of a PR comment.

Together with validate and eval, this makes .pipe files fully reviewable in CI: validate = structure, eval = behavior, diff = review.