feat: [v2] add compatibility check for v2 translations (#412)

Author: stevenle

.changeset/kind-pans-check.md

@@ -0,0 +1,5 @@
+---
+'@blinkk/root-cms': patch
+---
+
+feat: [v2] store compatibility versions in db

.changeset/strong-planes-float.md

@@ -0,0 +1,6 @@
+---
+'@blinkk/root-cms': patch
+'@blinkk/root': patch
+---
+
+feat: [v2] add compatibility check for v2 translations

packages/root-cms/core/client.ts

@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import {Plugin, RootConfig} from '@blinkk/root';
+import {RootConfig} from '@blinkk/root';
 import {App} from 'firebase-admin/app';
 import {
   FieldValue,
@@ -8,7 +8,7 @@ import {
   Timestamp,
   WriteBatch,
 } from 'firebase-admin/firestore';
-import {CMSPlugin} from './plugin.js';
+import {CMSPlugin, getCmsPlugin} from './plugin.js';
 
 export interface Doc<Fields = any> {
   /** The id of the doc, e.g. "Pages/foo-bar". */
@@ -956,15 +956,6 @@ export function isRichTextData(data: any) {
   );
 }
 
-export function getCmsPlugin(rootConfig: RootConfig): CMSPlugin {
-  const plugins: Plugin[] = rootConfig.plugins || [];
-  const plugin = plugins.find((plugin) => plugin.name === 'root-cms');
-  if (!plugin) {
-    throw new Error('could not find root-cms plugin config in root.config.ts');
-  }
-  return plugin as CMSPlugin;
-}
-
 /**
  * Walks the data tree and converts any array of objects into "array objects"
  * for storage in firestore.
@@ -1166,3 +1157,5 @@ export function parseDocId(docId: string) {
   }
   return {collection, slug};
 }
+
+export {getCmsPlugin};

packages/root-cms/core/compatibility.ts

@@ -0,0 +1,102 @@
+import {RootConfig} from '@blinkk/root';
+import {FieldValue} from 'firebase-admin/firestore';
+import type {CMSPlugin} from './plugin.js';
+
+/**
+ * Runs compatibility checks to ensure the current version of root supports
+ * any backwards-incompatible db changes.
+ *
+ * Compatibility versions are stored in the db in Projects/<projectId> under
+ * the "compatibility" key. If the compatibility version is less than the
+ * latest version, a backwards-friendly "migration" is done to ensure
+ * compatibility on both the old and new versions.
+ */
+export async function runCompatibilityChecks(
+  rootConfig: RootConfig,
+  cmsPlugin: CMSPlugin
+) {
+  const projectId = cmsPlugin.getConfig().id || 'default';
+  const db = cmsPlugin.getFirestore();
+  const projectConfigDocRef = db.doc(`Projects/${projectId}`);
+  const projectConfigDoc = await projectConfigDocRef.get();
+  const projectConfig = projectConfigDoc.data() || {};
+
+  const compatibilityVersions = projectConfig.compatibility || {};
+  let versionsChanged = false;
+
+  const translationsVersion = compatibilityVersions.translations || 0;
+  if (translationsVersion < 2) {
+    await migrateTranslationsToV2(rootConfig, cmsPlugin);
+    compatibilityVersions.translations = 2;
+    versionsChanged = true;
+  }
+
+  if (versionsChanged) {
+    await projectConfigDocRef.update({compatibility: compatibilityVersions});
+    console.log('[root cms] updated db compatibility');
+  }
+}
+
+/**
+ * Migrates translations from the "v1" format to "v2".
+ */
+async function migrateTranslationsToV2(
+  rootConfig: RootConfig,
+  cmsPlugin: CMSPlugin
+) {
+  if (rootConfig.experiments?.rootCmsDisableTranslationsToV2Check) {
+    return;
+  }
+
+  const projectId = cmsPlugin.getConfig().id || 'default';
+  const db = cmsPlugin.getFirestore();
+  const dbPath = `Projects/${projectId}/Translations`;
+  const query = db.collection(dbPath);
+  const querySnapshot = await query.get();
+  if (querySnapshot.size === 0) {
+    return;
+  }
+
+  console.log('[root cms] updating translations v2 compatibility');
+  const translationsMemories: Record<string, Record<string, any>> = {};
+  querySnapshot.forEach((doc) => {
+    const hash = doc.id;
+    const translation = doc.data();
+    const tags = translation.tags || [];
+    delete translation.tags;
+    for (const tag of tags) {
+      if (tag.includes('/')) {
+        const translationsMemoryId = tag.replaceAll('/', '--');
+        translationsMemories[translationsMemoryId] ??= {};
+        translationsMemories[translationsMemoryId][hash] = translation;
+      }
+    }
+  });
+
+  const batch = db.batch();
+  Object.entries(translationsMemories).forEach(
+    ([translationsMemoryId, strings]) => {
+      const updates = {
+        sys: {
+          modifiedAt: FieldValue.serverTimestamp(),
+          modifiedBy: 'root-cms-client',
+        },
+        strings: strings,
+      };
+      const draftRef = db.doc(
+        `Projects/${projectId}/TranslationsMemory/draft/Translations/${translationsMemoryId}`
+      );
+      const publishedRef = db.doc(
+        `Projects/${projectId}/TranslationsMemory/published/Translations/${translationsMemoryId}`
+      );
+      batch.set(draftRef, updates, {merge: true});
+      batch.set(publishedRef, updates, {merge: true});
+      const len = Object.keys(strings).length;
+      console.log(
+        `[root cms] saving ${len} string(s) to ${translationsMemoryId}...`
+      );
+    }
+  );
+  await batch.commit();
+  console.log('[root cms] done migrating translations to v2');
+}

packages/root-cms/core/plugin.ts

@@ -8,6 +8,7 @@ import {
   Plugin,
   Request,
   Response,
+  RootConfig,
   Server,
 } from '@blinkk/root';
 import bodyParser from 'body-parser';
@@ -24,6 +25,7 @@ import sirv from 'sirv';
 import {generateTypes} from '../cli/generate-types.js';
 import {api} from './api.js';
 import {Action, RootCMSClient} from './client.js';
+import {runCompatibilityChecks} from './compatibility.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -445,6 +447,19 @@ export function cmsPlugin(options: CMSPluginOptions): CMSPlugin {
       }
     },
 
+    hooks: {
+      /**
+       * Startup hook. On `dev` and `build` commands, the plugin does
+       * compatibility checks.
+       */
+      startup: async ({command, rootConfig}) => {
+        if (command === 'dev' || command === 'build') {
+          const cmsPlugin = getCmsPlugin(rootConfig);
+          await runCompatibilityChecks(rootConfig, cmsPlugin);
+        }
+      },
+    },
+
     /**
      * Attaches CMS-specific middleware to the Root.js server.
      */
@@ -597,3 +612,12 @@ function fileExists(filepath: string): Promise<boolean> {
     .then(() => true)
     .catch(() => false);
 }
+
+export function getCmsPlugin(rootConfig: RootConfig): CMSPlugin {
+  const plugins: Plugin[] = rootConfig.plugins || [];
+  const plugin = plugins.find((plugin) => plugin.name === 'root-cms');
+  if (!plugin) {
+    throw new Error('could not find root-cms plugin config in root.config.ts');
+  }
+  return plugin as CMSPlugin;
+}

packages/root/src/core/config.ts

@@ -4,6 +4,11 @@ import {HtmlPrettyOptions} from '../render/html-pretty.js';
 import {Plugin} from './plugin.js';
 import {RequestMiddleware} from './types.js';
 
+export interface RootExperimentsConfig {
+  [name: string]: boolean | undefined;
+  enableScriptAsync?: boolean;
+}
+
 export interface RootUserConfig {
   /**
    * Canonical domain the website will serve on. Useful for things like the
@@ -83,10 +88,7 @@ export interface RootUserConfig {
   /**
    * Experimental config options. Note: these are subject to change at any time.
    */
-  experiments?: {
-    /** Whether to render `<script>` tags with `async`. */
-    enableScriptAsync?: boolean;
-  };
+  experiments?: RootExperimentsConfig;
 }
 
 export type RootConfig = RootUserConfig & {