feat(diff): add dash0 diff command

New experimental `dash0 diff -f <file|directory> [--since <ref>]` command
previews what `apply` would do without ever creating, updating, or deleting
anything:

- Fetches each document's current state from Dash0 (per-kind, non-mutating)
  to accurately distinguish create from update, unlike `apply --dry-run`,
  which is local-only and can't tell the two apart.
- All-or-nothing fetch gate: any document fetch failure (other than a plain
  "not found") aborts the whole plan before anything is printed.
- `--since <ref>` reuses apply's identifier-diffing to preview deletions
  alongside creates/updates, never deleting anything regardless of
  confirmation.
- Three-way exit code (0 clean, 1 differences pending, 2 error), modeled on
  `kubectl diff` — a deliberate, narrow exception to this CLI's uniform 0/1
  convention.
- Human-mode unified-diff report and agent-mode JSON output matching
  `apply --dry-run`'s {path, changes} shape, extended with a "create" op.

Supporting changes:
- Move apply --since's git-diffing plan (deletionPlan) into
  internal/git as the exported SincePlan/ComputeSincePlan, so diff can
  reuse it without depending on internal/apply.
- Move apply's document validation (validateDocuments) and PrometheusRule
  CRD parsing into internal/asset as ValidateDocuments/ParsePrometheusRuleCRD,
  for the same reason.
- Fix a real cobra Traverse bug in cmd/dash0/main.go: a boolean persistent
  flag preceding the subcommand (e.g. `dash0 --experimental diff ...`, the
  form used throughout this CLI's docs) was misresolved to the root command
  because Traverse's flag lookup doesn't see PersistentFlags() until cobra's
  own lazy merge runs during Execute. This silently broke diff's exit code
  (always falling back to 1 instead of 2 on a genuine error) for that
  invocation order.
- Deprecate `apply --dry-run` in favor of `dash0 diff`, with a runtime
  stderr warning and updated help text.

References #256.

Author: mmanciop

.chloggen/feat_diff-command.yaml

@@ -0,0 +1,15 @@
+change_type: new_component
+
+component: diff
+
+note: "Add the experimental `dash0 diff` command, which previews what `apply` would do (creates, updates, and — with `--since` — deletions) without ever mutating anything."
+
+issues: [256]
+
+subtext: |
+  `diff` fetches each document's current state from Dash0 first, so it can accurately distinguish a create from
+  an update — unlike `apply --dry-run`, which is local-only and cannot tell the two apart. It uses a three-way
+  exit code (0 clean, 1 differences pending, 2 error), modeled on `kubectl diff`.
+  `apply --dry-run` is now deprecated in favor of `dash0 diff` and prints a warning to stderr on every invocation.
+
+change_logs: [user]

README.md

@@ -373,6 +373,12 @@ Validate without applying:
 dash0 apply -f assets.yaml --dry-run
 ```
 
+`--dry-run` is deprecated in favor of `dash0 diff` (experimental, requires `-X`), which fetches each asset's current state from Dash0 first to accurately distinguish a create from an update:
+
+```bash
+dash0 -X diff -f assets.yaml
+```
+
 Sync a directory to match its state as of a git ref, deleting assets removed since then (experimental, requires `-X`):
 
 ```bash

cmd/dash0/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"os/signal"
@@ -18,6 +19,7 @@ import (
 	dashcolor "github.com/dash0hq/dash0-cli/internal/color"
 	"github.com/dash0hq/dash0-cli/internal/config"
 	"github.com/dash0hq/dash0-cli/internal/dashboards"
+	"github.com/dash0hq/dash0-cli/internal/diff"
 	"github.com/dash0hq/dash0-cli/internal/help"
 	"github.com/dash0hq/dash0-cli/internal/logging"
 	"github.com/dash0hq/dash0-cli/internal/login"
@@ -77,6 +79,7 @@ func init() {
 	rootCmd.AddCommand(failedchecks.NewFailedChecksCmd())
 	rootCmd.AddCommand(config.NewConfigCmd())
 	rootCmd.AddCommand(dashboards.NewDashboardsCmd())
+	rootCmd.AddCommand(diff.NewDiffCmd())
 	rootCmd.AddCommand(logging.NewLogsCmd())
 	rootCmd.AddCommand(login.NewLoginCmd())
 	rootCmd.AddCommand(login.NewLogoutCmd())
@@ -298,8 +301,27 @@ func main() {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
-	// Determine which command will be executed (best-effort; Traverse may
-	// return the root command when persistent flags like -X come first).
+	// Command.Traverse decides whether a "--name value"-shaped argument is a
+	// flag (consuming the next token) or a bareword by looking up the flag
+	// in c.Flags() — which does NOT include persistent flags registered via
+	// PersistentFlags() until cobra's own (unexported) mergePersistentFlags
+	// runs, which normally happens lazily during Execute, i.e. after this
+	// pre-flight Traverse call. Without this merge, a boolean persistent
+	// flag preceding the subcommand (e.g. `dash0 --experimental diff ...`,
+	// the form used throughout this CLI's own docs and examples) is
+	// wrongly treated as expecting a value, which swallows the subcommand
+	// name as that value and makes Traverse return the root command
+	// instead of the real target. Replicating the merge here first (a
+	// public, idempotent equivalent of cobra's own step) fixes that. See
+	// TestTraverseTargetCommand in main_test.go for a regression test
+	// against an isolated command tree (rootCmd itself is a package-level
+	// singleton that Execute() mutates as a side effect, which would mask
+	// this bug in a test that reused rootCmd after any earlier Execute call).
+	rootCmd.Flags().AddFlagSet(rootCmd.PersistentFlags())
+
+	// Determine which command will be executed (best-effort; Traverse can
+	// still fall back to the root command for shapes it doesn't model,
+	// e.g. an unrecognized flag).
 	targetCmd, _, _ := rootCmd.Traverse(os.Args[1:])
 
 	// Resolve agent mode before any output.
@@ -366,15 +388,43 @@ func main() {
 	}
 
 	if err := rootCmd.ExecuteContext(ctx); err != nil {
-		printError(err)
-		// Show usage only for flag/argument errors, not for runtime errors.
-		// Commands set SilenceUsage = true once past flag validation.
-		if !agentmode.Enabled && targetCmd != nil && targetCmd.Name() != "dash0" && !targetCmd.SilenceUsage {
-			fmt.Fprintln(os.Stderr)
-			_ = targetCmd.Usage()
+		cmdName := ""
+		if targetCmd != nil {
+			cmdName = targetCmd.Name()
 		}
-		os.Exit(1)
+
+		// A *diff.PendingDifferencesError is not a failure -- the diff
+		// report was already printed to stdout/stderr by the time it's
+		// returned, so it must never be rendered through the
+		// "Error:"-prefixed path (and usage must not be printed either).
+		if !errors.As(err, new(*diff.PendingDifferencesError)) {
+			printError(err)
+			// Show usage only for flag/argument errors, not for runtime errors.
+			// Commands set SilenceUsage = true once past flag validation.
+			if !agentmode.Enabled && targetCmd != nil && targetCmd.Name() != "dash0" && !targetCmd.SilenceUsage {
+				fmt.Fprintln(os.Stderr)
+				_ = targetCmd.Usage()
+			}
+		}
+		os.Exit(exitCodeForError(cmdName, err))
+	}
+}
+
+// exitCodeForError determines the process exit code for a command whose
+// RunE returned a non-nil err. Every command exits 1 on error except dash0
+// diff, which uses a three-way exit code (0 clean, 1 differences pending, 2
+// genuine error) instead of this CLI's uniform 0/1 convention -- modeled on
+// `kubectl diff`, so a naive CI step doesn't fail on the routine "changes
+// pending" case, but still fails hard on a genuine error (bad --since ref,
+// API unreachable, and so on).
+func exitCodeForError(cmdName string, err error) int {
+	if errors.As(err, new(*diff.PendingDifferencesError)) {
+		return 1
+	}
+	if cmdName == "diff" {
+		return 2
 	}
+	return 1
 }
 
 // installJSONHelp replaces the default help function on cmd and all

cmd/dash0/main_test.go

@@ -3,13 +3,16 @@ package main
 import (
 	"bytes"
 	"errors"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
 	"testing"
 
 	"github.com/dash0hq/dash0-cli/internal/agentmode"
+	"github.com/dash0hq/dash0-cli/internal/diff"
 	"github.com/dash0hq/dash0-cli/internal/skill"
+	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -57,6 +60,79 @@ func TestRootCommandExecution(t *testing.T) {
 	}
 }
 
+// newIsolatedRootForTraverseTest builds a fresh root+child command tree
+// shaped like the real dash0 root command (a boolean persistent flag plus
+// one subcommand with its own flags), so tests can exercise Traverse
+// without touching the package-level rootCmd singleton. rootCmd is mutated
+// as a side effect by cobra internals the first time anything calls
+// rootCmd.Execute() anywhere in the test binary (e.g.
+// TestRootCommandExecution) -- persistent flags get merged into its local
+// flag set lazily, which would silently fix the exact bug this test exists
+// to catch and make the regression test pass regardless of whether main()
+// still carries the fix.
+func newIsolatedRootForTraverseTest() (*cobra.Command, *cobra.Command) {
+	root := &cobra.Command{Use: "dash0"}
+	root.PersistentFlags().BoolP("experimental", "X", false, "Enable experimental features")
+	child := &cobra.Command{Use: "diff"}
+	child.Flags().StringP("file", "f", "", "")
+	root.AddCommand(child)
+	return root, child
+}
+
+// TestTraverseTargetCommand is a regression test for a real cobra pitfall:
+// Command.Traverse decides whether a "--name" token expects a following
+// value by looking up the flag in c.Flags(), which does not include flags
+// registered via PersistentFlags() until cobra's own mergePersistentFlags
+// runs (normally during Execute, i.e. after Traverse). Without pre-merging
+// persistent flags into the root command's own flag set (main()'s fix,
+// right before its own Traverse call), a boolean persistent flag preceding
+// the subcommand -- e.g. `dash0 --experimental diff ...`, the invocation
+// form used throughout this CLI's own docs -- gets wrongly treated as
+// expecting a value, swallowing the subcommand name as that value and
+// making Traverse resolve to the root command instead of the real target.
+// This mattered concretely for `dash0 diff`'s three-way exit code: main()'s
+// exitCodeForError branches on the resolved command's name, so a
+// misresolved target silently fell back to exit 1 instead of exit 2 on a
+// genuine error.
+func TestTraverseTargetCommand(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{"persistent bool flag before subcommand", []string{"--experimental", "diff", "-f", "x.yaml"}, "diff"},
+		{"shorthand persistent bool flag before subcommand", []string{"-X", "diff", "-f", "x.yaml"}, "diff"},
+		{"no persistent flag", []string{"diff", "-f", "x.yaml"}, "diff"},
+		{"persistent flag after subcommand", []string{"diff", "--experimental", "-f", "x.yaml"}, "diff"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			root, _ := newIsolatedRootForTraverseTest()
+			// The fix under test: without this, a fresh root command (never
+			// Executed, so cobra's own lazy persistent-flag merge hasn't run
+			// yet) reproduces the bug.
+			root.Flags().AddFlagSet(root.PersistentFlags())
+
+			cmd, _, err := root.Traverse(tc.args)
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, cmd.Name())
+		})
+	}
+}
+
+// TestTraverseTargetCommand_ReproducesBugWithoutFix proves the fix is load-
+// bearing: the same isolated, never-Executed root command tree without the
+// AddFlagSet pre-merge misresolves a persistent bool flag preceding the
+// subcommand, confirming TestTraverseTargetCommand isn't passing for some
+// unrelated reason.
+func TestTraverseTargetCommand_ReproducesBugWithoutFix(t *testing.T) {
+	root, _ := newIsolatedRootForTraverseTest()
+
+	cmd, _, err := root.Traverse([]string{"--experimental", "diff", "-f", "x.yaml"})
+	require.NoError(t, err)
+	assert.Equal(t, "dash0", cmd.Name(), "without the AddFlagSet pre-merge, Traverse should misresolve to the root command")
+}
+
 // TestWithSkillHint covers the agent-mode error hint pointing at
 // `dash0 skill install`, added centrally in printError.
 func TestWithSkillHint(t *testing.T) {
@@ -256,3 +332,29 @@ func TestFlagValue(t *testing.T) {
 		})
 	}
 }
+
+// TestExitCodeForError pins dash0 diff's three-way exit code (0 clean -- not
+// exercised here since exitCodeForError is only called when err != nil, 1
+// differences pending, 2 genuine error) against every other command's
+// uniform 1-on-any-error convention.
+func TestExitCodeForError(t *testing.T) {
+	genericErr := errors.New("boom")
+	pendingErr := &diff.PendingDifferencesError{Count: 3}
+
+	cases := []struct {
+		name    string
+		cmdName string
+		err     error
+		want    int
+	}{
+		{"diff genuine error exits 2", "diff", genericErr, 2},
+		{"diff pending differences exits 1", "diff", pendingErr, 1},
+		{"diff pending differences wrapped still exits 1", "diff", fmt.Errorf("wrapped: %w", pendingErr), 1},
+		{"non-diff command exits 1 on any error", "apply", genericErr, 1},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.want, exitCodeForError(tc.cmdName, tc.err))
+		})
+	}
+}