Write only the document to stdout from snapshot remove --json (closes #251)

When the destination store cannot be reached, `snapshot remove` still
removes the snapshot from the local index and warns. The warning went
through the UI, which writes to stdout, so under `--json` it landed
ahead of the document and `| jq` failed on a command that exited 0.
Under `--json` the UI warning is now skipped; the logger's warning on
stderr carries the follow-up, with the snapshot ID as a field.

The follow-up, in the warning, the README and the command's help, said
`vaultik prune` would finish the cleanup, but `prune` never removes
snapshot metadata. They now say to run `vaultik snapshot remove` for the
snapshot again once the destination store is reachable.

Model: opus-5-5

internal/cli/entry_stdout_stderr_test.go

@@ -2,7 +2,9 @@ package cli //nolint:testpackage // shares hermeticConfig and the capture helper
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
@@ -87,12 +89,45 @@ func TestEntryJSONFailureIsReportedOnStderr(t *testing.T) {
 	}
 }
 
-// writeUnusableDestinationConfig builds a config whose destination
-// directory does not exist, which fails `remote info`, and whose local
-// index is bound to another destination, which fails `prune` and
-// `snapshot remove` (a missing destination alone only makes `snapshot
-// remove` warn). Returns the config path.
-func writeUnusableDestinationConfig(t *testing.T) string {
+// TestEntrySnapshotRemoveJSONWarningIsOnStderr runs `snapshot remove
+// --json` on a snapshot in the local index, against a destination
+// directory that does not exist. The command removes the snapshot from
+// the local index and still exits 0. Its stdout must hold the document
+// alone, with the warning about the destination store on stderr: the
+// command to run again once it is reachable, and the snapshot's ID in
+// the record's snapshot_id field.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotRemoveJSONWarningIsOnStderr(t *testing.T) {
+	configPath, indexPath := writeMissingDestinationConfig(t)
+	seedStaleSnapshotRecord(t, indexPath)
+
+	code, stdout, stderr := runEntry(t, flagConfig, configPath,
+		cmdSnapshot, cmdRemove, stalePruneSnapshotID, flagJSON)
+
+	require.Equal(t, 0, code)
+	requireExactlyOneJSONDocument(t, stdout)
+
+	// stderr is a pipe here, so the logger writes one JSON record a line.
+	var warning map[string]any
+
+	for line := range strings.Lines(stderr) {
+		if strings.Contains(line,
+			"Could not remove snapshot metadata from remote storage") {
+			require.NoError(t, json.Unmarshal([]byte(line), &warning))
+		}
+	}
+
+	require.NotNil(t, warning, "the warning must reach stderr")
+	assert.Contains(t, warning[slog.MessageKey],
+		"run 'vaultik snapshot remove' with the snapshot's ID again")
+	assert.Equal(t, stalePruneSnapshotID, warning["snapshot_id"])
+}
+
+// writeMissingDestinationConfig builds a config whose destination
+// directory does not exist. Returns the config path and the path of
+// its local index, which is not created here.
+func writeMissingDestinationConfig(t *testing.T) (string, string) {
 	t.Helper()
 
 	dir := t.TempDir()
@@ -114,6 +149,19 @@ func writeUnusableDestinationConfig(t *testing.T) string {
 	xdg.Reload()
 	t.Cleanup(xdg.Reload)
 
+	return configPath, indexPath
+}
+
+// writeUnusableDestinationConfig builds a config whose destination
+// directory does not exist, which fails `remote info`, and whose local
+// index is bound to another destination, which fails `prune` and
+// `snapshot remove` (a missing destination alone only makes `snapshot
+// remove` warn). Returns the config path.
+func writeUnusableDestinationConfig(t *testing.T) string {
+	t.Helper()
+
+	configPath, indexPath := writeMissingDestinationConfig(t)
+
 	ctx := context.Background()
 
 	db, err := database.New(ctx, indexPath)
@@ -122,7 +170,7 @@ func writeUnusableDestinationConfig(t *testing.T) string {
 	defer func() { require.NoError(t, db.Close()) }()
 
 	require.NoError(t, database.NewRepositories(db).LocalMeta.Set(ctx,
-		database.LocalMetaKeyStorageURL, "file://"+filepath.Join(dir, "other")))
+		database.LocalMetaKeyStorageURL, "file://"+t.TempDir()))
 
 	return configPath
 }

internal/cli/snapshot.go

@@ -258,8 +258,9 @@ Use --local-only to skip the remote half (e.g. when you want to forget a
 snapshot locally without touching the destination store).
 
 If the remote is unreachable, the local-database removal still completes
-and a warning is emitted; rerun 'vaultik prune' once the destination store
-is reachable to finish remote cleanup.
+and a warning is emitted; run 'vaultik snapshot remove <snapshot-id>' again
+once the destination store is reachable to remove the snapshot's metadata
+from it ('vaultik prune' does not).
 
 To wipe the entire destination store and start over, use 'vaultik remote
 nuke --force' — it is the single supported entry point for that.`,