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, and the logger's warning
on stderr carries the follow-up.

That 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.

The new test removes a snapshot from the local index against a missing
destination directory and checks both streams.

Model: opus-5-5

internal/cli/entry_stdout_stderr_test.go

@@ -87,12 +87,33 @@ 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, and the command
+// to run again once it is reachable, on stderr.
+//
+//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)
+	assert.Contains(t, stderr,
+		"Could not remove snapshot metadata from remote storage")
+	assert.Contains(t, stderr,
+		"run 'vaultik snapshot remove "+stalePruneSnapshotID+"' again")
+}
+
+// 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 +135,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 +156,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.`,

internal/vaultik/snapshot.go

@@ -1146,7 +1146,7 @@ func (v *Vaultik) RemoveSnapshot(
 	}
 
 	if !opts.LocalOnly {
-		result.RemoteRemoved = v.removeSnapshotRemote(snapshotID)
+		result.RemoteRemoved = v.removeSnapshotRemote(snapshotID, opts)
 	}
 
 	if v.SnapshotManager != nil {
@@ -1229,9 +1229,11 @@ func (v *Vaultik) confirmRemoveSnapshot(snapshotID string, opts *RemoveOptions)
 // removeSnapshotRemote strips the snapshot's metadata from the
 // destination store, warning and proceeding on failure: the local-DB
 // removal has already happened, so the user is told the remote half
-// didn't finish and can retry with `vaultik prune` once the destination
-// store is reachable. Returns true when the remote removal succeeded.
-func (v *Vaultik) removeSnapshotRemote(snapshotID string) bool {
+// didn't finish and to run `vaultik snapshot remove` for the snapshot
+// again once the destination store is reachable (`vaultik prune` never
+// removes snapshot metadata). Returns true when the remote removal
+// succeeded.
+func (v *Vaultik) removeSnapshotRemote(snapshotID string, opts *RemoveOptions) bool {
 	log.Info("Removing snapshot metadata from remote storage",
 		"snapshot_id", snapshotID)
 
@@ -1239,13 +1241,18 @@ func (v *Vaultik) removeSnapshotRemote(snapshotID string) bool {
 
 	err := v.deleteRemoteSnapshotByKey(remoteKey)
 	if err != nil {
-		log.Warn("Could not remove snapshot metadata from remote storage",
+		removeCommand := "vaultik snapshot remove " + snapshotID
+
+		log.Warn("Could not remove snapshot metadata from remote storage; "+
+			"run '"+removeCommand+"' again once the remote is reachable",
 			"error", err)
 
-		if v.UI != nil {
+		// The UI writes to stdout, which under --json holds only the
+		// document; the log record above is the warning on stderr.
+		if v.UI != nil && !opts.JSON {
 			v.UI.Warningf("Could not remove snapshot metadata from remote: "+
-				"%v. Run '%s' once the remote is reachable to finish cleanup.",
-				err, pruneCommandHint)
+				"%v. Run '%s' again once the remote is reachable.",
+				err, removeCommand)
 		}
 
 		return false