feat: keep git operations working when smudge cannot decrypt

- On a missing or wrong key, the smudge filter (both single-shot and
  filter-process) now passes the encrypted content through with a clear
  warning instead of aborting the checkout, so git pull/checkout/clone
  succeed with the file left encrypted
- The warning states the git operation succeeded and how to recover
  (envapor init <key>, then envapor decrypt)
- Clean stays fail-closed: encryption failures still abort so plaintext
  can never reach the object store
- Also destroy key material in the single-shot smudge/textconv paths

🤖 Generated with Claude Code

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ranaroussi

docs/user-guide.md

@@ -374,7 +374,7 @@ Both keys appear in the command by design: migration needs the old key to decryp
 ## Troubleshooting
 
 **Values look like `ENC[v2:...]` in my editor.**
-The smudge filter did not run on checkout. Run `envapor init --pem <key>` to reinstall the filters, then re-checkout the file with `git checkout -- .env`.
+The file was checked out without being decrypted — either the filters are not installed, or the local key does not match (in that case `git pull`/`git checkout` prints an `envapor: warning: could not decrypt ...` message but completes normally, leaving the file encrypted). Set the correct key with `envapor init <key>`, then run `envapor decrypt` to restore plaintext.
 
 **My commit was aborted with a plaintext warning.**
 This is the pre-commit guard doing its job: it caught a value that was not encrypted. Run `envapor doctor` to confirm the filters are installed, then re-stage and commit.

src/internal/cmd/filter.go

@@ -1,13 +1,31 @@
 package cmd
 
 import (
+	"fmt"
 	"io"
 	"os"
+	"strings"
 
 	"github.com/automazeio/envapor/internal/envfile"
 	"github.com/spf13/cobra"
 )
 
+// smudgeFallback reports a smudge failure and returns the content unchanged,
+// so the surrounding git operation (pull, checkout, clone) succeeds with the
+// file left encrypted instead of aborting halfway through. Clean has no such
+// fallback: failures there stay fatal so plaintext can never reach the object
+// store unencrypted.
+func smudgeFallback(path string, cause error, content []byte) []byte {
+	if path == "" {
+		path = "the file"
+	}
+	reason := strings.TrimPrefix(cause.Error(), "envapor: ")
+	fmt.Fprintf(os.Stderr, "envapor: warning: could not decrypt %s: %s\n", path, reason)
+	fmt.Fprintf(os.Stderr, "envapor: the git operation itself succeeded, but %s still holds encrypted values.\n", path)
+	fmt.Fprintf(os.Stderr, "envapor: set the right key with 'envapor init <key>', then run 'envapor decrypt'.\n")
+	return content
+}
+
 // cleanCmd is the Git clean filter: it reads a plaintext .env from stdin and
 // writes the encrypted form to stdout on the way into the object store.
 var cleanCmd = &cobra.Command{
@@ -34,24 +52,32 @@ var cleanCmd = &cobra.Command{
 }
 
 // smudgeCmd is the Git smudge filter: it reads an encrypted .env from stdin and
-// writes the decrypted form to the working tree on checkout.
+// writes the decrypted form to the working tree on checkout. When decryption is
+// impossible (missing or wrong key), it passes the encrypted content through
+// with a warning rather than failing the whole git operation.
 var smudgeCmd = &cobra.Command{
 	Use:    "smudge [file]",
 	Short:  "Git smudge filter (decrypt stdin to stdout)",
 	Hidden: true,
 	Args:   cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
-		key, err := loadRepoKey()
-		if err != nil {
-			return err
+		path := ".env"
+		if len(args) == 1 {
+			path = args[0]
 		}
 		in, err := io.ReadAll(os.Stdin)
 		if err != nil {
 			return err
 		}
+		key, err := loadRepoKey()
+		if err != nil {
+			_, werr := os.Stdout.Write(smudgeFallback(path, err, in))
+			return werr
+		}
+		defer key.Destroy()
 		out, err := envfile.Decrypt(in, key)
 		if err != nil {
-			return err
+			out = smudgeFallback(path, err, in)
 		}
 		_, err = os.Stdout.Write(out)
 		return err
@@ -66,17 +92,19 @@ var textconvCmd = &cobra.Command{
 	Hidden: true,
 	Args:   cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
-		key, err := loadRepoKey()
+		data, err := os.ReadFile(args[0])
 		if err != nil {
 			return err
 		}
-		data, err := os.ReadFile(args[0])
+		key, err := loadRepoKey()
 		if err != nil {
-			return err
+			_, werr := os.Stdout.Write(smudgeFallback(args[0], err, data))
+			return werr
 		}
+		defer key.Destroy()
 		out, err := envfile.Decrypt(data, key)
 		if err != nil {
-			return err
+			out = smudgeFallback(args[0], err, data)
 		}
 		_, err = os.Stdout.Write(out)
 		return err

src/internal/cmd/filterprocess.go

@@ -58,6 +58,7 @@ func runFilterProcess(stdin io.Reader, stdout io.Writer) error {
 			return nil
 		}
 		command := metaValue(meta, "command")
+		pathname := metaValue(meta, "pathname")
 		content, err := r.ReadDataUntilFlush()
 		if err != nil {
 			return err
@@ -69,13 +70,21 @@ func runFilterProcess(stdin io.Reader, stdout io.Writer) error {
 		}
 
 		var result []byte
-		switch {
-		case keyErr != nil:
-			err = keyErr
-		case command == "clean":
-			result, err = envfile.Encrypt(content, key)
-		case command == "smudge":
-			result, err = envfile.Decrypt(content, key)
+		switch command {
+		case "clean":
+			if keyErr != nil {
+				err = keyErr
+			} else {
+				result, err = envfile.Encrypt(content, key)
+			}
+		case "smudge":
+			// Smudge failures pass the encrypted content through so the git
+			// operation succeeds; clean failures above stay fatal (fail closed).
+			if keyErr != nil {
+				result = smudgeFallback(pathname, keyErr, content)
+			} else if result, err = envfile.Decrypt(content, key); err != nil {
+				result, err = smudgeFallback(pathname, err, content), nil
+			}
 		default:
 			err = fmt.Errorf("unsupported filter command %q", command)
 		}

src/internal/cmd/filterprocess_test.go

@@ -72,6 +72,41 @@ func TestFilterProcessKeyErrorFailsClosed(t *testing.T) {
 	}
 }
 
+func TestFilterProcessSmudgeWrongKeyPassesThrough(t *testing.T) {
+	encKey, err := crypto.Generate()
+	if err != nil {
+		t.Fatal(err)
+	}
+	wrongKey, err := crypto.Generate()
+	if err != nil {
+		t.Fatal(err)
+	}
+	orig := loadFilterKey
+	loadFilterKey = func() (*crypto.Key, error) { return wrongKey, nil }
+	defer func() { loadFilterKey = orig }()
+
+	ciphertext, err := envfile.Encrypt([]byte("SECRET=hunter2\n"), encKey)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var in bytes.Buffer
+	w := pktline.NewWriter(&in)
+	writeHandshake(t, w)
+	writeCommand(t, w, "smudge", ciphertext)
+
+	var out bytes.Buffer
+	if err := runFilterProcess(&in, &out); err != nil {
+		t.Fatalf("runFilterProcess: %v", err)
+	}
+
+	r := pktline.NewReader(&out)
+	readHandshake(t, r)
+	if got := readCommandResult(t, r); !bytes.Equal(got, ciphertext) {
+		t.Fatalf("smudge with wrong key = %q, want encrypted pass-through %q", got, ciphertext)
+	}
+}
+
 func writeHandshake(t *testing.T, w *pktline.Writer) {
 	t.Helper()
 	must(t, w.WriteText("git-filter-client\n"))