netlify-cli 10.14.0 → 10.15.0

package/README.md

@@ -165,7 +165,7 @@ Manage netlify functions
 | [`graph:init`](/docs/commands/graph.md#graphinit) | Initialize all the resources for Netlify Graph  |
 | [`graph:library`](/docs/commands/graph.md#graphlibrary) | Generate the Graph function library  |
 | [`graph:operations`](/docs/commands/graph.md#graphoperations) | List all of the locally available operations  |
-| [`graph:pull`](/docs/commands/graph.md#graphpull) | Pull down your local Netlify Graph schema, and process pending Graph edit events  |
+| [`graph:pull`](/docs/commands/graph.md#graphpull) | Pull your remote Netlify Graph schema locally, and process pending Graph edit events  |
 
 
 ### [init](/docs/commands/init.md)

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "netlify-cli",
-  "version": "10.14.0",
+  "version": "10.15.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "netlify-cli",
-      "version": "10.14.0",
+      "version": "10.15.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -81,7 +81,7 @@
         "multiparty": "^4.2.1",
         "netlify": "^12.0.0",
         "netlify-headers-parser": "^6.0.2",
-        "netlify-onegraph-internal": "0.4.1",
+        "netlify-onegraph-internal": "0.4.2",
         "netlify-redirect-parser": "^13.0.5",
         "netlify-redirector": "^0.2.1",
         "node-fetch": "^2.6.0",
@@ -8194,7 +8194,7 @@
     "node_modules/cpy/node_modules/glob-parent": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-3.1.0.tgz",
-      "integrity": "sha1-nmr2KZ2NO9K9QEMIMr0RPfkGxa4=",
+      "integrity": "sha512-E8Ak/2+dZY6fnzlR7+ueWvhsH1SjHr4jjss4YS/h4py44jY9MhK/VFdaZJAWDz6BbL21KeteKxFSFpq8OS5gVA==",
       "dependencies": {
         "is-glob": "^3.1.0",
         "path-dirname": "^1.0.0"
@@ -11962,9 +11962,9 @@
       }
     },
     "node_modules/follow-redirects": {
-      "version": "1.14.7",
-      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.14.7.tgz",
-      "integrity": "sha512-+hbxoLbFMbRKDwohX8GkTataGqO6Jb7jGwpAlwgy2bIz25XtRm7KEzJM76R1WiNT5SwZkX4Y75SwBolkpmE7iQ==",
+      "version": "1.15.1",
+      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.1.tgz",
+      "integrity": "sha512-yLAMQs+k0b2m7cVxpS1VKJVvoz7SS9Td1zss3XRwXj+ZDH00RJgnuLx7E44wx02kQLrdM3aOOy+FpzS7+8OizA==",
       "funding": [
         {
           "type": "individual",
@@ -12507,9 +12507,9 @@
       }
     },
     "node_modules/got": {
-      "version": "11.8.3",
-      "resolved": "https://registry.npmjs.org/got/-/got-11.8.3.tgz",
-      "integrity": "sha512-7gtQ5KiPh1RtGS9/Jbv1ofDpBFuq42gyfEib+ejaRBJuj/3tQFeR5+gw57e4ipaU8c/rCjvX6fkQz2lyDlGAOg==",
+      "version": "11.8.5",
+      "resolved": "https://registry.npmjs.org/got/-/got-11.8.5.tgz",
+      "integrity": "sha512-o0Je4NvQObAuZPHLFoRSkdG2lTgtcynqymzg2Vupdx6PorhaT5MCbIyXG6d4D94kk8ZG57QeosgdiqfJWhEhlQ==",
       "dev": true,
       "dependencies": {
         "@sindresorhus/is": "^4.0.0",
@@ -13312,9 +13312,9 @@
       }
     },
     "node_modules/inquirer/node_modules/ansi-regex": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.0.tgz",
-      "integrity": "sha512-1apePfXM1UOSqw0o9IiFAovVz9M5S1Dg+4TrDwfMewQ6p/rmMueb7tWZjQ1rx4Loy1ArBggoqGpfqqdI4rondg==",
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz",
+      "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==",
       "engines": {
         "node": ">=6"
       }
@@ -13391,9 +13391,9 @@
       }
     },
     "node_modules/inquirer/node_modules/string-width/node_modules/ansi-regex": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.0.tgz",
-      "integrity": "sha1-7QMXwyIGT3lGbAKWa922Bas32Zg=",
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.1.tgz",
+      "integrity": "sha512-+O9Jct8wf++lXxxFc4hc8LsjaSq0HFzzL7cVsw8pRDIPdjKD2mT4ytDZlLuSBZ4cLKZFXIrMGO7DbQCtMJJMKw==",
       "engines": {
         "node": ">=4"
       }
@@ -14842,9 +14842,9 @@
       }
     },
     "node_modules/listr-update-renderer/node_modules/wrap-ansi/node_modules/ansi-regex": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.0.tgz",
-      "integrity": "sha1-7QMXwyIGT3lGbAKWa922Bas32Zg=",
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.1.tgz",
+      "integrity": "sha512-+O9Jct8wf++lXxxFc4hc8LsjaSq0HFzzL7cVsw8pRDIPdjKD2mT4ytDZlLuSBZ4cLKZFXIrMGO7DbQCtMJJMKw==",
       "engines": {
         "node": ">=4"
       }
@@ -16384,12 +16384,13 @@
       }
     },
     "node_modules/netlify-onegraph-internal": {
-      "version": "0.4.1",
-      "resolved": "https://registry.npmjs.org/netlify-onegraph-internal/-/netlify-onegraph-internal-0.4.1.tgz",
-      "integrity": "sha512-b+9gNOJHUeFZ9DoUDYuOLxMhtfIibEO6PZKSj3Xf5TtV9k536uX2c963kldb3VQ2HfIv9S5H5iirgkXcJfzXHw==",
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/netlify-onegraph-internal/-/netlify-onegraph-internal-0.4.2.tgz",
+      "integrity": "sha512-3TGD/s2FGjx9NcOcMPMMUxamy3IVY9O0ZZ176FuHVDmLAc5l8mj0ZNoUbhdrXfZjes62Gt6/YynCJxGShE6oUA==",
       "dependencies": {
         "graphql": "16.0.0",
         "node-fetch": "^2.6.0",
+        "rusha": "^0.8.14",
         "uuid": "^8.3.2"
       }
     },
@@ -19977,6 +19978,11 @@
         "queue-microtask": "^1.2.2"
       }
     },
+    "node_modules/rusha": {
+      "version": "0.8.14",
+      "resolved": "https://registry.npmjs.org/rusha/-/rusha-0.8.14.tgz",
+      "integrity": "sha512-cLgakCUf6PedEu15t8kbsjnwIFFR2D4RfL+W3iWFJ4iac7z4B0ZI8fxy4R3J956kAI68HclCFGL8MPoUVC3qVA=="
+    },
     "node_modules/rxjs": {
       "version": "6.6.7",
       "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-6.6.7.tgz",
@@ -29028,7 +29034,7 @@
         "glob-parent": {
           "version": "3.1.0",
           "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-3.1.0.tgz",
-          "integrity": "sha1-nmr2KZ2NO9K9QEMIMr0RPfkGxa4=",
+          "integrity": "sha512-E8Ak/2+dZY6fnzlR7+ueWvhsH1SjHr4jjss4YS/h4py44jY9MhK/VFdaZJAWDz6BbL21KeteKxFSFpq8OS5gVA==",
           "requires": {
             "is-glob": "^3.1.0",
             "path-dirname": "^1.0.0"
@@ -31954,9 +31960,9 @@
       }
     },
     "follow-redirects": {
-      "version": "1.14.7",
-      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.14.7.tgz",
-      "integrity": "sha512-+hbxoLbFMbRKDwohX8GkTataGqO6Jb7jGwpAlwgy2bIz25XtRm7KEzJM76R1WiNT5SwZkX4Y75SwBolkpmE7iQ=="
+      "version": "1.15.1",
+      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.1.tgz",
+      "integrity": "sha512-yLAMQs+k0b2m7cVxpS1VKJVvoz7SS9Td1zss3XRwXj+ZDH00RJgnuLx7E44wx02kQLrdM3aOOy+FpzS7+8OizA=="
     },
     "for-in": {
       "version": "1.0.2",
@@ -32362,9 +32368,9 @@
       }
     },
     "got": {
-      "version": "11.8.3",
-      "resolved": "https://registry.npmjs.org/got/-/got-11.8.3.tgz",
-      "integrity": "sha512-7gtQ5KiPh1RtGS9/Jbv1ofDpBFuq42gyfEib+ejaRBJuj/3tQFeR5+gw57e4ipaU8c/rCjvX6fkQz2lyDlGAOg==",
+      "version": "11.8.5",
+      "resolved": "https://registry.npmjs.org/got/-/got-11.8.5.tgz",
+      "integrity": "sha512-o0Je4NvQObAuZPHLFoRSkdG2lTgtcynqymzg2Vupdx6PorhaT5MCbIyXG6d4D94kk8ZG57QeosgdiqfJWhEhlQ==",
       "dev": true,
       "requires": {
         "@sindresorhus/is": "^4.0.0",
@@ -32911,9 +32917,9 @@
           "integrity": "sha512-cBhpre4ma+U0T1oM5fXg7Dy1Jw7zzwv7lt/GoCpr+hDQJoYnKVPLL4dCvSEFMmQurOQvSrwT7SL/DAlhBI97RQ=="
         },
         "ansi-regex": {
-          "version": "4.1.0",
-          "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.0.tgz",
-          "integrity": "sha512-1apePfXM1UOSqw0o9IiFAovVz9M5S1Dg+4TrDwfMewQ6p/rmMueb7tWZjQ1rx4Loy1ArBggoqGpfqqdI4rondg=="
+          "version": "4.1.1",
+          "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz",
+          "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g=="
         },
         "ansi-styles": {
           "version": "3.2.1",
@@ -32966,9 +32972,9 @@
           },
           "dependencies": {
             "ansi-regex": {
-              "version": "3.0.0",
-              "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.0.tgz",
-              "integrity": "sha1-7QMXwyIGT3lGbAKWa922Bas32Zg="
+              "version": "3.0.1",
+              "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.1.tgz",
+              "integrity": "sha512-+O9Jct8wf++lXxxFc4hc8LsjaSq0HFzzL7cVsw8pRDIPdjKD2mT4ytDZlLuSBZ4cLKZFXIrMGO7DbQCtMJJMKw=="
             },
             "strip-ansi": {
               "version": "4.0.0",
@@ -34075,9 +34081,9 @@
           },
           "dependencies": {
             "ansi-regex": {
-              "version": "3.0.0",
-              "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.0.tgz",
-              "integrity": "sha1-7QMXwyIGT3lGbAKWa922Bas32Zg="
+              "version": "3.0.1",
+              "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.1.tgz",
+              "integrity": "sha512-+O9Jct8wf++lXxxFc4hc8LsjaSq0HFzzL7cVsw8pRDIPdjKD2mT4ytDZlLuSBZ4cLKZFXIrMGO7DbQCtMJJMKw=="
             },
             "is-fullwidth-code-point": {
               "version": "2.0.0",
@@ -35257,12 +35263,13 @@
       }
     },
     "netlify-onegraph-internal": {
-      "version": "0.4.1",
-      "resolved": "https://registry.npmjs.org/netlify-onegraph-internal/-/netlify-onegraph-internal-0.4.1.tgz",
-      "integrity": "sha512-b+9gNOJHUeFZ9DoUDYuOLxMhtfIibEO6PZKSj3Xf5TtV9k536uX2c963kldb3VQ2HfIv9S5H5iirgkXcJfzXHw==",
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/netlify-onegraph-internal/-/netlify-onegraph-internal-0.4.2.tgz",
+      "integrity": "sha512-3TGD/s2FGjx9NcOcMPMMUxamy3IVY9O0ZZ176FuHVDmLAc5l8mj0ZNoUbhdrXfZjes62Gt6/YynCJxGShE6oUA==",
       "requires": {
         "graphql": "16.0.0",
         "node-fetch": "^2.6.0",
+        "rusha": "^0.8.14",
         "uuid": "^8.3.2"
       },
       "dependencies": {
@@ -37945,6 +37952,11 @@
         "queue-microtask": "^1.2.2"
       }
     },
+    "rusha": {
+      "version": "0.8.14",
+      "resolved": "https://registry.npmjs.org/rusha/-/rusha-0.8.14.tgz",
+      "integrity": "sha512-cLgakCUf6PedEu15t8kbsjnwIFFR2D4RfL+W3iWFJ4iac7z4B0ZI8fxy4R3J956kAI68HclCFGL8MPoUVC3qVA=="
+    },
     "rxjs": {
       "version": "6.6.7",
       "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-6.6.7.tgz",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "netlify-cli",
   "description": "Netlify command line tool",
-  "version": "10.14.0",
+  "version": "10.15.0",
   "author": "Netlify Inc.",
   "contributors": [
     "Abraham Schilling <AbrahamSchilling@gmail.com> (https://gitlab.com/n4bb12)",
@@ -291,7 +291,7 @@
     "multiparty": "^4.2.1",
     "netlify": "^12.0.0",
     "netlify-headers-parser": "^6.0.2",
-    "netlify-onegraph-internal": "0.4.1",
+    "netlify-onegraph-internal": "0.4.2",
     "netlify-redirect-parser": "^13.0.5",
     "netlify-redirector": "^0.2.1",
     "node-fetch": "^2.6.0",

package/src/commands/graph/graph-edit.js

@@ -48,6 +48,7 @@ const graphEdit = async (options, command) => {
     netlifyToken,
     site,
     state,
+    netlifyGraphConfig,
   })
 
   const { branch } = gitRepoInfo()

package/src/commands/graph/graph-init.js

@@ -5,6 +5,7 @@ const { OneGraphClient } = require('netlify-onegraph-internal')
 const { v4: uuidv4 } = require('uuid')
 
 const { OneGraphCliClient, ensureCLISession } = require('../../lib/one-graph/cli-client')
+const { getNetlifyGraphConfig } = require('../../lib/one-graph/cli-netlify-graph')
 const { NETLIFYDEVERR, chalk, error, exit, getToken, log } = require('../../utils')
 const { msg } = require('../login/login')
 
@@ -63,11 +64,13 @@ const graphInit = async (options, command) => {
 
   await ensureAppForSite(netlifyToken, siteId)
 
+  const netlifyGraphConfig = await getNetlifyGraphConfig({ command, options })
   await ensureCLISession({
     metadata: {},
     netlifyToken,
     site,
     state,
+    netlifyGraphConfig,
   })
 
   let envChanged = false

package/src/commands/graph/graph-library.js

@@ -1,4 +1,5 @@
 // @ts-check
+const { readLockfile } = require('../../lib/one-graph/cli-client')
 const {
   buildSchema,
   defaultExampleOperationsDoc,
@@ -9,7 +10,7 @@ const {
   readGraphQLOperationsSourceFile,
   readGraphQLSchemaFile,
 } = require('../../lib/one-graph/cli-netlify-graph')
-const { error, log } = require('../../utils')
+const { NETLIFYDEVERR, chalk, error, log } = require('../../utils')
 
 /**
  * Creates the `netlify graph:library` command
@@ -42,10 +43,23 @@ const graphLibrary = async (options, command) => {
   const parsedDoc = parse(currentOperationsDoc)
   const { fragments, functions } = extractFunctionsFromOperationDoc(parsedDoc)
 
+  const lockfile = readLockfile({ siteRoot: command.netlify.site.root })
+
+  if (lockfile == null) {
+    error(
+      `${NETLIFYDEVERR} Error: no lockfile found, unable to run \`netlify graph:library\`. To pull a remote schema (and create a lockfile), run ${chalk.yellow(
+        'netlify graph:pull',
+      )} `,
+    )
+  }
+
+  const schemaId = lockfile && lockfile.locked.schemaId
+
   generateFunctionsFile({
     logger: log,
     netlifyGraphConfig,
     schema,
+    schemaId,
     operationsDoc: currentOperationsDoc,
     functions,
     fragments,

package/src/commands/graph/graph-pull.js

@@ -34,6 +34,13 @@ const graphPull = async (options, command) => {
   const { jwt } = await OneGraphCliClient.getGraphJwtForSite({ siteId, nfToken: netlifyToken })
 
   const oneGraphSessionId = loadCLISession(state)
+  if (!oneGraphSessionId) {
+    warn(
+      'No local Netlify Graph session found, skipping command queue drain. Create a new session by running `netlify graph:edit`.',
+    )
+    return
+  }
+
   await refetchAndGenerateFromOneGraph({
     logger: log,
     netlifyGraphConfig,
@@ -43,13 +50,6 @@ const graphPull = async (options, command) => {
     sessionId: oneGraphSessionId,
   })
 
-  if (!oneGraphSessionId) {
-    warn(
-      'No local Netlify Graph session found, skipping command queue drain. Create a new session by running `netlify graph:edit`.',
-    )
-    return
-  }
-
   const schemaString = readGraphQLSchemaFile(netlifyGraphConfig)
 
   let schema
@@ -106,7 +106,7 @@ const graphPull = async (options, command) => {
 const createGraphPullCommand = (program) =>
   program
     .command('graph:pull')
-    .description('Pull down your local Netlify Graph schema, and process pending Graph edit events')
+    .description('Pull your remote Netlify Graph schema locally, and process pending Graph edit events')
     .action(async (options, command) => {
       await graphPull(options, command)
     })

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

@@ -2,12 +2,13 @@
 /* eslint-disable eslint-comments/disable-enable-pair */
 /* eslint-disable fp/no-loops */
 const crypto = require('crypto')
+const { readFileSync, writeFileSync } = require('fs')
 const os = require('os')
 const path = require('path')
 
 const gitRepoInfo = require('git-repo-info')
 const { GraphQL, InternalConsole, OneGraphClient } = require('netlify-onegraph-internal')
-const { NetlifyGraph } = require('netlify-onegraph-internal')
+const { NetlifyGraph, NetlifyGraphLockfile } = require('netlify-onegraph-internal')
 
 // eslint-disable-next-line no-unused-vars
 const { StateConfig, USER_AGENT, chalk, error, execa, log, warn, watchDebounced } = require('../../utils')
@@ -273,6 +274,33 @@ const regenerateFunctionsFileFromOperationsFile = (input) => {
   generateFunctionsFile({ netlifyGraphConfig, schema, operationsDoc: appOperationsDoc, functions, fragments })
 }
 
+/**
+ * Lockfile Operations
+ */
+
+/**
+ * Persist the Netlify Graph lockfile on disk
+ * @param {object} input
+ * @param {string} input.siteRoot The GraphQL schema to use when generating code
+ * @param {NetlifyGraphLockfile.V0_format} input.lockfile
+ */
+const writeLockfile = ({ lockfile, siteRoot }) => {
+  writeFileSync(path.join(siteRoot, NetlifyGraphLockfile.defaultLockFileName), JSON.stringify(lockfile, null, 2))
+}
+
+/**
+ * Read the Netlify Graph lockfile from disk, if it exists
+ * @param {object} input
+ * @param {string} input.siteRoot The GraphQL schema to use when generating code
+ * @return {NetlifyGraphLockfile.V0_format | undefined}
+ */
+const readLockfile = ({ siteRoot }) => {
+  try {
+    const buf = readFileSync(path.join(siteRoot, NetlifyGraphLockfile.defaultLockFileName))
+    return JSON.parse(buf.toString('utf8'))
+  } catch {}
+}
+
 /**
  * Compute a md5 hash of a string
  * @param {string} input String to compute a quick md5 hash for
@@ -285,7 +313,8 @@ const quickHash = (input) => {
 }
 
 /**
- * Fetch a persisted operations doc by its id, write it to the system, and regenerate the library
+ * Fetch a persisted operations doc by its id, normalize it for Netlify Graph
+ * and return its contents as a string
  * @param {object} input
  * @param {string} input.siteId The site id to query against
  * @param {string} input.netlifyToken The (typically netlify) access token that is used for authentication, if any
@@ -293,11 +322,11 @@ const quickHash = (input) => {
  * @param {(message: string) => void=} input.logger A function that if provided will be used to log messages
  * @param {GraphQL.GraphQLSchema} input.schema The GraphQL schema to use when generating code
  * @param {NetlifyGraph.NetlifyGraphConfig} input.netlifyGraphConfig A standalone config object that contains all the information necessary for Netlify Graph to process events
- * @returns
+ * @returns {Promise<string | undefined>}
  */
-const updateGraphQLOperationsFileFromPersistedDoc = async (input) => {
+const fetchGraphQLOperationsLibraryFromPersistedDoc = async (input) => {
   try {
-    const { docId, logger, netlifyGraphConfig, netlifyToken, schema, siteId } = input
+    const { docId, netlifyToken, siteId } = input
     const { jwt } = await OneGraphClient.getGraphJwtForSite({ siteId, nfToken: netlifyToken })
     const persistedDoc = await OneGraphClient.fetchPersistedQuery(jwt, siteId, docId)
     if (!persistedDoc) {
@@ -308,21 +337,63 @@ const updateGraphQLOperationsFileFromPersistedDoc = async (input) => {
     // Sorts the operations stably, prepends the @netlify directive, etc.
     const operationsDocString = normalizeOperationsDoc(persistedDoc.query)
 
-    writeGraphQLOperationsSourceFile({ logger, netlifyGraphConfig, operationsDocString })
-    regenerateFunctionsFileFromOperationsFile({ netlifyGraphConfig, schema })
+    return operationsDocString
+  } catch {
+    warn(`Unable to reach Netlify Graph servers in order to update Graph operations file`)
+  }
+}
+
+/**
+ * Fetch a persisted operations doc by its id, write it to the system, and regenerate the library
+ * @param {object} input
+ * @param {string} input.operationsDocString The contents of the GraphQL operations document
+ * @param {(message: string) => void=} input.logger A function that if provided will be used to log messages
+ * @param {GraphQL.GraphQLSchema} input.schema The GraphQL schema to use when generating code
+ * @param {NetlifyGraph.NetlifyGraphConfig} input.netlifyGraphConfig A standalone config object that contains all the information necessary for Netlify Graph to process events
+ * @returns
+ */
+const updateGraphQLOperationsFileFromPersistedDoc = (input) => {
+  const { logger, netlifyGraphConfig, operationsDocString, schema } = input
 
-    const hash = quickHash(operationsDocString)
+  writeGraphQLOperationsSourceFile({ logger, netlifyGraphConfig, operationsDocString })
+  regenerateFunctionsFileFromOperationsFile({ netlifyGraphConfig, schema })
 
-    const relevantHasLength = 10
+  const hash = quickHash(operationsDocString)
 
-    if (witnessedIncomingDocumentHashes.length > relevantHasLength) {
-      witnessedIncomingDocumentHashes.shift()
-    }
+  const relevantHasLength = 10
 
-    witnessedIncomingDocumentHashes.push(hash)
-  } catch {
-    warn(`Unable to reach Netlify Graph servers in order to update Graph operations file`)
+  if (witnessedIncomingDocumentHashes.length > relevantHasLength) {
+    witnessedIncomingDocumentHashes.shift()
   }
+
+  witnessedIncomingDocumentHashes.push(hash)
+}
+
+/**
+ * Fetch a persisted operations doc by its id, write it to the system, and regenerate the library
+ * @param {object} input
+ * @param {string} input.siteId The site id to query against
+ * @param {string} input.schemaId The schema ID to query against
+ * @param {string} input.siteRoot Path to the root of the project
+ * @param {string} input.netlifyToken The (typically netlify) access token that is used for authentication, if any
+ * @param {string} input.docId The GraphQL operations document id to fetch
+ * @param {(message: string) => void=} input.logger A function that if provided will be used to log messages
+ * @param {GraphQL.GraphQLSchema} input.schema The GraphQL schema to use when generating code
+ * @param {NetlifyGraph.NetlifyGraphConfig} input.netlifyGraphConfig A standalone config object that contains all the information necessary for Netlify Graph to process events
+ * @returns {Promise<string | undefined>}
+ */
+const handleOperationsLibraryPersistedEvent = async (input) => {
+  const { schemaId, siteRoot } = input
+  const operationsFileContents = await fetchGraphQLOperationsLibraryFromPersistedDoc(input)
+
+  if (!operationsFileContents) {
+    // `fetch` already warned
+    return
+  }
+
+  const lockfile = NetlifyGraphLockfile.createLockfile({ operationsFileContents, schemaId })
+  writeLockfile({ siteRoot, lockfile })
+  updateGraphQLOperationsFileFromPersistedDoc({ ...input, operationsDocString: operationsFileContents })
 }
 
 const handleCliSessionEvent = async ({
@@ -412,12 +483,14 @@ const handleCliSessionEvent = async ({
       break
     }
     case 'OneGraphNetlifyCliSessionPersistedLibraryUpdatedEvent':
-      await updateGraphQLOperationsFileFromPersistedDoc({
+      await handleOperationsLibraryPersistedEvent({
         netlifyToken,
         docId: payload.docId,
+        schemaId: payload.schemaId,
         netlifyGraphConfig,
         schema,
         siteId,
+        siteRoot,
       })
       break
     default: {
@@ -538,6 +611,20 @@ const persistNewOperationsDocForSession = async ({
     return
   }
 
+  const lockfile = readLockfile({ siteRoot })
+
+  if (!lockfile) {
+    warn(
+      `can't find a lockfile for the project while running trying to persist operations for session. To pull a remote schema (and create a lockfile), run ${chalk.yellow(
+        'netlify graph:pull',
+      )} `,
+    )
+  }
+
+  // NOTE(anmonteiro): We still persist a new operations document because we
+  // might be checking out someone else's branch whose session we don't have
+  // access to.
+
   const { branch } = gitRepoInfo()
   const { jwt } = await OneGraphClient.getGraphJwtForSite({ siteId, nfToken: netlifyToken })
   const persistedResult = await OneGraphClient.executeCreatePersistedQueryMutation(
@@ -575,6 +662,15 @@ const persistNewOperationsDocForSession = async ({
 
   if (result.errors) {
     warn(`Unable to update session metadata with updated operations doc ${JSON.stringify(result.errors, null, 2)}`)
+  } else if (lockfile != null) {
+    // Now that we've persisted the document, lock it in the lockfile
+    const currentOperationsDoc = readGraphQLOperationsSourceFile(netlifyGraphConfig)
+
+    const newLockfile = NetlifyGraphLockfile.createLockfile({
+      schemaId: lockfile.locked.schemaId,
+      operationsFileContents: currentOperationsDoc,
+    })
+    writeLockfile({ siteRoot, lockfile: newLockfile })
   }
 }
 
@@ -611,6 +707,7 @@ const startOneGraphCLISession = async (input) => {
     site,
     state,
     oneGraphSessionId: input.oneGraphSessionId,
+    netlifyGraphConfig,
   })
 
   const enabledServices = []
@@ -718,29 +815,81 @@ const generateSessionName = () => {
   return sessionName
 }
 
+/**
+ * Mark a session as inactive so it doesn't show up in any UI lists, and potentially becomes available to GC later
+ * @param {object} input
+ * @param {{metadata: {schemaId:string}; id: string; appId: string; name?: string}} input.session The current session
+ * @param {string} input.netlifyToken The (typically netlify) access token that is used for authentication, if any
+ * @param {NetlifyGraphLockfile.V0_format | undefined} input.lockfile A function to call to set/get the current state of the local Netlify project
+ */
+const idempotentlyUpdateSessionSchemaIdFromLockfile = async (input) => {
+  const { lockfile, netlifyToken, session } = input
+  const sessionSchemaId = session.metadata && session.metadata.schemaId
+  const lockfileSchemaId = lockfile && lockfile.locked.schemaId
+
+  if (lockfileSchemaId != null && sessionSchemaId !== lockfileSchemaId) {
+    // Local schema always wins, update the session metadata to reflect that
+    const siteId = session.appId
+    const { jwt } = await OneGraphClient.getGraphJwtForSite({ siteId, nfToken: netlifyToken })
+
+    log(`Found new lockfile, overwriting session ${session.name || session.id}`)
+    return OneGraphClient.updateCLISessionMetadata(jwt, siteId, session.id, {
+      ...session.metadata,
+      schemaId: lockfileSchemaId,
+    })
+  }
+}
+
 /**
  * Ensures a cli session exists for the current checkout, or errors out if it doesn't and cannot create one.
+ * @param {object} input
+ * @param {NetlifyGraph.NetlifyGraphConfig} input.netlifyGraphConfig A standalone config object that contains all the information necessary for Netlify Graph to process events
+ * @param {object} input.metadata
+ * @param {string} input.netlifyToken
+ * @param {StateConfig} input.state
+ * @param {string} [input.oneGraphSessionId]
+ * @param {any} input.site The site object
  */
 const ensureCLISession = async (input) => {
-  const { metadata, netlifyToken, site, state } = input
+  const { metadata, netlifyGraphConfig, netlifyToken, site, state } = input
   let oneGraphSessionId = input.oneGraphSessionId ? input.oneGraphSessionId : loadCLISession(state)
   let parentCliSessionId = null
   const { jwt } = await OneGraphClient.getGraphJwtForSite({ siteId: site.id, nfToken: netlifyToken })
 
+  const lockfile = readLockfile({ siteRoot: site.root })
+
   // Validate that session still exists and we can access it
   try {
     if (oneGraphSessionId) {
-      const sessionEvents = await OneGraphClient.fetchCliSessionEvents({
+      const { errors, session } = await OneGraphClient.fetchCliSession({
         appId: site.id,
         jwt,
         sessionId: oneGraphSessionId,
+        desiredEventCount: 0,
       })
-      if (sessionEvents.errors) {
-        warn(`Unable to fetch cli session: ${JSON.stringify(sessionEvents.errors, null, 2)}`)
+      if (errors) {
+        warn(`Unable to fetch cli session: ${JSON.stringify(errors, null, 2)}`)
         log(`Creating new cli session`)
         parentCliSessionId = oneGraphSessionId
         oneGraphSessionId = null
       }
+
+      // During the transition to lockfiles, write a lockfile if one isn't
+      // found. Later, only handling a 'OneGraphNetlifyCliSessionPersistedLibraryUpdatedEvent'
+      // will create or update the lockfile
+      // TODO(anmonteiro): remove this in the future?
+      if (lockfile == null && session.metadata.schemaId) {
+        const currentOperationsDoc = readGraphQLOperationsSourceFile(netlifyGraphConfig)
+        log(`Generating Netlify Graph lockfile at ${NetlifyGraphLockfile.defaultLockFileName}`)
+
+        const newLockfile = NetlifyGraphLockfile.createLockfile({
+          schemaId: session.metadata.schemaId,
+          operationsFileContents: currentOperationsDoc,
+        })
+        writeLockfile({ siteRoot: site.root, lockfile: newLockfile })
+      }
+
+      await idempotentlyUpdateSessionSchemaIdFromLockfile({ session, lockfile, netlifyToken })
     }
   } catch (fetchSessionError) {
     warn(`Unable to fetch cli session events: ${JSON.stringify(fetchSessionError, null, 2)}`)
@@ -752,17 +901,25 @@ const ensureCLISession = async (input) => {
     const sessionName = generateSessionName()
     const detectedMetadata = detectLocalCLISessionMetadata({ siteRoot: site.root })
     const newSessionMetadata = parentCliSessionId ? { parentCliSessionId } : {}
+
     const sessionMetadata = {
       ...detectedMetadata,
       ...newSessionMetadata,
       ...metadata,
     }
+
+    if (lockfile != null) {
+      log(`Creating new session "${sessionName}" from lockfile`)
+      sessionMetadata.schemaId = lockfile.locked.schemaId
+    }
+
     const oneGraphSession = await createCLISession({
       netlifyToken,
       siteId: site.id,
       sessionName,
       metadata: sessionMetadata,
     })
+
     oneGraphSessionId = oneGraphSession.id
   }
 
@@ -808,4 +965,5 @@ module.exports = {
   refetchAndGenerateFromOneGraph,
   startOneGraphCLISession,
   upsertMergeCLISessionMetadata,
+  readLockfile,
 }