add review-notifications enable and poll-interval flags

Review notifications are gated by a dedicated flag family, deliberately
not a capability group: the feature is client-side mechanics, not a
Gerrit operation class. --review-notifications (default off) and
--review-notifications-poll-interval (default 60s) follow the
established flag-over-mirror-over-default precedence with
GERRIT_MCP_REVIEW_NOTIFICATIONS* mirrors.

The interval is resolved and validated even when the feature is off, so
a typo fails loudly at startup instead of surfacing on a later enable.
Unparsable and non-positive intervals join the aggregated startup error
naming the flag and value.

Refs: #50

Author: xobotyi

internal/config/config.go

@@ -12,6 +12,7 @@ import (
 	"io"
 	"strconv"
 	"strings"
+	"time"
 
 	"dev.gaijin.team/go/golib/e"
 	"dev.gaijin.team/go/golib/fields"
@@ -31,6 +32,8 @@ const (
 
 const defaultGroups = "read"
 
+const defaultPollInterval = "60s"
+
 // Env variable names for connection identity and credentials.
 const (
 	EnvURL      = "GERRIT_URL"
@@ -39,11 +42,13 @@ const (
 )
 
 var (
-	errEnvMissing    = e.New("required environment variable is not set")
-	errUnknownGroups = e.New("unknown capability groups")
-	errNoGroups      = e.New("no capability groups enabled")
-	errParseFlags    = e.New("parse flags")
-	errInvalidBool   = e.New("invalid boolean flag value")
+	errEnvMissing          = e.New("required environment variable is not set")
+	errUnknownGroups       = e.New("unknown capability groups")
+	errNoGroups            = e.New("no capability groups enabled")
+	errParseFlags          = e.New("parse flags")
+	errInvalidBool         = e.New("invalid boolean flag value")
+	errInvalidDuration     = e.New("invalid duration flag value")
+	errIntervalNotPositive = e.New("poll interval must be positive")
 )
 
 // Config is the resolved server configuration.
@@ -68,6 +73,14 @@ type Config struct {
 	// (the default), trail-leaving operations are refused on changes not
 	// owned by the authenticated account.
 	AllowForeignChanges bool
+	// ReviewNotifications enables the review-notifications feature: polling
+	// Gerrit for activity on subscribed changes and pushing it into the
+	// agent's session. Off by default.
+	ReviewNotifications bool
+	// ReviewNotificationsPollInterval is the cadence of the review
+	// notifications poller. Always resolved and validated, even when the
+	// feature is disabled.
+	ReviewNotificationsPollInterval time.Duration
 }
 
 // behaviorFlag is one CLI flag with its GERRIT_MCP_* env mirror. The flag
@@ -115,21 +128,37 @@ func Load(args []string, getenv func(string) string) (*Config, error) {
 		usage:    "refuse trail-leaving operations on changes not owned by the authenticated account",
 		fallback: "true",
 	}
+	reviewNotifications := behaviorFlag{
+		name:     "review-notifications",
+		mirror:   "GERRIT_MCP_REVIEW_NOTIFICATIONS",
+		usage:    "poll Gerrit for activity on subscribed changes and push it into the agent's session",
+		fallback: "false",
+	}
+	pollInterval := behaviorFlag{
+		name:     "review-notifications-poll-interval",
+		mirror:   "GERRIT_MCP_REVIEW_NOTIFICATIONS_POLL_INTERVAL",
+		usage:    "cadence of the review notifications poller, as a Go duration (e.g. 60s)",
+		fallback: defaultPollInterval,
+	}
 
-	err := resolveFlags(args, getenv, []*behaviorFlag{&groups, &includeTools, &excludeTools, &projects, &ownChanges})
+	err := resolveFlags(args, getenv, []*behaviorFlag{
+		&groups, &includeTools, &excludeTools, &projects, &ownChanges, &reviewNotifications, &pollInterval,
+	})
 	if err != nil {
 		return nil, err
 	}
 
 	cfg := &Config{
-		GerritURL:           getenv(EnvURL),
-		Username:            getenv(EnvUsername),
-		Token:               getenv(EnvToken),
-		Groups:              nil,
-		IncludeTools:        splitList(includeTools.value),
-		ExcludeTools:        splitList(excludeTools.value),
-		Projects:            splitList(projects.value),
-		AllowForeignChanges: false,
+		GerritURL:                       getenv(EnvURL),
+		Username:                        getenv(EnvUsername),
+		Token:                           getenv(EnvToken),
+		Groups:                          nil,
+		IncludeTools:                    splitList(includeTools.value),
+		ExcludeTools:                    splitList(excludeTools.value),
+		Projects:                        splitList(projects.value),
+		AllowForeignChanges:             false,
+		ReviewNotifications:             false,
+		ReviewNotificationsPollInterval: 0,
 	}
 
 	errs := missingEnv(cfg)
@@ -141,6 +170,20 @@ func Load(args []string, getenv func(string) string) (*Config, error) {
 		cfg.AllowForeignChanges = !ownOnly
 	}
 
+	notifications, err := parseBool(reviewNotifications)
+	if err != nil {
+		errs = append(errs, err)
+	} else {
+		cfg.ReviewNotifications = notifications
+	}
+
+	interval, err := parsePollInterval(pollInterval)
+	if err != nil {
+		errs = append(errs, err)
+	} else {
+		cfg.ReviewNotificationsPollInterval = interval
+	}
+
 	parsed, err := parseGroups(groups.value)
 	if err != nil {
 		errs = append(errs, err)
@@ -217,6 +260,28 @@ func parseBool(bf behaviorFlag) (bool, error) {
 	return v, nil
 }
 
+// parsePollInterval parses a resolved duration flag value and rejects
+// non-positive intervals, naming the flag and the offending value in the
+// error.
+func parsePollInterval(bf behaviorFlag) (time.Duration, error) {
+	d, err := time.ParseDuration(strings.TrimSpace(bf.value))
+	if err != nil {
+		return 0, errInvalidDuration.WithFields(
+			fields.F("flag", bf.name),
+			fields.F("value", bf.value),
+		)
+	}
+
+	if d <= 0 {
+		return 0, errIntervalNotPositive.WithFields(
+			fields.F("flag", bf.name),
+			fields.F("value", bf.value),
+		)
+	}
+
+	return d, nil
+}
+
 // splitList splits a comma-separated list, trimming whitespace and dropping
 // empty entries. An empty input yields nil.
 func splitList(s string) []string {

internal/config/config_test.go

@@ -2,6 +2,7 @@ package config_test
 
 import (
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -247,6 +248,133 @@ func Test_Load_OwnChanges(t *testing.T) {
 	})
 }
 
+func Test_Load_ReviewNotifications(t *testing.T) {
+	t.Parallel()
+
+	t.Run("zero config leaves the feature disabled with the default interval", func(t *testing.T) {
+		t.Parallel()
+
+		cfg, err := config.Load(nil, env(secrets()))
+		require.NoError(t, err)
+		assert.False(t, cfg.ReviewNotifications)
+		assert.Equal(t, 60*time.Second, cfg.ReviewNotificationsPollInterval)
+	})
+
+	t.Run("flag enables", func(t *testing.T) {
+		t.Parallel()
+
+		cfg, err := config.Load([]string{"--review-notifications", "true"}, env(secrets()))
+		require.NoError(t, err)
+		assert.True(t, cfg.ReviewNotifications)
+	})
+
+	t.Run("env mirror enables", func(t *testing.T) {
+		t.Parallel()
+
+		m := secrets()
+
+		m["GERRIT_MCP_REVIEW_NOTIFICATIONS"] = "true"
+
+		cfg, err := config.Load(nil, env(m))
+		require.NoError(t, err)
+		assert.True(t, cfg.ReviewNotifications)
+	})
+
+	t.Run("enable flag wins over env mirror", func(t *testing.T) {
+		t.Parallel()
+
+		m := secrets()
+
+		m["GERRIT_MCP_REVIEW_NOTIFICATIONS"] = "true"
+
+		cfg, err := config.Load([]string{"--review-notifications=false"}, env(m))
+		require.NoError(t, err)
+		assert.False(t, cfg.ReviewNotifications)
+	})
+
+	t.Run("interval resolves from flag", func(t *testing.T) {
+		t.Parallel()
+
+		cfg, err := config.Load([]string{"--review-notifications-poll-interval", "2m"}, env(secrets()))
+		require.NoError(t, err)
+		assert.Equal(t, 2*time.Minute, cfg.ReviewNotificationsPollInterval)
+	})
+
+	t.Run("interval resolves from env mirror", func(t *testing.T) {
+		t.Parallel()
+
+		m := secrets()
+
+		m["GERRIT_MCP_REVIEW_NOTIFICATIONS_POLL_INTERVAL"] = "30s"
+
+		cfg, err := config.Load(nil, env(m))
+		require.NoError(t, err)
+		assert.Equal(t, 30*time.Second, cfg.ReviewNotificationsPollInterval)
+	})
+
+	t.Run("interval flag wins over env mirror", func(t *testing.T) {
+		t.Parallel()
+
+		m := secrets()
+
+		m["GERRIT_MCP_REVIEW_NOTIFICATIONS_POLL_INTERVAL"] = "30s"
+
+		cfg, err := config.Load([]string{"--review-notifications-poll-interval", "90s"}, env(m))
+		require.NoError(t, err)
+		assert.Equal(t, 90*time.Second, cfg.ReviewNotificationsPollInterval)
+	})
+
+	t.Run("invalid enable value names the flag", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := config.Load([]string{"--review-notifications", "nope"}, env(secrets()))
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "invalid boolean flag value")
+		assert.ErrorContains(t, err, "review-notifications")
+		assert.ErrorContains(t, err, "nope")
+	})
+
+	t.Run("unparsable interval names the flag and value", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := config.Load([]string{"--review-notifications-poll-interval", "soon"}, env(secrets()))
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "invalid duration flag value")
+		assert.ErrorContains(t, err, "review-notifications-poll-interval")
+		assert.ErrorContains(t, err, "soon")
+	})
+
+	t.Run("zero interval rejected", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := config.Load([]string{"--review-notifications-poll-interval", "0s"}, env(secrets()))
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "poll interval must be positive")
+		assert.ErrorContains(t, err, "0s")
+	})
+
+	t.Run("negative interval rejected", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := config.Load([]string{"--review-notifications-poll-interval", "-15s"}, env(secrets()))
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "poll interval must be positive")
+		assert.ErrorContains(t, err, "-15s")
+	})
+
+	t.Run("interval error aggregates with other errors", func(t *testing.T) {
+		t.Parallel()
+
+		m := secrets()
+		delete(m, "GERRIT_TOKEN")
+
+		_, err := config.Load([]string{"--review-notifications-poll-interval", "never"}, env(m))
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "invalid duration flag value")
+		assert.ErrorContains(t, err, "GERRIT_TOKEN")
+	})
+}
+
 func Test_Load_Connection(t *testing.T) {
 	t.Parallel()
 

internal/gerritclient/gerritclient_test.go

@@ -15,14 +15,16 @@ import (
 
 func testConfig(url string) *config.Config {
 	return &config.Config{
-		GerritURL:           url,
-		Username:            "bot",
-		Token:               "s3cret",
-		Groups:              []config.Group{config.GroupRead},
-		IncludeTools:        nil,
-		ExcludeTools:        nil,
-		Projects:            nil,
-		AllowForeignChanges: false,
+		GerritURL:                       url,
+		Username:                        "bot",
+		Token:                           "s3cret",
+		Groups:                          []config.Group{config.GroupRead},
+		IncludeTools:                    nil,
+		ExcludeTools:                    nil,
+		Projects:                        nil,
+		AllowForeignChanges:             false,
+		ReviewNotifications:             false,
+		ReviewNotificationsPollInterval: 0,
 	}
 }
 

internal/registry/registry_test.go

@@ -13,14 +13,16 @@ import (
 
 func cfg(groups []config.Group, include, exclude []string) *config.Config {
 	return &config.Config{
-		GerritURL:           "https://gerrit.example.com",
-		Username:            "bot",
-		Token:               "s3cret",
-		Groups:              groups,
-		IncludeTools:        include,
-		ExcludeTools:        exclude,
-		Projects:            nil,
-		AllowForeignChanges: false,
+		GerritURL:                       "https://gerrit.example.com",
+		Username:                        "bot",
+		Token:                           "s3cret",
+		Groups:                          groups,
+		IncludeTools:                    include,
+		ExcludeTools:                    exclude,
+		Projects:                        nil,
+		AllowForeignChanges:             false,
+		ReviewNotifications:             false,
+		ReviewNotificationsPollInterval: 0,
 	}
 }
 

internal/tools/get-change_test.go

@@ -53,14 +53,16 @@ func session(t *testing.T, gerritHandler http.HandlerFunc, mutate ...func(*confi
 	t.Cleanup(srv.Close)
 
 	cfg := &config.Config{
-		GerritURL:           srv.URL,
-		Username:            "bot",
-		Token:               "s3cret",
-		Groups:              []config.Group{config.GroupRead},
-		IncludeTools:        nil,
-		ExcludeTools:        nil,
-		Projects:            nil,
-		AllowForeignChanges: false,
+		GerritURL:                       srv.URL,
+		Username:                        "bot",
+		Token:                           "s3cret",
+		Groups:                          []config.Group{config.GroupRead},
+		IncludeTools:                    nil,
+		ExcludeTools:                    nil,
+		Projects:                        nil,
+		AllowForeignChanges:             false,
+		ReviewNotifications:             false,
+		ReviewNotificationsPollInterval: 0,
 	}
 	for _, m := range mutate {
 		m(cfg)