Skip to content

feat: add cascade plan command to preview workflow diffs#243

Merged
joshua-temple merged 1 commit into
mainfrom
feat/cascade-plan-diff
Jun 21, 2026
Merged

feat: add cascade plan command to preview workflow diffs#243
joshua-temple merged 1 commit into
mainfrom
feat/cascade-plan-diff

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

Problem

Running generation overwrites the managed workflow files in place. There was no way to preview exactly what cascade generate-workflow would change before committing to it, which makes upgrades and manifest edits feel risky.

Fix

Add a read-only cascade plan command that renders, as a per-file unified diff, what generation would change in the committed workflow and action files, writing nothing. It is the human-facing preview counterpart to cascade verify:

  • plan = human preview (shows the actual diff).
  • verify = CI pass/fail gate (status lines + drift exit codes).

For each file the manifest would generate, plan prints the diff of committed bytes vs generated bytes: a new file as a whole-file add, a changed file as a unified hunk, a byte-identical file produces no diff. A clean tree prints plan: N files, no pending changes.

The producer is reused (generate.Plan); plan and verify are kept separate because verify owns a frozen 0/1/2 exit contract plus orphan detection and stderr status lines, while plan is stdout unified-diff output.

Read-only / exit contract

  • Writes nothing: no file writes, directory creation, or git invocation.
  • Exit 0 always on success, regardless of whether a diff exists (informational, not a gate).
  • Non-zero only for operational errors (manifest missing/invalid, a planned file unreadable).

This is deliberately distinct from verify's 0/1/2 drift contract.

Verification

  • go build ./cmd/... ./internal/...: success
  • go test ./... -count=1: pass (incl. new internal/plan unit tests: clean tree, mutated file diff, missing-file whole-file add, deterministic output, read-only snapshot, operational error)
  • golangci-lint run ./...: 0 issues
  • e2e module go build ./... && go vet ./...: success
  • e2e scenario e2e/scenarios/33-plan-diff.yaml: regenerate then assert a clean tree, then mutate a committed workflow and assert the specific unified-diff hunk with exit 0

go-difflib promoted from indirect to a direct dependency.

Closes #180

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple joshua-temple enabled auto-merge (squash) June 21, 2026 18:43
@joshua-temple joshua-temple merged commit c79563d into main Jun 21, 2026
16 of 18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: cascade plan shows the workflow diff before writing

1 participant