@tinacms/cli 0.0.0-f3aa146-20241112221138 → 0.0.0-f4d873b-20250312063427

package/dist/index.js

@@ -17,23 +17,28 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  default: () => src_default
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 var import_clipanion8 = require("clipanion");
 
 // package.json
-var version = "1.6.11";
+var version = "1.9.2";
 
 // src/next/commands/dev-command/index.ts
+var import_async_lock = __toESM(require("async-lock"));
 var import_clipanion2 = require("clipanion");
 var import_fs_extra6 = __toESM(require("fs-extra"));
 var import_path5 = __toESM(require("path"));
@@ -57,7 +62,10 @@ function isUnicodeSupported() {
   if (process.platform !== "win32") {
     return process.env.TERM !== "linux";
   }
-  return Boolean(process.env.CI) || Boolean(process.env.WT_SESSION) || Boolean(process.env.TERMINUS_SUBLIME) || process.env.ConEmuTask === "{cmd::Cmder}" || process.env.TERM_PROGRAM === "Terminus-Sublime" || process.env.TERM_PROGRAM === "vscode" || process.env.TERM === "xterm-256color" || process.env.TERM === "alacritty" || process.env.TERMINAL_EMULATOR === "JetBrains-JediTerm";
+  return Boolean(process.env.CI) || Boolean(process.env.WT_SESSION) || // Windows Terminal
+  Boolean(process.env.TERMINUS_SUBLIME) || // Terminus (<0.2.27)
+  process.env.ConEmuTask === "{cmd::Cmder}" || // ConEmu and cmder
+  process.env.TERM_PROGRAM === "Terminus-Sublime" || process.env.TERM_PROGRAM === "vscode" || process.env.TERM === "xterm-256color" || process.env.TERM === "alacritty" || process.env.TERMINAL_EMULATOR === "JetBrains-JediTerm";
 }
 
 // src/logger/index.ts
@@ -212,7 +220,7 @@ var ConfigManager = class {
     this.generatedCachePath = import_path.default.join(
       this.generatedFolderPath,
       ".cache",
-      String(new Date().getTime())
+      String((/* @__PURE__ */ new Date()).getTime())
     );
     this.generatedGraphQLGQLPath = import_path.default.join(
       this.generatedFolderPath,
@@ -355,17 +363,22 @@ var ConfigManager = class {
     );
   }
   getTinaGraphQLVersion() {
-    var _a, _b;
     if (this.tinaGraphQLVersionFromCLI) {
-      return this.tinaGraphQLVersionFromCLI;
+      const version2 = this.tinaGraphQLVersionFromCLI.split(".");
+      return {
+        fullVersion: this.tinaGraphQLVersionFromCLI,
+        major: version2[0] || "x",
+        minor: version2[1] || "x",
+        patch: version2[2] || "x"
+      };
     }
     const generatedSchema = import_fs_extra.default.readJSONSync(this.generatedSchemaJSONPath);
-    if (!generatedSchema || !(typeof (generatedSchema == null ? void 0 : generatedSchema.version) !== "undefined") || !(typeof ((_a = generatedSchema == null ? void 0 : generatedSchema.version) == null ? void 0 : _a.major) === "string") || !(typeof ((_b = generatedSchema == null ? void 0 : generatedSchema.version) == null ? void 0 : _b.minor) === "string")) {
+    if (!generatedSchema || !(typeof (generatedSchema == null ? void 0 : generatedSchema.version) !== "undefined")) {
       throw new Error(
         `Can not find Tina GraphQL version in ${this.generatedSchemaJSONPath}`
       );
     }
-    return `${generatedSchema.version.major}.${generatedSchema.version.minor}`;
+    return generatedSchema.version;
   }
   printGeneratedClientFilePath() {
     if (this.isUsingTs()) {
@@ -394,6 +407,9 @@ var ConfigManager = class {
     }
     throw `No path provided to print`;
   }
+  /**
+   * Given a filepath without an extension, find the first match (eg. tsx, ts, jsx, js)
+   */
   async getPathWithExtension(filepath) {
     const extensions = ["tsx", "ts", "jsx", "js"];
     let result;
@@ -427,7 +443,10 @@ var ConfigManager = class {
   }
   async loadConfigFile(generatedFolderPath, configFilePath) {
     const tmpdir = import_path.default.join(import_os.default.tmpdir(), Date.now().toString());
-    const prebuild = import_path.default.join(this.generatedFolderPath, "config.prebuild.jsx");
+    const preBuildConfigPath = import_path.default.join(
+      this.generatedFolderPath,
+      "config.prebuild.jsx"
+    );
     const outfile = import_path.default.join(tmpdir, "config.build.jsx");
     const outfile2 = import_path.default.join(tmpdir, "config.build.js");
     const tempTSConfigFile = import_path.default.join(tmpdir, "tsconfig.json");
@@ -441,7 +460,7 @@ var ConfigManager = class {
       logLevel: "silent",
       packages: "external",
       ignoreAnnotations: true,
-      outfile: prebuild,
+      outfile: preBuildConfigPath,
       loader: loaders,
       metafile: true
     });
@@ -464,6 +483,7 @@ var ConfigManager = class {
     await esbuild.build({
       entryPoints: [outfile],
       bundle: true,
+      // Suppress warning about comparison with -0 from client module
       logLevel: "silent",
       platform: "node",
       outfile: outfile2,
@@ -481,7 +501,7 @@ var ConfigManager = class {
     import_fs_extra.default.removeSync(outfile2);
     return {
       config: result.default,
-      prebuildPath: prebuild,
+      prebuildPath: preBuildConfigPath,
       watchList: flattenedList
     };
   }
@@ -570,19 +590,19 @@ var devHTML = (port) => `<!DOCTYPE html>
     window.$RefreshReg$ = () => {}
     window.$RefreshSig$ = () => (type) => type
     window.__vite_plugin_react_preamble_installed__ = true
-  <\/script>
-  <script type="module" src="http://localhost:${port}/@vite/client"><\/script>
+  </script>
+  <script type="module" src="http://localhost:${port}/@vite/client"></script>
   <script>
   function handleLoadError() {
     // Assets have failed to load
     document.getElementById('root').innerHTML = '${errorHTML}';
   }
-  <\/script>
+  </script>
   <script
     type="module"
     src="http://localhost:${port}/src/main.tsx"
     onerror="handleLoadError()"
-  ><\/script>
+  ></script>
   <body class="tina-tailwind">
     <div id="root"></div>
   </body>
@@ -628,6 +648,7 @@ var import_defaultTheme = __toESM(require("tailwindcss/defaultTheme.js"));
 var tinaTailwind = (spaPath, prebuildFilePath) => {
   return {
     name: "vite-plugin-tina",
+    // @ts-ignore
     config: (viteConfig) => {
       const plugins = [];
       const content = [
@@ -939,7 +960,6 @@ async function listFilesRecursively({
 }
 var createConfig = async ({
   configManager,
-  database,
   apiURL,
   plugins = [],
   noWatch,
@@ -999,6 +1019,8 @@ var createConfig = async ({
   if (configManager.config.build.basePath) {
     basePath = configManager.config.build.basePath;
   }
+  const fullVersion = configManager.getTinaGraphQLVersion();
+  const version2 = `${fullVersion.major}.${fullVersion.minor}`;
   const config2 = {
     root: configManager.spaRootPath,
     base: `/${basePath ? `${(0, import_normalize_path2.default)(basePath)}/` : ""}${(0, import_normalize_path2.default)(
@@ -1010,15 +1032,33 @@ var createConfig = async ({
       dedupe: ["graphql", "tinacms", "react", "react-dom", "react-router-dom"]
     },
     define: {
+      /**
+       * Since we prebuild the config.ts, it's possible for modules to be loaded which make
+       * use of `process`. The main scenario where this is an issue is when co-locating schema
+       * definitions with source files, and specifically source files which impor from NextJS.
+       *
+       * Some examples of what NextJS uses for `process.env` are:
+       *  - `process.env.__NEXT_TRAILING_SLASH`
+       *  - `process.env.__NEXT_CROSS_ORIGIN`
+       *  - `process.env.__NEXT_I18N_SUPPORT`
+       *
+       * Also, interestingly some of the advice for handling this doesn't work, references to replacing
+       * `process.env` with `{}` are problematic, because browsers don't understand the `{}.` syntax,
+       * but node does. This was a surprise, but using `new Object()` seems to do the trick.
+       */
       "process.env": `new Object(${JSON.stringify(publicEnv)})`,
+      // Used by picomatch https://github.com/micromatch/picomatch/blob/master/lib/utils.js#L4
       "process.platform": `"${process.platform}"`,
       __API_URL__: `"${apiURL}"`,
       __BASE_PATH__: `"${((_e = (_d = configManager.config) == null ? void 0 : _d.build) == null ? void 0 : _e.basePath) || ""}"`,
-      __TINA_GRAPHQL_VERSION__: `"${configManager.getTinaGraphQLVersion()}"`
+      __TINA_GRAPHQL_VERSION__: version2
     },
     logLevel: "error",
+    // Vite import warnings are noisy
     optimizeDeps: {
       force: true,
+      // Not 100% sure why this isn't being picked up automatically, this works from within the monorepo
+      // but breaks externally
       include: ["react/jsx-runtime", "react/jsx-dev-runtime"]
     },
     server: {
@@ -1026,6 +1066,7 @@ var createConfig = async ({
       watch: noWatch ? {
         ignored: ["**/*"]
       } : {
+        // Ignore everything except for the alias fields we specified above
         ignored: [
           `${configManager.tinaFolderPath}/**/!(config.prebuild.jsx|_graphql.json)`
         ]
@@ -1041,8 +1082,13 @@ var createConfig = async ({
       rollupOptions
     },
     plugins: [
+      /**
+       * `splitVendorChunkPlugin` is needed because `tinacms` is quite large,
+       * Vite's chunking strategy chokes on memory issues for smaller machines (ie. on CI).
+       */
       (0, import_plugin_react.default)({
         babel: {
+          // Supresses the warning [NOTE] babel The code generator has deoptimised the styling of
           compact: true
         }
       }),
@@ -1119,8 +1165,7 @@ var createMediaRouter = (config2) => {
 };
 var parseMediaFolder = (str) => {
   let returnString = str;
-  if (returnString.startsWith("/"))
-    returnString = returnString.substr(1);
+  if (returnString.startsWith("/")) returnString = returnString.substr(1);
   if (returnString.endsWith("/"))
     returnString = returnString.substr(0, returnString.length - 1);
   return returnString;
@@ -1137,7 +1182,7 @@ var MediaModel = class {
         this.rootPath,
         this.publicFolder,
         this.mediaRoot,
-        args.searchPath
+        decodeURIComponent(args.searchPath)
       );
       const searchPath = parseMediaFolder(args.searchPath);
       if (!await import_fs_extra3.default.pathExists(folderPath)) {
@@ -1209,7 +1254,7 @@ var MediaModel = class {
         this.rootPath,
         this.publicFolder,
         this.mediaRoot,
-        args.searchPath
+        decodeURIComponent(args.searchPath)
       );
       await import_fs_extra3.default.stat(file);
       await import_fs_extra3.default.remove(file);
@@ -1285,7 +1330,8 @@ var devServerEndPointsPlugin = ({
   configManager,
   apiURL,
   database,
-  searchIndex
+  searchIndex,
+  databaseLock
 }) => {
   const plug = {
     name: "graphql-endpoints",
@@ -1329,14 +1375,17 @@ var devServerEndPointsPlugin = ({
         }
         if (req.url === "/graphql") {
           const { query, variables } = req.body;
-          const result = await (0, import_graphql.resolve)({
-            config: {
-              useRelativeMedia: true
-            },
-            database,
-            query,
-            variables,
-            verbose: false
+          let result;
+          await databaseLock(async () => {
+            result = await (0, import_graphql.resolve)({
+              config: {
+                useRelativeMedia: true
+              },
+              database,
+              query,
+              variables,
+              verbose: false
+            });
           });
           res.end(JSON.stringify(result));
           return;
@@ -1387,6 +1436,7 @@ function viteTransformExtension({
         return {
           code: res.code,
           map: null
+          // TODO:
         };
       }
     }
@@ -1394,10 +1444,16 @@ function viteTransformExtension({
 }
 
 // src/next/commands/dev-command/server/index.ts
-var createDevServer = async (configManager, database, searchIndex, apiURL, noWatch) => {
+var createDevServer = async (configManager, database, searchIndex, apiURL, noWatch, databaseLock) => {
   const plugins = [
     transformTsxPlugin({ configManager }),
-    devServerEndPointsPlugin({ apiURL, configManager, database, searchIndex }),
+    devServerEndPointsPlugin({
+      apiURL,
+      configManager,
+      database,
+      searchIndex,
+      databaseLock
+    }),
     viteTransformExtension()
   ];
   return (0, import_vite3.createServer)(
@@ -1407,6 +1463,14 @@ var createDevServer = async (configManager, database, searchIndex, apiURL, noWat
       apiURL,
       plugins,
       noWatch,
+      /**
+       * Ensure Vite's import scan uses the spaMainPath as the input
+       * so it properly finds everything. This is for dev only, and when
+       * running the server outside of this monorepo vite fails to find
+       * and optimize the imports, so you get errors about it not being
+       * able to find an export from a module, and it's always a CJS
+       * module that Vite would usually transform to an ES module.
+       */
       rollupOptions: {
         input: configManager.spaMainPath,
         onwarn(warning, warn) {
@@ -1532,6 +1596,7 @@ var GenericSdkVisitor = class extends import_visitor_plugin_common.ClientSideBas
         node,
         documentVariableName,
         operationType,
+        // This is the only line that is different
         operationResultType: `{data: ${operationResultType}, errors?: { message: string, locations: { line: number, column: number }[], path: string[] }[], variables: ${operationVariablesTypes}, query: string}`,
         operationVariablesTypes
       });
@@ -1580,6 +1645,8 @@ var plugin = (schema, documents, config2) => {
   const visitor = new GenericSdkVisitor(schema, allFragments, config2);
   const visitorResult = (0, import_graphql3.visit)(allAst, { leave: visitor });
   return {
+    // We will take care of imports
+    // prepend: visitor.getImports(),
     content: [
       visitor.fragments,
       ...visitorResult.definitions.filter((t) => typeof t === "string"),
@@ -1595,6 +1662,7 @@ var generateTypes = async (schema, queryPathGlob = process.cwd(), fragDocPath =
   docs = await loadGraphQLDocuments(queryPathGlob);
   fragDocs = await loadGraphQLDocuments(fragDocPath);
   const res = await (0, import_core.codegen)({
+    // Filename is not used. This is because the typescript plugin returns a string instead of writing to a file.
     filename: process.cwd(),
     schema: (0, import_graphql5.parse)((0, import_graphql5.printSchema)(schema)),
     documents: [...docs, ...fragDocs],
@@ -1629,9 +1697,12 @@ var loadGraphQLDocuments = async (globPath) => {
       loaders: [new import_graphql_file_loader.GraphQLFileLoader()]
     });
   } catch (e) {
-    if ((e.message || "").includes(
-      "Unable to find any GraphQL type definitions for the following pointers:"
-    )) {
+    if (
+      // https://www.graphql-tools.com/docs/documents-loading#no-files-found
+      (e.message || "").includes(
+        "Unable to find any GraphQL type definitions for the following pointers:"
+      )
+    ) {
     } else {
       throw e;
     }
@@ -1668,7 +1739,10 @@ var Codegen = class {
     this.noClientBuildCache = noClientBuildCache;
   }
   async writeConfigFile(fileName, data) {
-    const filePath = import_path4.default.join(this.configManager.generatedFolderPath, fileName);
+    const filePath = import_path4.default.join(
+      this.configManager.generatedFolderPath,
+      fileName
+    );
     await import_fs_extra4.default.ensureFile(filePath);
     await import_fs_extra4.default.outputFile(filePath, data);
     if (this.configManager.hasSeparateContentRoot()) {
@@ -1788,16 +1862,14 @@ var Codegen = class {
     const branch = (_a = this.configManager.config) == null ? void 0 : _a.branch;
     const clientId = (_b = this.configManager.config) == null ? void 0 : _b.clientId;
     const token = (_c = this.configManager.config) == null ? void 0 : _c.token;
-    const version2 = this.configManager.getTinaGraphQLVersion();
+    const fullVersion = this.configManager.getTinaGraphQLVersion();
+    const version2 = `${fullVersion.major}.${fullVersion.minor}`;
     const baseUrl = ((_d = this.configManager.config.tinaioConfig) == null ? void 0 : _d.contentApiUrlOverride) || `https://${TINA_HOST}`;
     if ((!branch || !clientId || !token) && !this.port && !this.configManager.config.contentApiUrlOverride) {
       const missing = [];
-      if (!branch)
-        missing.push("branch");
-      if (!clientId)
-        missing.push("clientId");
-      if (!token)
-        missing.push("token");
+      if (!branch) missing.push("branch");
+      if (!clientId) missing.push("clientId");
+      if (!token) missing.push("token");
       throw new Error(
         `Client not configured properly. Missing ${missing.join(
           ", "
@@ -1951,7 +2023,11 @@ schema {
   }
 };
 var maybeWarnFragmentSize = async (filepath) => {
-  if ((await import_fs_extra4.default.stat(filepath)).size > 100 * 1024) {
+  if (
+    // is the file bigger than 100kb?
+    (await import_fs_extra4.default.stat(filepath)).size > // convert to 100 kb to bytes
+    100 * 1024
+  ) {
     console.warn(
       "Warning: frags.gql is very large (>100kb). Consider setting the reference depth to 1 or 0. See code snippet below."
     );
@@ -1979,6 +2055,7 @@ var import_many_level = require("many-level");
 var import_memory_level = require("memory-level");
 var createDBServer = (port) => {
   const levelHost = new import_many_level.ManyLevelHost(
+    // @ts-ignore
     new import_memory_level.MemoryLevel({
       valueEncoding: "json"
     })
@@ -2129,7 +2206,9 @@ var BaseCommand = class extends import_clipanion.Command {
     let subProc;
     if (this.subCommand) {
       subProc = await startSubprocess2({ command: this.subCommand });
-      logger.info(`Starting subprocess: ${import_chalk4.default.cyan(this.subCommand)}`);
+      logger.info(
+        `Running web application with command: ${import_chalk4.default.cyan(this.subCommand)}`
+      );
     }
     function exitHandler(options, exitCode) {
       if (subProc) {
@@ -2253,6 +2332,7 @@ var import_search = require("@tinacms/search");
 var DevCommand = class extends BaseCommand {
   constructor() {
     super(...arguments);
+    // NOTE: camelCase commands for string options don't work if there's an `=` used https://github.com/arcanis/clipanion/issues/141
     this.watchFolders = import_clipanion2.Option.String("-w,--watchFolders", {
       description: "DEPRECATED - a list of folders (relative to where this is being run) that the cli will watch for changes"
     });
@@ -2262,6 +2342,10 @@ var DevCommand = class extends BaseCommand {
     this.outputSearchIndexPath = import_clipanion2.Option.String("--outputSearchIndexPath", {
       description: "Path to write the search index to"
     });
+    this.noServer = import_clipanion2.Option.Boolean("--no-server", false, {
+      description: "Do not start the dev server"
+    });
+    this.indexingLock = new import_async_lock.default();
   }
   async catch(error) {
     logger.error("Error occured during tinacms dev");
@@ -2282,10 +2366,13 @@ var DevCommand = class extends BaseCommand {
       rootPath: this.rootPath,
       legacyNoSDK: this.noSDK
     });
-    logger.info("Starting Tina Dev Server");
+    logger.info("\u{1F999} TinaCMS Dev Server is initializing...");
     this.logDeprecationWarnings();
     createDBServer(Number(this.datalayerPort));
     let database = null;
+    const dbLock = async (fn) => {
+      return this.indexingLock.acquire("Key", fn);
+    };
     const setup = async ({ firstTime }) => {
       try {
         await configManager.processConfig();
@@ -2336,9 +2423,6 @@ var DevCommand = class extends BaseCommand {
             await import_fs_extra6.default.outputFile(filePath, tinaLockContent);
           }
         }
-        if (!this.noWatch) {
-          this.watchQueries(configManager, async () => await codegen2.execute());
-        }
         await this.indexContentWithSpinner({
           database,
           graphQLSchema: graphQLSchema2,
@@ -2348,6 +2432,13 @@ var DevCommand = class extends BaseCommand {
         if (!firstTime) {
           logger.error("Re-index complete");
         }
+        if (!this.noWatch) {
+          this.watchQueries(
+            configManager,
+            dbLock,
+            async () => await codegen2.execute()
+          );
+        }
         return { apiURL: apiURL2, database, graphQLSchema: graphQLSchema2, tinaSchema: tinaSchema2 };
       } catch (e) {
         logger.error(`
@@ -2382,14 +2473,6 @@ ${dangerText(e.message)}
       tokenSplitRegex: (_d = (_c = configManager.config.search) == null ? void 0 : _c.tina) == null ? void 0 : _d.tokenSplitRegex
     });
     await searchIndexClient.onStartIndexing();
-    const server = await createDevServer(
-      configManager,
-      database,
-      searchIndexClient.searchIndex,
-      apiURL,
-      this.noWatch
-    );
-    await server.listen(Number(this.port));
     const searchIndexer = new import_search.SearchIndexer({
       batchSize: ((_e = configManager.config.search) == null ? void 0 : _e.indexBatchSize) || 100,
       bridge: new import_graphql10.FilesystemBridge(
@@ -2411,16 +2494,34 @@ ${dangerText(e.message)}
         await searchIndexClient.export(this.outputSearchIndexPath);
       }
     }
+    if (this.noServer) {
+      logger.info("--no-server option specified - Dev server not started");
+      process.exit(0);
+    }
     if (!this.noWatch) {
       this.watchContentFiles(
         configManager,
         database,
+        dbLock,
         configManager.config.search && searchIndexer
       );
+    }
+    const server = await createDevServer(
+      configManager,
+      database,
+      searchIndexClient.searchIndex,
+      apiURL,
+      this.noWatch,
+      dbLock
+    );
+    await server.listen(Number(this.port));
+    if (!this.noWatch) {
       import_chokidar.default.watch(configManager.watchList).on("change", async () => {
-        logger.info(`Tina config change detected, rebuilding`);
-        await setup({ firstTime: false });
-        server.ws.send({ type: "full-reload", path: "*" });
+        await dbLock(async () => {
+          logger.info(`Tina config change detected, rebuilding`);
+          await setup({ firstTime: false });
+          server.ws.send({ type: "full-reload", path: "*" });
+        });
       });
     }
     const subItems = [];
@@ -2433,7 +2534,7 @@ ${dangerText(e.message)}
     const summaryItems = [
       {
         emoji: "\u{1F999}",
-        heading: "Tina Config",
+        heading: "TinaCMS URLs",
         subItems: [
           {
             key: "CMS",
@@ -2468,14 +2569,28 @@ ${dangerText(e.message)}
       });
     }
     summary({
-      heading: "Tina Dev Server is running...",
+      heading: "\u2705 \u{1F999} TinaCMS Dev Server is active:",
       items: [
         ...summaryItems
+        // {
+        //   emoji: '📚',
+        //   heading: 'Useful links',
+        //   subItems: [
+        //     {
+        //       key: 'Custom queries',
+        //       value: 'https://tina.io/querying',
+        //     },
+        //     {
+        //       key: 'Visual editing',
+        //       value: 'https://tina.io/visual-editing',
+        //     },
+        //   ],
+        // },
       ]
     });
     await this.startSubCommand();
   }
-  watchContentFiles(configManager, database, searchIndexer) {
+  watchContentFiles(configManager, database, databaseLock, searchIndexer) {
     const collectionContentFiles = [];
     configManager.config.schema.collections.forEach((collection) => {
       const collectionGlob = `${import_path5.default.join(
@@ -2491,39 +2606,42 @@ ${dangerText(e.message)}
       if (!ready) {
         return;
       }
-      const pathFromRoot = configManager.printContentRelativePath(addedFile);
-      await database.indexContentByPaths([pathFromRoot]).catch(console.error);
-      if (searchIndexer) {
-        await searchIndexer.indexContentByPaths([pathFromRoot]).catch(console.error);
-      }
+      await databaseLock(async () => {
+        const pathFromRoot = configManager.printContentRelativePath(addedFile);
+        await database.indexContentByPaths([pathFromRoot]).catch(console.error);
+        if (searchIndexer) {
+          await searchIndexer.indexContentByPaths([pathFromRoot]).catch(console.error);
+        }
+      });
     }).on("change", async (changedFile) => {
       const pathFromRoot = configManager.printContentRelativePath(changedFile);
-      await database.indexContentByPaths([pathFromRoot]).catch(console.error);
-      if (searchIndexer) {
-        await searchIndexer.indexContentByPaths([pathFromRoot]).catch(console.error);
-      }
+      await databaseLock(async () => {
+        await database.indexContentByPaths([pathFromRoot]).catch(console.error);
+        if (searchIndexer) {
+          await searchIndexer.indexContentByPaths([pathFromRoot]).catch(console.error);
+        }
+      });
     }).on("unlink", async (removedFile) => {
       const pathFromRoot = configManager.printContentRelativePath(removedFile);
-      await database.deleteContentByPaths([pathFromRoot]).catch(console.error);
-      if (searchIndexer) {
-        await searchIndexer.deleteIndexContent([pathFromRoot]).catch(console.error);
-      }
+      await databaseLock(async () => {
+        await database.deleteContentByPaths([pathFromRoot]).catch(console.error);
+        if (searchIndexer) {
+          await searchIndexer.deleteIndexContent([pathFromRoot]).catch(console.error);
+        }
+      });
     });
   }
-  watchQueries(configManager, callback) {
-    let ready = false;
-    import_chokidar.default.watch(configManager.userQueriesAndFragmentsGlob).on("ready", () => {
-      ready = true;
-    }).on("add", async (addedFile) => {
-      await callback();
-    }).on("change", async (changedFile) => {
-      await callback();
-    }).on("unlink", async (removedFile) => {
-      await callback();
-    });
+  watchQueries(configManager, databaseLock, callback) {
+    const executeCallback = async (_) => {
+      await databaseLock(async () => {
+        await callback();
+      });
+    };
+    import_chokidar.default.watch(configManager.userQueriesAndFragmentsGlob).on("add", executeCallback).on("change", executeCallback).on("unlink", executeCallback);
   }
 };
 DevCommand.paths = [["dev"], ["server:start"]];
+// Prevent indexes and reads occurring at once
 DevCommand.usage = import_clipanion2.Command.Usage({
   category: `Commands`,
   description: `Builds Tina and starts the dev server`,
@@ -2582,7 +2700,7 @@ var buildProductionSpa = async (configManager, database, apiURL) => {
 // src/next/commands/build-command/index.ts
 var import_schema_tools2 = require("@tinacms/schema-tools");
 var import_graphql12 = require("graphql");
-var import_core2 = require("@graphql-inspector/core");
+var import_core3 = require("@graphql-inspector/core");
 
 // src/next/commands/build-command/waitForDB.ts
 var import_progress = __toESM(require("progress"));
@@ -2684,6 +2802,20 @@ var waitForDB = async (config2, apiUrl, previewName, verbose) => {
 
 // src/next/commands/build-command/index.ts
 var import_search2 = require("@tinacms/search");
+
+// src/utils/index.ts
+var import_core2 = require("@graphql-inspector/core");
+var getFaqLink = (type) => {
+  switch (type) {
+    case import_core2.ChangeType.FieldRemoved: {
+      return "https://tina.io/docs/introduction/faq#how-do-i-resolve-the-local-graphql-schema-doesnt-match-the-remote-graphql-schema-errors";
+    }
+    default:
+      return null;
+  }
+};
+
+// src/next/commands/build-command/index.ts
 var BuildCommand = class extends BaseCommand {
   constructor() {
     super(...arguments);
@@ -2699,6 +2831,9 @@ var BuildCommand = class extends BaseCommand {
     this.tinaGraphQLVersion = import_clipanion3.Option.String("--tina-graphql-version", {
       description: "Specify the version of @tinacms/graphql to use (defaults to latest)"
     });
+    /**
+     * This option allows the user to skip the tina cloud checks if they want to. This could be useful for mismatched GraphQL versions or if they want to build only using the local client and never connect to Tina Cloud
+     */
     this.skipCloudChecks = import_clipanion3.Option.Boolean("--skip-cloud-checks", false, {
       description: "Skips checking the provided cloud config."
     });
@@ -2804,14 +2939,15 @@ ${dangerText(e.message)}
         database,
         null,
         apiURL,
-        true
+        true,
+        (lockedFn) => lockedFn()
       );
       await server.listen(Number(this.port));
       console.log("server listening on port", this.port);
     }
     const skipCloudChecks = this.skipCloudChecks || configManager.hasSelfHostedConfig();
     if (!skipCloudChecks) {
-      const { hasUpstream } = await this.checkClientInfo(
+      const { hasUpstream, timestamp } = await this.checkClientInfo(
         configManager,
         codegen2.productionUrl,
         this.previewBaseBranch
@@ -2839,14 +2975,16 @@ ${dangerText(e.message)}
       await this.checkGraphqlSchema(
         configManager,
         database,
-        codegen2.productionUrl
+        codegen2.productionUrl,
+        timestamp
       );
       await this.checkTinaSchema(
         configManager,
         database,
         codegen2.productionUrl,
         this.previewName,
-        this.verbose
+        this.verbose,
+        timestamp
       );
     }
     await buildProductionSpa(configManager, database, codegen2.productionUrl);
@@ -2864,7 +3002,9 @@ ${dangerText(e.message)}
               `ERROR: Branch not configured in tina search configuration.`
             )}`
           );
-          throw new Error("Branch not configured in tina search configuration.");
+          throw new Error(
+            "Branch not configured in tina search configuration."
+          );
         }
         if (!((_d = configManager.config) == null ? void 0 : _d.clientId)) {
           logger.error(`${dangerText(`ERROR: clientId not configured.`)}`);
@@ -2965,11 +3105,13 @@ ${dangerText(e.message)}
     const bar2 = new import_progress2.default("Checking clientId and token. :prog", 1);
     let branchKnown = false;
     let hasUpstream = false;
+    let timestamp;
     try {
       const res = await request({
         token,
         url
       });
+      timestamp = res.timestamp || 0;
       bar2.tick({
         prog: "\u2705"
       });
@@ -3005,13 +3147,17 @@ ${dangerText(e.message)}
       });
       throw e;
     }
-    const branchBar = new import_progress2.default("Checking branch is on Tina Cloud. :prog", 1);
+    const branchBar = new import_progress2.default(
+      "Checking branch is on Tina Cloud. :prog",
+      1
+    );
     if (branchKnown) {
       branchBar.tick({
         prog: "\u2705"
       });
       return {
-        hasUpstream
+        hasUpstream,
+        timestamp
       };
     }
     for (let i = 0; i <= 5; i++) {
@@ -3101,14 +3247,14 @@ ${dangerText(e.message)}
       throw e;
     }
   }
-  async checkGraphqlSchema(configManager, database, apiURL) {
+  async checkGraphqlSchema(configManager, database, apiURL, timestamp) {
     const bar2 = new import_progress2.default(
       "Checking local GraphQL Schema matches server. :prog",
       1
     );
     const { config: config2 } = configManager;
     const token = config2.token;
-    const remoteSchema = await fetchRemoteGraphqlSchema({
+    const { remoteSchema, remoteProjectVersion } = await fetchRemoteGraphqlSchema({
       url: apiURL,
       token
     });
@@ -3128,7 +3274,7 @@ Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
     const localSchemaDocument = await database.getGraphQLSchemaFromBridge();
     const localGraphqlSchema = (0, import_graphql12.buildASTSchema)(localSchemaDocument);
     try {
-      const diffResult = await (0, import_core2.diff)(localGraphqlSchema, remoteGqlSchema);
+      const diffResult = await (0, import_core3.diff)(localGraphqlSchema, remoteGqlSchema);
       if (diffResult.length === 0) {
         bar2.tick({
           prog: "\u2705"
@@ -3137,12 +3283,30 @@ Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
         bar2.tick({
           prog: "\u274C"
         });
-        let errorMessage = `The local GraphQL schema doesn't match the remote GraphQL schema. Please push up your changes to GitHub to update your remote GraphQL schema.`;
-        if (config2 == null ? void 0 : config2.branch) {
-          errorMessage += `
+        const type = diffResult[0].type;
+        const reason = diffResult[0].message;
+        const errorLevel = diffResult[0].criticality.level;
+        const faqLink = getFaqLink(type);
+        const tinaGraphQLVersion = configManager.getTinaGraphQLVersion();
+        let errorMessage = `The local GraphQL schema doesn't match the remote GraphQL schema. Please push up your changes to GitHub to update your remote GraphQL schema. ${faqLink && `
+Check out '${faqLink}' for possible solutions.`}`;
+        errorMessage += `
 
-Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
+Additional info:
+
+`;
+        if (config2 == null ? void 0 : config2.branch) {
+          errorMessage += `	Branch: ${config2.branch}, Client ID: ${config2.clientId}
+`;
         }
+        errorMessage += `	Local GraphQL version: ${tinaGraphQLVersion.fullVersion} / Remote GraphQL version: ${remoteProjectVersion}
+`;
+        errorMessage += `	Last indexed at: ${new Date(
+          timestamp
+        ).toUTCString()}
+`;
+        errorMessage += `	Reason: [${errorLevel} - ${type}] ${reason}
+`;
         throw new Error(errorMessage);
       }
     } catch (e) {
@@ -3157,7 +3321,7 @@ Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
       }
     }
   }
-  async checkTinaSchema(configManager, database, apiURL, previewName, verbose) {
+  async checkTinaSchema(configManager, database, apiURL, previewName, verbose, timestamp) {
     const bar2 = new import_progress2.default(
       "Checking local Tina Schema matches server. :prog",
       1
@@ -3167,7 +3331,9 @@ Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
     const { clientId, branch, isLocalClient, host } = (0, import_schema_tools2.parseURL)(apiURL);
     if (isLocalClient || !host || !clientId || !branch) {
       if (verbose) {
-        logger.info(logText("Not using Tina Cloud, skipping Tina Schema check"));
+        logger.info(
+          logText("Not using Tina Cloud, skipping Tina Schema check")
+        );
       }
       return;
     }
@@ -3206,11 +3372,19 @@ Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
         prog: "\u274C"
       });
       let errorMessage = `The local Tina schema doesn't match the remote Tina schema. Please push up your changes to GitHub to update your remote tina schema.`;
-      if (config2 == null ? void 0 : config2.branch) {
-        errorMessage += `
+      errorMessage += `
 
-Additional info: Branch: ${config2.branch}, Client ID: ${config2.clientId} `;
+Additional info:
+
+`;
+      if (config2 == null ? void 0 : config2.branch) {
+        errorMessage += `        Branch: ${config2.branch}, Client ID: ${config2.clientId}
+`;
       }
+      errorMessage += `        Last indexed at: ${new Date(
+        timestamp
+      ).toUTCString()}
+`;
       throw new Error(errorMessage);
     }
   }
@@ -3280,7 +3454,11 @@ var fetchRemoteGraphqlSchema = async ({
     body
   });
   const data = await res.json();
-  return data == null ? void 0 : data.data;
+  return {
+    remoteSchema: data == null ? void 0 : data.data,
+    remoteRuntimeVersion: res.headers.get("tinacms-grapqhl-version"),
+    remoteProjectVersion: res.headers.get("tinacms-graphql-project-version")
+  };
 };
 var fetchSchemaSha = async ({
   url,
@@ -3404,6 +3582,7 @@ var auditDocuments = async (args) => {
         logger.error(import_chalk5.default.red(err.message));
         if (err.originalError.originalError) {
           logger.error(
+            // @ts-ignore FIXME: this doesn't seem right
             import_chalk5.default.red(`    ${err.originalError.originalError.message}`)
           );
         }
@@ -3609,7 +3788,9 @@ var detectEnvironment = async ({
   const usingSrc = import_fs_extra8.default.pathExistsSync(import_path7.default.join(baseDir, "src")) && (import_fs_extra8.default.pathExistsSync(import_path7.default.join(baseDir, "src", "app")) || import_fs_extra8.default.pathExistsSync(import_path7.default.join(baseDir, "src", "pages")));
   const tinaFolder = import_path7.default.join(baseDir, "tina");
   const tinaConfigExists = Boolean(
-    await import_fs_extra8.default.pathExists(tinaFolder) && (await import_fs_extra8.default.readdir(tinaFolder)).find((x) => x.includes("config"))
+    // Does the tina folder exist?
+    await import_fs_extra8.default.pathExists(tinaFolder) && // Does the tina folder contain a config file?
+    (await import_fs_extra8.default.readdir(tinaFolder)).find((x) => x.includes("config"))
   );
   const pagesDir = [baseDir, usingSrc ? "src" : false, "pages"].filter(
     Boolean
@@ -3844,6 +4025,7 @@ var supportedDatabaseAdapters = {
       {
         from: "mongodb",
         imported: [],
+        // not explicitly imported
         packageName: "mongodb"
       }
     ]
@@ -3916,6 +4098,10 @@ var chooseDatabaseAdapter = async ({
           title: "MongoDB",
           value: "mongodb"
         }
+        // {
+        //   title: "I'll create my own database adapter",
+        //   value: 'other',
+        // },
       ]
     }
   ]);
@@ -4193,6 +4379,7 @@ async function configure(env, opts) {
     packageManager,
     forestryMigrate: false,
     isLocalEnvVarName: "TINA_PUBLIC_IS_LOCAL",
+    // TODO: give this a better default
     typescript: false
   };
   if (config2.framework.name === "next") {
@@ -4296,15 +4483,25 @@ var import_js_yaml = __toESM(require("js-yaml"));
 var import_zod = __toESM(require("zod"));
 
 // src/cmds/forestry-migrate/util/errorSingleton.ts
-var ErrorSingleton = class {
+var ErrorSingleton = class _ErrorSingleton {
+  /**
+   * The Singleton's constructor should always be private to prevent direct
+   * construction calls with the `new` operator.
+   */
   constructor() {
   }
+  /**
+   * The static method that controls the access to the singleton instance.
+   *
+   * This implementation let you subclass the Singleton class while keeping
+   * just one instance of each subclass around.
+   */
   static getInstance() {
-    if (!ErrorSingleton.instance) {
-      ErrorSingleton.instance = new ErrorSingleton();
-      ErrorSingleton.instance.collectionNameErrors = [];
+    if (!_ErrorSingleton.instance) {
+      _ErrorSingleton.instance = new _ErrorSingleton();
+      _ErrorSingleton.instance.collectionNameErrors = [];
     }
-    return ErrorSingleton.instance;
+    return _ErrorSingleton.instance;
   }
   addErrorName(error) {
     this.collectionNameErrors.push(error);
@@ -4347,8 +4544,7 @@ var makeFieldsWithInternalCode = ({
   if (hasBody) {
     return [bodyField, `__TINA_INTERNAL__:::...${field}():::`];
   } else {
-    if (spread)
-      return `__TINA_INTERNAL__:::...${field}():::`;
+    if (spread) return `__TINA_INTERNAL__:::...${field}():::`;
     return `__TINA_INTERNAL__:::${field}():::`;
   }
 };
@@ -4432,6 +4628,7 @@ var forestryConfigSchema = import_zod.default.object({
   )
 });
 var forestryFieldWithoutField = import_zod.default.object({
+  // TODO: maybe better type this?
   type: import_zod.default.union([
     import_zod.default.literal("text"),
     import_zod.default.literal("datetime"),
@@ -4455,6 +4652,7 @@ var forestryFieldWithoutField = import_zod.default.object({
   default: import_zod.default.any().optional(),
   template: import_zod.default.string().optional(),
   config: import_zod.default.object({
+    // min and max are used for lists
     min: import_zod.default.number().optional().nullable(),
     max: import_zod.default.number().optional().nullable(),
     required: import_zod.default.boolean().optional().nullable(),
@@ -4468,6 +4666,7 @@ var forestryFieldWithoutField = import_zod.default.object({
         import_zod.default.literal("pages"),
         import_zod.default.literal("documents"),
         import_zod.default.literal("simple"),
+        // TODO: I want to ignore this key if its invalid
         import_zod.default.string()
       ]).optional().nullable(),
       section: import_zod.default.string().optional().nullable()
@@ -4503,6 +4702,7 @@ var transformForestryFieldsToTinaFields = ({
     }
     let field;
     switch (forestryField2.type) {
+      // Single filed types
       case "text":
         field = {
           type: "string",
@@ -4582,6 +4782,7 @@ var transformForestryFieldsToTinaFields = ({
           );
         }
         break;
+      // List Types
       case "list":
         field = {
           type: "string",
@@ -4604,6 +4805,7 @@ var transformForestryFieldsToTinaFields = ({
           }
         };
         break;
+      // Object (Group) types
       case "field_group":
         field = {
           type: "object",
@@ -4644,6 +4846,7 @@ var transformForestryFieldsToTinaFields = ({
           });
           const fieldsString = stringifyLabelWithField(template2.label);
           const t = {
+            // @ts-ignore
             fields: makeFieldsWithInternalCode({
               hasBody: false,
               field: fieldsString
@@ -4652,7 +4855,6 @@ var transformForestryFieldsToTinaFields = ({
             name: stringifyTemplateName(tem, tem)
           };
           if (t.name != tem) {
-            ;
             t.nameOverride = tem;
           }
           templates2.push(t);
@@ -4681,6 +4883,7 @@ var transformForestryFieldsToTinaFields = ({
           spread: true
         });
         tinaFields.push(
+          // @ts-ignore
           field2
         );
         break;
@@ -4740,6 +4943,7 @@ var parseSections = ({ val }) => {
 
 // src/cmds/forestry-migrate/index.ts
 var BODY_FIELD = {
+  // This is the body field
   type: "rich-text",
   name: "body",
   label: "Body of Document",
@@ -4798,8 +5002,7 @@ var generateAllTemplates = async ({
 };
 var generateCollectionFromForestrySection = (args) => {
   const { section, templateMap } = args;
-  if (section.read_only)
-    return;
+  if (section.read_only) return;
   let format3 = "md";
   if (section.new_doc_ext) {
     const ext = checkExt(section.new_doc_ext);
@@ -4866,12 +5069,14 @@ var generateCollectionFromForestrySection = (args) => {
     if (((forestryTemplates == null ? void 0 : forestryTemplates.length) || 0) > 1) {
       c = {
         ...baseCollection,
+        // @ts-expect-error
         templates: forestryTemplates.map((tem) => {
           const currentTemplate = templateMap.get(tem);
           const fieldsString = stringifyLabelWithField(
             currentTemplate.templateObj.label
           );
           return {
+            // fields: [BODY_FIELD],
             fields: makeFieldsWithInternalCode({
               hasBody,
               field: fieldsString,
@@ -4889,6 +5094,8 @@ var generateCollectionFromForestrySection = (args) => {
       const fieldsString = stringifyLabelWithField(template.templateObj.label);
       c = {
         ...baseCollection,
+        // fields: [BODY_FIELD],
+        // @ts-expect-error
         fields: makeFieldsWithInternalCode({
           field: fieldsString,
           hasBody,
@@ -5636,6 +5843,7 @@ var makeImportsVisitor = (sourceFile, importMap) => (ctx) => (node) => {
           ) : [];
           const newImports = [
             .../* @__PURE__ */ new Set([
+              // we use Set to remove duplicates
               ...existingImports,
               ...imports
             ])
@@ -5790,10 +5998,14 @@ var addSelfHostedTinaAuthToConfig = async (config2, configFile) => {
   );
   const { configImports, configAuthProviderClass, extraTinaCollections } = config2.authProvider;
   const importMap = {
-    ...configImports.reduce((acc, { from, imported }) => {
-      acc[from] = imported;
-      return acc;
-    }, {})
+    // iterate over configImports and add them to the import map
+    ...configImports.reduce(
+      (acc, { from, imported }) => {
+        acc[from] = imported;
+        return acc;
+      },
+      {}
+    )
   };
   const transformedSourceFileResult = import_typescript3.default.transform(
     sourceFile,
@@ -5964,7 +6176,13 @@ async function apply({
       config: config2
     });
   }
-  if (env.tinaConfigExists && params.isBackendInit && config2.hosting === "self-host" && (((_a = config2.authProvider) == null ? void 0 : _a.name) || "") !== "tina-cloud") {
+  if (
+    // if the config was just generated we do not need to update the config file because it will be generated correctly
+    env.tinaConfigExists && // Are we running tinacms init backend
+    params.isBackendInit && // Do the user choose the 'self-host' option
+    config2.hosting === "self-host" && // the user did not choose the 'tina-cloud' auth provider
+    (((_a = config2.authProvider) == null ? void 0 : _a.name) || "") !== "tina-cloud"
+  ) {
     await addSelfHostedTinaAuthToConfig(config2, env.generatedFiles["config"]);
   }
   logNextSteps({
@@ -6242,6 +6460,13 @@ ${titleText(" TinaCMS ")} has been initialized!`));
     logger.info(
       "To get started run: " + cmdText(frameworkDevCmds[framework.name]({ packageManager }))
     );
+    if (framework.name === "hugo") {
+      logger.info(
+        focusText("Hugo is required. "),
+        "Don't have Hugo installed? Follow this guide to set it up: ",
+        linkText("https://gohugo.io/installation/")
+      );
+    }
     logger.info(
       "To get your site production ready, run: " + cmdText(`tinacms init backend`)
     );
@@ -6257,6 +6482,7 @@ var other = ({ packageManager }) => {
   const packageManagers = {
     pnpm: `pnpm`,
     npm: `npx`,
+    // npx is the way to run executables that aren't in your "scripts"
     yarn: `yarn`
   };
   return `${packageManagers[packageManager]} tinacms dev -c "<your dev command>"`;
@@ -6269,6 +6495,7 @@ var frameworkDevCmds = {
     const packageManagers = {
       pnpm: `pnpm`,
       npm: `npm run`,
+      // npx is the way to run executables that aren't in your "scripts"
       yarn: `yarn`
     };
     return `${packageManagers[packageManager]} dev`;
@@ -6525,6 +6752,4 @@ cli.register(SearchIndexCommand);
 cli.register(import_clipanion8.Builtins.DefinitionsCommand);
 cli.register(import_clipanion8.Builtins.HelpCommand);
 cli.register(import_clipanion8.Builtins.VersionCommand);
-var src_default = cli;
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {});
+var index_default = cli;