feat: connect to a cloud session (#4776)

* feat: connect to a cloud session

* fix: docs

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

docs/commands/dev.md

@@ -28,6 +28,7 @@ netlify dev
 - `live` (*boolean*) - start a public live session
 - `offline` (*boolean*) - disables any features that require network access
 - `port` (*string*) - port of netlify dev
+- `sessionId` (*string*) - (Graph) connect to cloud session with ID [sessionId]
 - `targetPort` (*string*) - port of target app server
 - `debug` (*boolean*) - Print debugging information
 - `httpProxy` (*string*) - Proxy server address to route requests through.

src/commands/dev/dev.js

@@ -501,7 +501,13 @@ const dev = async (options, command) => {
         graphqlDocument = defaultExampleOperationsDoc
       }
 
-      stopWatchingCLISessions = await startOneGraphCLISession({ netlifyGraphConfig, netlifyToken, site, state })
+      stopWatchingCLISessions = await startOneGraphCLISession({
+        netlifyGraphConfig,
+        netlifyToken,
+        site,
+        state,
+        oneGraphSessionId: options.sessionId,
+      })
 
       // Should be created by startOneGraphCLISession
       const oneGraphSessionId = loadCLISession(state)
@@ -599,6 +605,7 @@ const createDevCommand = (program) => {
         .hideHelp(),
     )
     .addOption(new Option('--graph', 'enable Netlify Graph support').hideHelp())
+    .addOption(new Option('--sessionId [sessionId]', '(Graph) connect to cloud session with ID [sessionId]'))
     .addOption(
       new Option(
         '-e, --edgeInspect [address]',

src/lib/one-graph/cli-client.js

@@ -535,6 +535,7 @@ const loadCLISession = (state) => state.get('oneGraphSessionId')
  * Idemponentially save the CLI session id to the local state and start monitoring for CLI events, upstream schema changes, and local operation file changes
  * @param {object} input
  * @param {string} input.netlifyToken The (typically netlify) access token that is used for authentication, if any
+ * @param {string | undefined} input.oneGraphSessionId The session ID to use for this CLI session (default: read from state)
  * @param {NetlifyGraph.NetlifyGraphConfig} input.netlifyGraphConfig A standalone config object that contains all the information necessary for Netlify Graph to process events
  * @param {StateConfig} input.state A function to call to set/get the current state of the local Netlify project
  * @param {any} input.site The site object
@@ -548,6 +549,7 @@ const startOneGraphCLISession = async (input) => {
     netlifyToken,
     site,
     state,
+    oneGraphSessionId: input.oneGraphSessionId,
   })
 
   const enabledServices = []
@@ -657,8 +659,9 @@ const generateSessionName = () => {
 /**
  * Ensures a cli session exists for the current checkout, or errors out if it doesn't and cannot create one.
  */
-const ensureCLISession = async ({ metadata, netlifyToken, site, state }) => {
-  let oneGraphSessionId = loadCLISession(state)
+const ensureCLISession = async (input) => {
+  const { metadata, netlifyToken, site, state } = input
+  let oneGraphSessionId = input.oneGraphSessionId ? input.oneGraphSessionId : loadCLISession(state)
   let parentCliSessionId = null
 
   // Validate that session still exists and we can access it
@@ -697,14 +700,14 @@ const ensureCLISession = async ({ metadata, netlifyToken, site, state }) => {
       sessionName,
       metadata: sessionMetadata,
     })
-    state.set('oneGraphSessionId', oneGraphSession.id)
-    oneGraphSessionId = state.get('oneGraphSessionId')
+    oneGraphSessionId = oneGraphSession.id
   }
 
   if (!oneGraphSessionId) {
     error('Unable to create or access Netlify Graph CLI session')
   }
 
+  state.set('oneGraphSessionId', oneGraphSessionId)
   const { errors: markCLISessionActiveErrors } = await executeMarkCliSessionActiveHeartbeat(
     netlifyToken,
     site.id,