address PR comment

added a paragraph about the server/client architecture to the agents.md
addresed the PR comment

Author: chupe

AGENTS.md

@@ -107,3 +107,27 @@ These checks must be the final tasks before considering work complete.
 | `log/`    | Logging utilities                |
 | `util/`   | Context helpers                  |
 | `tests/`  | Python E2E tests                 |
+
+## CLI Architecture (Server + Client)
+
+PCSM uses a single binary that operates in two modes:
+
+### Server Mode (Root Command)
+
+Running `pcsm --source <uri> --target <uri>` starts a **long-running server process**:
+
+1. Connects to source and target MongoDB clusters
+2. Creates `pcsm.PCSM` instance with real MongoDB clients
+3. Starts HTTP server on `localhost:<port>` (default 27018)
+4. Exposes REST endpoints: `/status`, `/start`, `/pause`, `/resume`, `/finalize`
+
+The server holds MongoDB connections and manages the replication state machine.
+
+### Client Mode (Subcommands)
+
+Running `pcsm start`, `pcsm pause`, etc. operates as an **HTTP client**:
+
+1. Creates `PCSMClient` with just the port number
+2. Constructs HTTP request with JSON body
+3. Sends request to the already-running server
+4. Prints JSON response to stdout

pcsm/state_test.go

@@ -9,37 +9,32 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func TestStartCommand_StateValidation(t *testing.T) {
+func TestStart_StateValidation(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
 		name          string
 		initialState  State
-		expectError   bool
 		errorContains string
 	}{
 		{
 			name:          "fails from running state",
 			initialState:  StateRunning,
-			expectError:   true,
 			errorContains: "already running",
 		},
 		{
 			name:          "fails from paused state",
 			initialState:  StatePaused,
-			expectError:   true,
 			errorContains: "paused",
 		},
 		{
 			name:          "fails from failed state",
 			initialState:  StateFailed,
-			expectError:   true,
 			errorContains: "already running",
 		},
 		{
 			name:          "fails from finalizing state",
 			initialState:  StateFinalizing,
-			expectError:   true,
 			errorContains: "already running",
 		},
 	}
@@ -55,62 +50,51 @@ func TestStartCommand_StateValidation(t *testing.T) {
 
 			err := p.Start(context.Background(), nil)
 
-			if tt.expectError {
-				require.Error(t, err)
-				assert.Contains(t, err.Error(), tt.errorContains)
-				assert.Equal(t, tt.initialState, p.state)
-			}
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tt.errorContains)
+			assert.Equal(t, tt.initialState, p.state)
 		})
 	}
 }
 
-func TestPauseCommand_StateValidation(t *testing.T) {
+func TestPause_StateValidation(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
 		name          string
 		initialState  State
 		setupRepl     bool
-		replRunning   bool
-		expectError   bool
 		errorContains string
 	}{
 		{
 			name:          "fails from idle state",
 			initialState:  StateIdle,
-			expectError:   true,
 			errorContains: "not running",
 		},
 		{
 			name:          "fails from paused state",
 			initialState:  StatePaused,
-			expectError:   true,
 			errorContains: "not running",
 		},
 		{
 			name:          "fails from failed state",
 			initialState:  StateFailed,
-			expectError:   true,
 			errorContains: "not running",
 		},
 		{
 			name:          "fails from finalizing state",
 			initialState:  StateFinalizing,
-			expectError:   true,
 			errorContains: "not running",
 		},
 		{
 			name:          "fails from finalized state",
 			initialState:  StateFinalized,
-			expectError:   true,
 			errorContains: "not running",
 		},
 		{
 			name:          "fails from running when repl not actually running",
 			initialState:  StateRunning,
 			setupRepl:     true,
-			replRunning:   false,
-			expectError:   true,
 			errorContains: "Change Replication is not running",
 		},
 	}
@@ -129,78 +113,60 @@ func TestPauseCommand_StateValidation(t *testing.T) {
 					pauseC:  make(chan struct{}),
 					doneSig: make(chan struct{}),
 				}
-				if tt.replRunning {
-					p.repl.startTime = time.Now()
-				}
 			}
 
 			err := p.Pause(context.Background())
 
-			if tt.expectError {
-				require.Error(t, err)
-				assert.Contains(t, err.Error(), tt.errorContains)
-			}
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tt.errorContains)
 		})
 	}
 }
 
-func TestResumeCommand_StateValidation(t *testing.T) {
+func TestResume_StateValidation(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
 		name          string
 		initialState  State
 		fromFailure   bool
-		expectError   bool
 		errorContains string
 	}{
 		{
 			name:          "fails from idle state",
 			initialState:  StateIdle,
-			fromFailure:   false,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 		{
 			name:          "fails from running state",
 			initialState:  StateRunning,
-			fromFailure:   false,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 		{
 			name:          "fails from failed state without fromFailure flag",
 			initialState:  StateFailed,
-			fromFailure:   false,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 		{
 			name:          "fails from finalizing state",
 			initialState:  StateFinalizing,
-			fromFailure:   false,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 		{
 			name:          "fails from finalized state",
 			initialState:  StateFinalized,
-			fromFailure:   false,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 		{
 			name:          "fails from idle even with fromFailure flag",
 			initialState:  StateIdle,
 			fromFailure:   true,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 		{
 			name:          "fails from running even with fromFailure flag",
 			initialState:  StateRunning,
 			fromFailure:   true,
-			expectError:   true,
 			errorContains: "cannot resume",
 		},
 	}
@@ -225,87 +191,73 @@ func TestResumeCommand_StateValidation(t *testing.T) {
 				ResumeFromFailure: tt.fromFailure,
 			})
 
-			if tt.expectError {
-				require.Error(t, err)
-				assert.Contains(t, err.Error(), tt.errorContains)
-			}
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tt.errorContains)
 		})
 	}
 }
 
-func TestFinalizeCommand_FailedStateValidation(t *testing.T) {
+func TestFinalize_FailsFromFailedStateWithoutIgnoreHistoryLost(t *testing.T) {
 	t.Parallel()
 
-	t.Run("fails from failed state without ignoreHistoryLost", func(t *testing.T) {
-		t.Parallel()
-
-		p := &PCSM{
-			state:          StateFailed,
-			onStateChanged: func(State) {},
-			err:            ErrOplogHistoryLost,
-			clone: &Clone{
-				doneSig: make(chan struct{}),
-			},
-			repl: &Repl{
-				pauseC:  make(chan struct{}),
-				doneSig: make(chan struct{}),
-			},
-		}
-
-		err := p.Finalize(context.Background(), FinalizeOptions{
-			IgnoreHistoryLost: false,
-		})
+	p := &PCSM{
+		state:          StateFailed,
+		onStateChanged: func(State) {},
+		err:            ErrOplogHistoryLost,
+		clone: &Clone{
+			doneSig: make(chan struct{}),
+		},
+		repl: &Repl{
+			pauseC:  make(chan struct{}),
+			doneSig: make(chan struct{}),
+		},
+	}
 
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "failed state")
+	err := p.Finalize(context.Background(), FinalizeOptions{
+		IgnoreHistoryLost: false,
 	})
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed state")
 }
 
-func TestResumeFromPaused_ValidatesReplState(t *testing.T) {
+func TestResumeFromPaused_FailsWhenReplNotStarted(t *testing.T) {
 	t.Parallel()
 
-	t.Run("fails when repl not started and not resuming from failure", func(t *testing.T) {
-		t.Parallel()
-
-		p := &PCSM{
-			state:          StatePaused,
-			onStateChanged: func(State) {},
-			repl: &Repl{
-				pauseC:  make(chan struct{}),
-				doneSig: make(chan struct{}),
-			},
-		}
-
-		err := p.Resume(context.Background(), ResumeOptions{
-			ResumeFromFailure: false,
-		})
+	p := &PCSM{
+		state:          StatePaused,
+		onStateChanged: func(State) {},
+		repl: &Repl{
+			pauseC:  make(chan struct{}),
+			doneSig: make(chan struct{}),
+		},
+	}
 
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "replication is not started")
+	err := p.Resume(context.Background(), ResumeOptions{
+		ResumeFromFailure: false,
 	})
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "replication is not started")
 }
 
-func TestResumeFromFailed_ValidatesReplState(t *testing.T) {
+func TestResumeFromFailed_FailsWhenReplNotPaused(t *testing.T) {
 	t.Parallel()
 
-	t.Run("fails when repl not paused but resuming from failure", func(t *testing.T) {
-		t.Parallel()
-
-		p := &PCSM{
-			state:          StateFailed,
-			onStateChanged: func(State) {},
-			repl: &Repl{
-				pauseC:    make(chan struct{}),
-				doneSig:   make(chan struct{}),
-				startTime: time.Now(),
-			},
-		}
-
-		err := p.Resume(context.Background(), ResumeOptions{
-			ResumeFromFailure: true,
-		})
+	p := &PCSM{
+		state:          StateFailed,
+		onStateChanged: func(State) {},
+		repl: &Repl{
+			pauseC:    make(chan struct{}),
+			doneSig:   make(chan struct{}),
+			startTime: time.Now(),
+		},
+	}
 
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "replication is not paused")
+	err := p.Resume(context.Background(), ResumeOptions{
+		ResumeFromFailure: true,
 	})
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "replication is not paused")
 }