feat(app): CentralMigrator interface + CLI central-mode migrate routing

Author: juicycleff

app.go

@@ -45,9 +45,20 @@ type App interface {
 	// Configuration queries
 	MigrationsDisabled() bool
 
+	// SetMigrationsDisabled overrides the DisableMigrations config flag at
+	// runtime. CLI commands call this before app.Start() to prevent the
+	// PhaseAfterRegister forward-migration hook from running when rolling back
+	// or inspecting status.
+	SetMigrationsDisabled(v bool)
+
 	// CentralMigrationsEnabled reports whether the single-pass migration
 	// lifecycle is enabled.
 	CentralMigrationsEnabled() bool
+
+	// CentralMigrator resolves the CentralMigrator registered in the DI
+	// container (ok=true) or returns nil, false when nothing has been
+	// contributed (e.g. no grove extension or CentralMigrations is off).
+	CentralMigrator() (CentralMigrator, bool)
 }
 
 // AppConfig configures the application.

app_impl.go

@@ -483,12 +483,34 @@ func (a *app) MigrationsDisabled() bool {
 	return a.config.DisableMigrations
 }
 
+// SetMigrationsDisabled overrides the DisableMigrations config flag at runtime.
+func (a *app) SetMigrationsDisabled(v bool) {
+	a.config.DisableMigrations = v
+}
+
 // CentralMigrationsEnabled reports whether the single-pass migration lifecycle
 // is enabled via config or .forge.yaml.
 func (a *app) CentralMigrationsEnabled() bool {
 	return a.config.CentralMigrations
 }
 
+// CentralMigrator resolves the CentralMigrator registered in the DI container.
+// Returns nil, false when the container is nil or no CentralMigrator has been
+// contributed (e.g. CentralMigrations is disabled or grove is not registered).
+func (a *app) CentralMigrator() (CentralMigrator, bool) {
+	if a.container == nil {
+		return nil, false
+	}
+	if !vessel.HasType[CentralMigrator](a.container) {
+		return nil, false
+	}
+	cm, err := vessel.Inject[CentralMigrator](a.container)
+	if err != nil {
+		return nil, false
+	}
+	return cm, true
+}
+
 // StartTime returns the application start time.
 func (a *app) StartTime() time.Time {
 	a.mu.RLock()

central_migrator.go

@@ -0,0 +1,11 @@
+package forge
+
+import "context"
+
+// CentralMigrator runs all extension migrations as one ordered set per database.
+// The grove MigrationRegistry implements it; it is resolved from the DI container.
+type CentralMigrator interface {
+	RunAll(ctx context.Context) (*MigrationResult, error)
+	RollbackAll(ctx context.Context) (*MigrationResult, error)
+	StatusAll(ctx context.Context) ([]*MigrationGroupInfo, error)
+}

central_migrator_test.go

@@ -0,0 +1,152 @@
+package forge
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/xraph/forge/internal/logger"
+	"github.com/xraph/vessel"
+)
+
+// fakeCentralMigrator is a recording fake that satisfies the CentralMigrator interface.
+type fakeCentralMigrator struct {
+	runAllCalled      bool
+	rollbackAllCalled bool
+	statusAllCalled   bool
+
+	runAllResult      *MigrationResult
+	rollbackAllResult *MigrationResult
+	statusAllResult   []*MigrationGroupInfo
+}
+
+func newFakeCentralMigrator() *fakeCentralMigrator {
+	return &fakeCentralMigrator{
+		runAllResult: &MigrationResult{Applied: 2, Names: []string{"001_init", "002_users"}},
+		rollbackAllResult: &MigrationResult{RolledBack: 1, Names: []string{"002_users"}},
+		statusAllResult: []*MigrationGroupInfo{
+			{
+				Name: "core",
+				Applied: []*MigrationInfo{
+					{Version: "001", Name: "init", AppliedAt: "2024-01-01T00:00:00Z"},
+				},
+				Pending: []*MigrationInfo{
+					{Version: "002", Name: "users"},
+				},
+			},
+		},
+	}
+}
+
+func (f *fakeCentralMigrator) RunAll(_ context.Context) (*MigrationResult, error) {
+	f.runAllCalled = true
+	return f.runAllResult, nil
+}
+
+func (f *fakeCentralMigrator) RollbackAll(_ context.Context) (*MigrationResult, error) {
+	f.rollbackAllCalled = true
+	return f.rollbackAllResult, nil
+}
+
+func (f *fakeCentralMigrator) StatusAll(_ context.Context) ([]*MigrationGroupInfo, error) {
+	f.statusAllCalled = true
+	return f.statusAllResult, nil
+}
+
+// Compile-time assertion: fakeCentralMigrator satisfies CentralMigrator.
+var _ CentralMigrator = (*fakeCentralMigrator)(nil)
+
+// TestApp_CentralMigratorResolves verifies that CentralMigrator() returns the
+// implementation when one is registered in the container, and ok=false otherwise.
+func TestApp_CentralMigratorResolves(t *testing.T) {
+	t.Run("ReturnsFalseWhenNothingRegistered", func(t *testing.T) {
+		testLogger := logger.NewTestLogger()
+		a := NewApp(AppConfig{Logger: testLogger})
+		cm, ok := a.CentralMigrator()
+		assert.False(t, ok, "CentralMigrator() should return false when nothing is registered")
+		assert.Nil(t, cm)
+	})
+
+	t.Run("ReturnsTrueWhenRegistered", func(t *testing.T) {
+		testLogger := logger.NewTestLogger()
+		a := NewApp(AppConfig{Logger: testLogger, CentralMigrations: true})
+
+		fake := newFakeCentralMigrator()
+		err := vessel.ProvideValue[CentralMigrator](a.Container(), fake)
+		require.NoError(t, err, "ProvideValue should succeed")
+
+		cm, ok := a.CentralMigrator()
+		assert.True(t, ok, "CentralMigrator() should return true when registered")
+		assert.NotNil(t, cm)
+
+		// Verify it's the same instance we registered.
+		result, err := cm.RunAll(context.Background())
+		require.NoError(t, err)
+		assert.Equal(t, 2, result.Applied)
+		assert.True(t, fake.runAllCalled)
+	})
+}
+
+// TestApp_SetMigrationsDisabled verifies the runtime setter toggles the config flag.
+func TestApp_SetMigrationsDisabled(t *testing.T) {
+	testLogger := logger.NewTestLogger()
+	a := NewApp(AppConfig{Logger: testLogger})
+
+	assert.False(t, a.MigrationsDisabled(), "should be false by default")
+
+	a.SetMigrationsDisabled(true)
+	assert.True(t, a.MigrationsDisabled(), "should be true after SetMigrationsDisabled(true)")
+
+	a.SetMigrationsDisabled(false)
+	assert.False(t, a.MigrationsDisabled(), "should be false after SetMigrationsDisabled(false)")
+}
+
+// TestApp_SetMigrationsDisabledViaConfig verifies the initial config flag is respected.
+func TestApp_SetMigrationsDisabledViaConfig(t *testing.T) {
+	testLogger := logger.NewTestLogger()
+	a := NewApp(AppConfig{Logger: testLogger, DisableMigrations: true})
+	assert.True(t, a.MigrationsDisabled())
+
+	// Override at runtime.
+	a.SetMigrationsDisabled(false)
+	assert.False(t, a.MigrationsDisabled())
+}
+
+// TestApp_CentralMigratorFakeCallsThrough verifies each method on the fake
+// records the call and returns the expected canned result.
+func TestApp_CentralMigratorFakeCallsThrough(t *testing.T) {
+	testLogger := logger.NewTestLogger()
+	a := NewApp(AppConfig{Logger: testLogger})
+
+	fake := newFakeCentralMigrator()
+	require.NoError(t, vessel.ProvideValue[CentralMigrator](a.Container(), fake))
+
+	cm, ok := a.CentralMigrator()
+	require.True(t, ok)
+
+	ctx := context.Background()
+
+	// RunAll
+	r, err := cm.RunAll(ctx)
+	require.NoError(t, err)
+	assert.True(t, fake.runAllCalled)
+	assert.Equal(t, 2, r.Applied)
+	assert.Equal(t, []string{"001_init", "002_users"}, r.Names)
+
+	// RollbackAll
+	rb, err := cm.RollbackAll(ctx)
+	require.NoError(t, err)
+	assert.True(t, fake.rollbackAllCalled)
+	assert.Equal(t, 1, rb.RolledBack)
+	assert.Equal(t, []string{"002_users"}, rb.Names)
+
+	// StatusAll
+	groups, err := cm.StatusAll(ctx)
+	require.NoError(t, err)
+	assert.True(t, fake.statusAllCalled)
+	require.Len(t, groups, 1)
+	assert.Equal(t, "core", groups[0].Name)
+	require.Len(t, groups[0].Applied, 1)
+	require.Len(t, groups[0].Pending, 1)
+}