Introduce `StateMigrateJSON` method/command (#609)
diff --git a/tfexec/internal/e2etest/state_migrate_test.go b/tfexec/internal/e2etest/state_migrate_test.go
new file mode 100644
index 0000000..2f7f69d
--- /dev/null
+++ b/tfexec/internal/e2etest/state_migrate_test.go
@@ -0,0 +1,90 @@
+// Copyright IBM Corp. 2020, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package e2etest
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"regexp"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/go-version"
+	tfjson "github.com/hashicorp/terraform-json"
+
+	"github.com/hashicorp/terraform-exec/tfexec"
+	"github.com/hashicorp/terraform-exec/tfexec/internal/testutil"
+)
+
+func TestStateMigrateJSON_tooOldVersion(t *testing.T) {
+	versions := []string{testutil.Latest_v1_12}
+
+	runTestWithVersions(t, versions, "state_migrate_local_backend", func(t *testing.T, tfv *version.Version, tf *tfexec.Terraform) {
+		re := regexp.MustCompile("terraform state migrate -json was added in 1.18.0")
+
+		_, err := tf.StateMigrateJSON(context.Background())
+		if err == nil {
+			t.Fatal("expected StateMigrateJSON to fail in old version")
+		}
+		if !re.MatchString(err.Error()) {
+			t.Fatalf("error running StateMigrateJSON: %s", err)
+		}
+	})
+}
+
+func TestStateMigrateJSON_basic(t *testing.T) {
+	runTest(t, "state_migrate_local_backend", func(t *testing.T, tfv *version.Version, tf *tfexec.Terraform) {
+		if tfv.LessThan(stateMigrateMinVersion) {
+			t.Skip("state migrate command not available in this Terraform version")
+		}
+
+		srcBytes, err := os.ReadFile(filepath.Join(tf.WorkingDir(), "src.tfstate"))
+		if err != nil {
+			t.Fatalf("failed to read source state: %s", err)
+		}
+		sourceState := string(srcBytes)
+
+		iter, err := tf.StateMigrateJSON(context.Background())
+		if err != nil {
+			t.Fatalf("error running StateMigrateJSON: %s", err)
+		}
+
+		finalMsg := ""
+		for nextMsg := range iter {
+			if nextMsg.Err != nil {
+				t.Fatalf("error getting next message: %s", nextMsg.Err)
+			}
+			switch m := nextMsg.Msg.(type) {
+			case tfjson.VersionLogMessage:
+				t.Logf("versions: Terraform %q, UI %q", m.Terraform, m.UI)
+			case tfjson.DiagnosticLogMessage:
+				t.Errorf("unexpected diagnostic: %q", m.Msg)
+			case tfjson.MigrationCompleteMessage:
+				t.Logf("migration complete: %q", m.Msg)
+			case tfjson.MigrationFinalizedMessage:
+				finalMsg = m.Msg
+			}
+		}
+
+		expectedMsg := `Finished migrating state from backend "local" to backend "local".`
+		if diff := cmp.Diff(expectedMsg, finalMsg); diff != "" {
+			t.Fatalf("unexpected final message: %s", diff)
+		}
+
+		dstBytes, err := os.ReadFile(filepath.Join(tf.WorkingDir(), "dst.tfstate"))
+		if err != nil {
+			t.Fatalf("failed to read destination state: %s", err)
+		}
+		destinationState := string(dstBytes)
+
+		if diff := cmp.Diff(sourceState, destinationState); diff != "" {
+			t.Fatalf("unexpected difference after migration: %s", diff)
+		}
+	})
+
+	// TODO: basic state store test (requires an implemented provider)
+
+	// TODO: provider upgrade test (requires an implemented provider)
+}
diff --git a/tfexec/internal/e2etest/testdata/.gitattributes b/tfexec/internal/e2etest/testdata/.gitattributes
new file mode 100644
index 0000000..6566631
--- /dev/null
+++ b/tfexec/internal/e2etest/testdata/.gitattributes
@@ -0,0 +1,3 @@
+# Always checkout state files with LF (even on Windows)
+# to match how the state is written by Terraform
+*.tfstate text eol=lf
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/.terraform.lock.hcl b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/.terraform.lock.hcl
new file mode 100644
index 0000000..6e7e533
--- /dev/null
+++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/.terraform.lock.hcl
@@ -0,0 +1,2 @@
+# This file is maintained automatically by "terraform init".
+# Manual edits may be lost in future updates.
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/from.tfmigrate.hcl b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/from.tfmigrate.hcl
new file mode 100644
index 0000000..a8a53d9
--- /dev/null
+++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/from.tfmigrate.hcl
@@ -0,0 +1,5 @@
+from {
+  backend "local" {
+    path = "src.tfstate"
+  }
+}
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/src.tfstate b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/src.tfstate
new file mode 100644
index 0000000..a50176d
--- /dev/null
+++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/src.tfstate
@@ -0,0 +1,36 @@
+{
+  "version": 4,
+  "terraform_version": "1.18.0",
+  "serial": 1,
+  "lineage": "effc3564-885c-34f7-cae4-7be5aff731cf",
+  "outputs": {},
+  "resources": [
+    {
+      "mode": "managed",
+      "type": "terraform_data",
+      "name": "test",
+      "provider": "provider[\"terraform.io/builtin/terraform\"]",
+      "instances": [
+        {
+          "schema_version": 0,
+          "attributes": {
+            "id": "c2d8ad26-8316-550c-5e25-bcc3a20e58d9",
+            "input": {
+              "value": "foo",
+              "type": "string"
+            },
+            "output": {
+              "value": "foo",
+              "type": "string"
+            },
+            "store": null,
+            "triggers_replace": null
+          },
+          "sensitive_attributes": [],
+          "identity_schema_version": 0
+        }
+      ]
+    }
+  ],
+  "check_results": null
+}
diff --git a/tfexec/internal/e2etest/testdata/state_migrate_local_backend/to.tf b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/to.tf
new file mode 100644
index 0000000..775b02c
--- /dev/null
+++ b/tfexec/internal/e2etest/testdata/state_migrate_local_backend/to.tf
@@ -0,0 +1,9 @@
+terraform {
+  backend "local" {
+    path = "dst.tfstate"
+  }
+}
+
+resource "terraform_data" "test" {
+  input = "foo"
+}
diff --git a/tfexec/internal/e2etest/util_test.go b/tfexec/internal/e2etest/util_test.go
index 7fd872c..ffee59a 100644
--- a/tfexec/internal/e2etest/util_test.go
+++ b/tfexec/internal/e2etest/util_test.go
@@ -29,6 +29,8 @@
 	providerAddressMinVersion = version.Must(version.NewVersion("0.13.0"))
 
 	metadataFunctionsMinVersion = version.Must(version.NewVersion("1.4.0"))
+
+	stateMigrateMinVersion = version.Must(version.NewVersion("1.18.0-dev"))
 )
 
 func runTest(t *testing.T, fixtureName string, cb func(t *testing.T, tfVersion *version.Version, tf *tfexec.Terraform)) {
diff --git a/tfexec/options.go b/tfexec/options.go
index 30d6b6a..b132f60 100644
--- a/tfexec/options.go
+++ b/tfexec/options.go
@@ -476,3 +476,19 @@
 func LockFile(useLockFile bool) *LockFileOption {
 	return &LockFileOption{useLockFile: useLockFile}
 }
+
+type SourceProviderLockFileOption struct {
+	path string
+}
+
+func SourceProviderLockFile(path string) *SourceProviderLockFileOption {
+	return &SourceProviderLockFileOption{path: path}
+}
+
+type DestinationProviderLockFileOption struct {
+	path string
+}
+
+func DestinationProviderLockFile(path string) *DestinationProviderLockFileOption {
+	return &DestinationProviderLockFileOption{path: path}
+}
diff --git a/tfexec/state_migrate.go b/tfexec/state_migrate.go
new file mode 100644
index 0000000..cc40666
--- /dev/null
+++ b/tfexec/state_migrate.go
@@ -0,0 +1,104 @@
+// Copyright IBM Corp. 2020, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package tfexec
+
+import (
+	"context"
+	"fmt"
+	"iter"
+	"os/exec"
+)
+
+type stateMigrateConfig struct {
+	srcProviderLockFile string
+	dstProviderLockFile string
+
+	upgrade bool
+
+	reattachInfo ReattachInfo
+}
+
+var defaultStateMigrateOptions = stateMigrateConfig{}
+
+// StateMigrateOption represents options used in the StateMigrate method.
+type StateMigrateOption interface {
+	configureStateMigrate(*stateMigrateConfig)
+}
+
+func (opt *SourceProviderLockFileOption) configureStateMigrate(conf *stateMigrateConfig) {
+	conf.srcProviderLockFile = opt.path
+}
+
+func (opt *DestinationProviderLockFileOption) configureStateMigrate(conf *stateMigrateConfig) {
+	conf.dstProviderLockFile = opt.path
+}
+
+func (opt *UpgradeOption) configureStateMigrate(conf *stateMigrateConfig) {
+	conf.upgrade = opt.upgrade
+}
+
+func (opt *ReattachOption) configureStateMigrate(conf *stateMigrateConfig) {
+	conf.reattachInfo = opt.info
+}
+
+// StateMigrateJSON executes `terraform state migrate` with `-json` flag
+// and any specified options and waits for it to complete.
+//
+// StateMigrateJSON is likely to be removed in a future major version in favour of
+// StateMigrate returning JSON by default.
+func (tf *Terraform) StateMigrateJSON(ctx context.Context, opts ...StateMigrateOption) (iter.Seq[NextMessage], error) {
+	err := tf.compatible(ctx, tf1_18_0, nil)
+	if err != nil {
+		return nil, fmt.Errorf("terraform state migrate -json was added in 1.18.0: %w", err)
+	}
+
+	cmd, err := tf.stateMigrateJSONCmd(ctx, opts...)
+	if err != nil {
+		return nil, err
+	}
+
+	return tf.runTerraformCmdJSONLog(ctx, cmd), nil
+}
+
+func (tf *Terraform) stateMigrateJSONCmd(ctx context.Context, opts ...StateMigrateOption) (*exec.Cmd, error) {
+	c := defaultStateMigrateOptions
+
+	for _, o := range opts {
+		o.configureStateMigrate(&c)
+	}
+
+	mergeEnv := map[string]string{}
+	if c.reattachInfo != nil {
+		reattachStr, err := c.reattachInfo.marshalString()
+		if err != nil {
+			return nil, err
+		}
+		mergeEnv[reattachEnvVar] = reattachStr
+	}
+
+	args := tf.buildStateMigrateArgs(c)
+
+	return tf.buildTerraformCmd(ctx, mergeEnv, args...), nil
+}
+
+func (tf *Terraform) buildStateMigrateArgs(c stateMigrateConfig) []string {
+	args := []string{
+		"state", "migrate",
+		"-no-color",
+		"-input=false",
+		"-force-copy",
+		"-json",
+	}
+
+	if c.srcProviderLockFile != "" {
+		args = append(args, "-source-provider-lock-file="+c.srcProviderLockFile)
+	}
+	if c.dstProviderLockFile != "" {
+		args = append(args, "-destination-provider-lock-file="+c.dstProviderLockFile)
+	}
+	if c.upgrade {
+		args = append(args, "-upgrade")
+	}
+	return args
+}
diff --git a/tfexec/state_migrate_test.go b/tfexec/state_migrate_test.go
new file mode 100644
index 0000000..dda27ca
--- /dev/null
+++ b/tfexec/state_migrate_test.go
@@ -0,0 +1,86 @@
+// Copyright IBM Corp. 2020, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package tfexec
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hashicorp/terraform-exec/tfexec/internal/testutil"
+)
+
+func TestStateMigrateJSONCmd(t *testing.T) {
+	td := t.TempDir()
+
+	tf, err := NewTerraform(td, tfVersion(t, testutil.Latest_v1))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// empty env, to avoid environ mismatch in testing
+	tf.SetEnv(map[string]string{})
+
+	t.Run("defaults", func(t *testing.T) {
+		stateMigrateJSONCmd, err := tf.stateMigrateJSONCmd(context.Background())
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		assertCmd(t, []string{
+			"state",
+			"migrate",
+			"-no-color",
+			"-input=false",
+			"-force-copy",
+			"-json",
+		}, nil, stateMigrateJSONCmd)
+	})
+
+	t.Run("override all defaults", func(t *testing.T) {
+		stateMigrateJSONCmd, err := tf.stateMigrateJSONCmd(context.Background(),
+			SourceProviderLockFile("src.lock.hcl"),
+			DestinationProviderLockFile("dst.lock.hcl"),
+			Upgrade(true))
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		assertCmd(t, []string{
+			"state",
+			"migrate",
+			"-no-color",
+			"-input=false",
+			"-force-copy",
+			"-json",
+			"-source-provider-lock-file=src.lock.hcl",
+			"-destination-provider-lock-file=dst.lock.hcl",
+			"-upgrade",
+		}, nil, stateMigrateJSONCmd)
+	})
+
+	t.Run("reattach config", func(t *testing.T) {
+		stateMigrateCmd, err := tf.stateMigrateJSONCmd(context.Background(), Reattach(map[string]ReattachConfig{
+			"registry.terraform.io/hashicorp/examplecloud": {
+				Protocol:        "grpc",
+				ProtocolVersion: 6,
+				Pid:             1234,
+				Test:            true,
+				Addr: ReattachConfigAddr{
+					Network: "unix",
+					String:  "/fake_folder/T/plugin123",
+				},
+			},
+		}))
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		assertCmd(t, []string{
+			"state", "migrate",
+			"-no-color", "-input=false", "-force-copy", "-json",
+		}, map[string]string{
+			"TF_REATTACH_PROVIDERS": `{"registry.terraform.io/hashicorp/examplecloud":{"Protocol":"grpc","ProtocolVersion":6,"Pid":1234,"Test":true,"Addr":{"Network":"unix","String":"/fake_folder/T/plugin123"}}}`,
+		}, stateMigrateCmd)
+	})
+}
diff --git a/tfexec/version.go b/tfexec/version.go
index 751c9b2..aeef247 100644
--- a/tfexec/version.go
+++ b/tfexec/version.go
@@ -40,6 +40,7 @@
 	tf1_13_0 = version.Must(version.NewVersion("1.13.0"))
 	tf1_14_0 = version.Must(version.NewVersion("1.14.0"))
 	tf1_16_0 = version.Must(version.NewVersion("1.16.0"))
+	tf1_18_0 = version.Must(version.NewVersion("1.18.0"))
 )
 
 // Version returns structured output from the terraform version command including both the Terraform CLI version