Refactor: Implement MetadataManager for Sync Service #7643

Author: tobiu

ai/mcp/server/github-workflow/services/SyncService.mjs

@@ -1,23 +1,18 @@
-import aiConfig      from '../config.mjs';
-import Base          from '../../../../../src/core/Base.mjs';
-import fs            from 'fs/promises';
-import logger        from '../logger.mjs';
-import path          from 'path';
-import IssueSyncer   from './sync/IssueSyncer.mjs';
-import ReleaseSyncer from './sync/ReleaseSyncer.mjs';
-
-const issueSyncConfig = aiConfig.issueSync;
+import aiConfig        from '../config.mjs';
+import Base            from '../../../../../src/core/Base.mjs';
+import logger          from '../logger.mjs';
+import IssueSyncer     from './sync/IssueSyncer.mjs';
+import MetadataManager from './sync/MetadataManager.mjs';
+import ReleaseSyncer   from './sync/ReleaseSyncer.mjs';
 
 /**
  * Orchestrates the bi-directional synchronization of GitHub issues and releases with local Markdown files.
  *
  * This service is the core engine for the GitHub sync workflow. Its primary responsibilities include:
- * - **State Management:** It maintains a persistent state via a `.sync-metadata.json` file to track
- *   the last sync time and the status of each item, enabling efficient delta-based updates.
  * - **Orchestration:** It calls specialized syncer modules (`IssueSyncer`, `ReleaseSyncer`) in the
  *   correct order to ensure data integrity and minimize conflicts (e.g., push-then-pull).
- * - **Metadata Management:** It loads the metadata at the start of a sync and saves the updated
- *   metadata, including new cache objects from the syncers, at the end.
+ * - **Metadata Management:** It uses the `MetadataManager` to load metadata at the start of a sync
+ *   and save the updated metadata at the end.
  *
  * The main entry point is the `runFullSync` method, which executes the entire orchestration sequence.
  * @class Neo.ai.mcp.server.github-workflow.SyncService
@@ -43,20 +38,20 @@ class SyncService extends Base {
      *
      * This method orchestrates the entire bi-directional sync workflow in a specific order
      * to ensure data integrity and minimize conflicts:
-     * 1.  Loads the persistent metadata from the last sync.
+     * 1.  Loads the persistent metadata from the last sync via `MetadataManager`.
      * 2.  Fetches and caches GitHub release data via `ReleaseSyncer`.
      * 3.  **Pushes** any local issue changes to GitHub via `IssueSyncer`.
      * 4.  **Pulls** the latest issue changes from GitHub via `IssueSyncer`.
      * 5.  Syncs release notes into local Markdown files via `ReleaseSyncer`.
-     * 6.  Saves the updated metadata (including new release and issue data) to disk.
+     * 6.  Saves the updated, pruned metadata to disk via `MetadataManager`.
      *
      * @returns {Promise<object>} A comprehensive object containing detailed statistics and timing
      * information about all operations performed during the sync.
      */
     async runFullSync() {
         const startTime = new Date();
 
-        const metadata = await this.#loadMetadata();
+        const metadata = await MetadataManager.load();
 
         // Fetch releases first, as they are needed for issue archiving
         await ReleaseSyncer.fetchAndCacheReleases(metadata);
@@ -89,7 +84,7 @@ class SyncService extends Base {
         newMetadata.releasesLastFetched = new Date().toISOString();
 
         // 6. Save metadata
-        await this.#saveMetadata(newMetadata);
+        await MetadataManager.save(newMetadata);
 
         const endTime    = new Date();
         const durationMs = endTime - startTime;
@@ -121,41 +116,6 @@ class SyncService extends Base {
             timing
         };
     }
-
-    /**
-     * Loads the synchronization metadata file from disk. If the file doesn't exist,
-     * it returns a default empty metadata object.
-     * @returns {Promise<object>} The parsed metadata object.
-     * @throws {Error} If reading the file fails for reasons other than not existing.
-     * @private
-     */
-    async #loadMetadata() {
-        try {
-            const data = await fs.readFile(issueSyncConfig.metadataFile, 'utf-8');
-            return JSON.parse(data);
-        } catch (error) {
-            if (error.code === 'ENOENT') {
-                return {
-                    lastSync: null,
-                    issues   : {}
-                };
-            }
-            throw error;
-        }
-    }
-
-    /**
-     * Saves the provided metadata object to the configured metadata file on disk,
-     * ensuring the directory exists.
-     * @param {object} metadata - The metadata object to serialize and save.
-     * @returns {Promise<void>}
-     * @private
-     */
-    async #saveMetadata(metadata) {
-        const dir = path.dirname(issueSyncConfig.metadataFile);
-        await fs.mkdir(dir, { recursive: true });
-        await fs.writeFile(issueSyncConfig.metadataFile, JSON.stringify(metadata, null, 2), 'utf-8');
-    }
 }
 
 export default Neo.setupClass(SyncService);

ai/mcp/server/github-workflow/services/sync/MetadataManager.mjs

@@ -0,0 +1,91 @@
+import aiConfig from '../../config.mjs';
+import Base     from '../../../../../../src/core/Base.mjs';
+import fs       from 'fs/promises';
+import path     from 'path';
+
+const issueSyncConfig = aiConfig.issueSync;
+
+/**
+ * Manages loading, saving, and pruning of the .sync-metadata.json file.
+ * @class Neo.ai.mcp.server.github-workflow.services.sync.MetadataManager
+ * @extends Neo.core.Base
+ * @singleton
+ */
+class MetadataManager extends Base {
+    static config = {
+        /**
+         * @member {String} className='Neo.ai.mcp.server.github-workflow.services.sync.MetadataManager'
+         * @protected
+         */
+        className: 'Neo.ai.mcp.server.github-workflow.services.sync.MetadataManager',
+        /**
+         * @member {Boolean} singleton=true
+         * @protected
+         */
+        singleton: true
+    }
+
+    /**
+     * Loads the synchronization metadata file from disk.
+     * If the file doesn't exist, it returns a default empty metadata object.
+     * @returns {Promise<object>} The parsed metadata object.
+     * @throws {Error} If reading the file fails for reasons other than not existing.
+     */
+    async load() {
+        try {
+            const data = await fs.readFile(issueSyncConfig.metadataFile, 'utf-8');
+            return JSON.parse(data);
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return {
+                    lastSync: null,
+                    issues: {},
+                    releases: {}
+                };
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Saves the provided metadata object to the configured metadata file on disk,
+     * ensuring the directory exists. This method also prunes the data to save only
+     * essential fields for change detection.
+     * @param {object} metadata - The metadata object to serialize and save.
+     * @returns {Promise<void>}
+     */
+    async save(metadata) {
+        const prunedMetadata = {
+            lastSync           : metadata.lastSync,
+            releasesLastFetched: metadata.releasesLastFetched,
+            pushFailures       : metadata.pushFailures || [],
+            issues             : {},
+            releases           : {}
+        };
+
+        // Prune issues
+        for (const [key, value] of Object.entries(metadata.issues)) {
+            prunedMetadata.issues[key] = {
+                state      : value.state,
+                path       : value.path,
+                updated    : value.updated,
+                contentHash: value.contentHash
+            };
+        }
+
+        // Prune releases
+        for (const [key, value] of Object.entries(metadata.releases)) {
+            prunedMetadata.releases[key] = {
+                publishedAt: value.publishedAt,
+                contentHash: value.contentHash
+            };
+        }
+
+        const dir = path.dirname(issueSyncConfig.metadataFile);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(issueSyncConfig.metadataFile, JSON.stringify(prunedMetadata, null, 2), 'utf-8');
+    }
+}
+
+export default Neo.setupClass(MetadataManager);

ai/mcp/server/github-workflow/services/sync/ReleaseSyncer.mjs

@@ -95,9 +95,9 @@ class ReleaseSyncer extends Base {
         // Phase 2: Full fetch with early exit
         logger.info('Fetching releases from GitHub via GraphQL...');
 
-        let allReleases = [];
-        let hasNextPage = true;
-        let cursor      = null;
+        let allReleases   = [];
+        let hasNextPage   = true;
+        let cursor        = null;
         const maxReleases = issueSyncConfig.maxReleases;
         const startDate   = new Date(issueSyncConfig.syncStartDate);