strapi-content-sync-pro 1.0.4 → 1.0.6

package/docs/sync-strategy-approach-review.md

@@ -0,0 +1,127 @@
+# Sync Strategy Approach Review
+
+This document consolidates and refines the agreed approach for sync reliability, dependency handling, content-type enabling, and profile editing.
+
+## 1) Core Execution Strategy (Hybrid Two-Pass)
+
+**Consolidated rule:** Use a hybrid two-pass sync approach: **pass 1 syncs core entities, pass 2 syncs one-direction dependencies from owner/declaring side only** (entities first, relations second).
+
+Implementation shape:
+
+1. **Pass 1: Entities First**
+   - Sync core entity payload first (materialize records on both sides).
+   - Avoid relation-linking behavior in this pass.
+2. **Pass 2: Relations Second (One Direction)**
+   - Sync dependencies/relations only after entities exist.
+   - Apply relation sync in one direction from the **owner/declaring side only**.
+
+### Media in the Same Two-Pass Model
+
+Media follows the same strategy:
+
+1. **Pass 1 (Core media):** sync media entities/files first.
+2. **Pass 2 (Media links):** sync media relations from owner entities (content types that hold media fields).
+
+Design decision:
+
+- Treat media as a referenced target, not the relation-driving owner.
+- Relation updates are written from owning entities only.
+- Remove separate morph-side traversal/update strategy from the approach.
+
+Why: this removes duplicate/bi-directional link work, reduces conflict risk, and keeps relation application deterministic.
+
+---
+
+## 2) Dependency Rules (Authoritative)
+
+For dependency sync:
+
+1. `dependencyDepth` is always **1**.
+2. Include only dependency targets that are part of sync scope.
+3. Never traverse owning-side metadata graph expansion via `mappedBy` / `inversedBy`.
+4. In pass 2, apply relation updates from the **owner/declaring side only**.
+
+Applied interpretation:
+
+- Use direct relation target only.
+- Exclude self-links and out-of-scope content types.
+- No recursive traversal.
+- No inverse-side fan-out traversal.
+- Media links are applied only from owner entities; no separate morph-driven inverse traversal.
+
+---
+
+## 3) Execution Ordering
+
+- Entities pass runs first for all selected content types and core media.
+- Relations pass runs second for all selected content types, including media link fields from owner entities.
+- Ordering remains dependency-aware and stable.
+- For relation-heavy types, keep lower priority (higher order number) where ordering tie-break is needed.
+
+---
+
+## 4) Enabling Content Types
+
+When enabling a content type, provide:
+
+1. **Enable only selected type**
+2. **Enable selected type + direct dependencies (depth=1)**
+
+Behavior for “enable with dependencies”:
+
+- Expand only direct in-scope relation targets.
+- Do not recursively traverse.
+- Do not traverse through `mappedBy` / `inversedBy`.
+
+Recommended UX:
+
+- Show preview summary before apply:
+  - to enable
+  - already enabled
+  - skipped/out-of-scope
+
+---
+
+## 5) Sync Profiles and Advanced Editing
+
+Profiles should remain fully editable and not locked by auto-generation.
+
+For newly enabled types, support:
+
+1. **Quick defaults** (auto-create profiles)
+2. **Create + edit now** (guided advanced configuration)
+
+Editable advanced settings include:
+
+- direction
+- conflict strategy
+- sync deletions
+- execution mode
+- dependency sync toggle
+- dependency depth (fixed to 1 where dependency sync is used)
+- field-level policies
+
+---
+
+## 6) Suggested Implementation Sequence
+
+1. Add strategy contract as **hybrid two-pass default**.
+2. Enforce dependency constraints globally (depth=1, in-scope only, no mappedBy/inversedBy traversal).
+3. Implement orchestration in sync-now, profile execution, and bulk transfer:
+   - pass 1 entities + core media
+   - pass 2 owner-side relations (including media links from owner entities)
+   - remove separate morph/inverse traversal flow
+4. Add content-type enable flow with “enable dependencies too” option and preview.
+5. Keep profile editing fully available, including advanced settings.
+6. Update UI hints to explain constraints and reliability tradeoffs.
+
+---
+
+## 7) Final Position
+
+- Use **hybrid two-pass** execution: entities/core media first, relations second.
+- Relation sync in pass 2 is **one directional from owner/declaring side**.
+- Media links are synced from owner entities only; no separate morph-side inverse traversal strategy.
+- Keep dependency scope constrained (depth=1, in-scope targets only).
+- Add dependency-aware enable-all-direct-dependencies option.
+- Preserve and improve advanced profile editing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strapi-content-sync-pro",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Strapi v5 plugin to copy, migrate, and live-sync content, media, and data between multiple Strapi environments with bi-directional sync, field-level policies, scheduling, and alerts.",
   "license": "MIT",
   "author": {

package/server/src/controllers/config.js

@@ -198,12 +198,69 @@ module.exports = {
    * Proxy login to remote Strapi and retrieve/create API token
    */
   async remoteLogin(ctx) {
-    const { baseUrl, email, password } = ctx.request.body;
+    const { baseUrl: rawBaseUrl, email, password } = ctx.request.body;
 
-    if (!baseUrl || !email || !password) {
+    if (!rawBaseUrl || !email || !password) {
       return ctx.badRequest('baseUrl, email, and password are required');
     }
 
+    // --- Normalize and validate the base URL so URL mistakes produce a clear message ---
+    let baseUrl = String(rawBaseUrl).trim();
+    if (!/^https?:\/\//i.test(baseUrl)) {
+      return ctx.badRequest(
+        `Invalid Server URL "${rawBaseUrl}": must start with http:// or https:// (e.g. http://localhost:4010)`
+      );
+    }
+    // Strip trailing slashes and accidental /admin suffix
+    baseUrl = baseUrl.replace(/\/+$/, '').replace(/\/admin$/i, '');
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(baseUrl);
+    } catch {
+      return ctx.badRequest(
+        `Invalid Server URL "${rawBaseUrl}": not a valid URL. Expected format: http(s)://host[:port]`
+      );
+    }
+    if (!parsedUrl.hostname) {
+      return ctx.badRequest(`Invalid Server URL "${rawBaseUrl}": missing hostname`);
+    }
+
+    // --- Pre-flight reachability check against /admin/init so wrong URL != "invalid credentials" ---
+    try {
+      const initResp = await fetch(`${baseUrl}/admin/init`, { method: 'GET' });
+      if (!initResp.ok) {
+        return ctx.throw(
+          502,
+          `Server URL "${baseUrl}" is reachable but did not respond as a Strapi admin (HTTP ${initResp.status} on /admin/init). Check that the URL points to the root of a Strapi v5 server (no /admin suffix) and that the admin panel is enabled.`
+        );
+      }
+      const initData = await initResp.json().catch(() => null);
+      if (!initData || typeof initData !== 'object' || !('data' in initData)) {
+        return ctx.throw(
+          502,
+          `Server URL "${baseUrl}" did not return a valid Strapi /admin/init response. Please verify the URL points to a Strapi v5 instance.`
+        );
+      }
+      if (initData.data && initData.data.hasAdmin === false) {
+        return ctx.throw(
+          400,
+          `Remote Strapi at "${baseUrl}" has no admin user yet. Create the first admin in the remote Strapi panel before generating a token.`
+        );
+      }
+    } catch (err) {
+      if (err && err.status) throw err;
+      const code = err && (err.cause?.code || err.code);
+      const hint =
+        code === 'ECONNREFUSED'
+          ? 'Connection refused — the server is not running or not listening on that port.'
+          : code === 'ENOTFOUND'
+            ? 'Host not found — check the hostname/IP spelling and that it resolves from this machine.'
+            : code === 'ETIMEDOUT'
+              ? 'Request timed out — check firewall, network, and that the port is reachable.'
+              : 'Network error while contacting the remote server.';
+      return ctx.throw(502, `Cannot reach "${baseUrl}": ${hint}${code ? ` (${code})` : ''}`);
+    }
+
     try {
       // Step 1: Login to remote Strapi admin
       const loginResponse = await fetch(`${baseUrl}/admin/login`, {
@@ -219,7 +276,23 @@ module.exports = {
 
       if (!loginResponse.ok) {
         const errorBody = await loginResponse.json().catch(() => ({}));
-        const errorMessage = errorBody?.error?.message || `Login failed with status ${loginResponse.status}`;
+        const remoteMsg = errorBody?.error?.message;
+        // Distinguish URL-vs-credential failures so users aren't misled
+        if (loginResponse.status === 404) {
+          return ctx.throw(
+            404,
+            `"${baseUrl}/admin/login" not found (HTTP 404). The Server URL likely points to the wrong path — use the Strapi root URL (e.g. http://localhost:4010), not an admin or API sub-path.`
+          );
+        }
+        if (loginResponse.status === 405) {
+          return ctx.throw(
+            405,
+            `"${baseUrl}/admin/login" rejected the request method. The Server URL may be pointing to a proxy or non-Strapi endpoint.`
+          );
+        }
+        const errorMessage = remoteMsg
+          ? `Remote login failed: ${remoteMsg}. If you believe the credentials are correct, double-check the Server URL "${baseUrl}" is the right Strapi instance.`
+          : `Login failed with status ${loginResponse.status} at ${baseUrl}/admin/login`;
         return ctx.throw(loginResponse.status, errorMessage);
       }
 

package/server/src/controllers/sync-media.js

@@ -111,6 +111,30 @@ module.exports = ({ strapi }) => ({
     }
   },
 
+  async pauseProfile(ctx) {
+    try {
+      ctx.body = { data: await service(strapi).pauseProfile(ctx.params.id) };
+    } catch (err) {
+      ctx.throw(400, err.message);
+    }
+  },
+
+  async resumeProfile(ctx) {
+    try {
+      ctx.body = { data: await service(strapi).resumeProfile(ctx.params.id) };
+    } catch (err) {
+      ctx.throw(400, err.message);
+    }
+  },
+
+  async cancelProfile(ctx) {
+    try {
+      ctx.body = { data: await service(strapi).cancelProfile(ctx.params.id) };
+    } catch (err) {
+      ctx.throw(400, err.message);
+    }
+  },
+
   // ── Morph link sync (documentId-based mapping) ───────────────────────────
 
   async getMorphLinks(ctx) {

package/server/src/routes/index.js

@@ -91,6 +91,9 @@ const adminRoutes = [
   { method: 'DELETE', path: '/media-sync/profiles/:id',          handler: 'syncMedia.deleteProfile',       config: { policies: [] } },
   { method: 'POST',   path: '/media-sync/profiles/:id/activate', handler: 'syncMedia.activateProfile',    config: { policies: [] } },
   { method: 'POST',   path: '/media-sync/profiles/:id/run',     handler: 'syncMedia.runProfile',          config: { policies: [] } },
+  { method: 'POST',   path: '/media-sync/profiles/:id/pause',   handler: 'syncMedia.pauseProfile',        config: { policies: [] } },
+  { method: 'POST',   path: '/media-sync/profiles/:id/resume',  handler: 'syncMedia.resumeProfile',       config: { policies: [] } },
+  { method: 'POST',   path: '/media-sync/profiles/:id/cancel',  handler: 'syncMedia.cancelProfile',       config: { policies: [] } },
   { method: 'POST',   path: '/media-sync/run-active',           handler: 'syncMedia.runActiveProfiles',   config: { policies: [] } },
   { method: 'GET',    path: '/media-sync/morph-links',          handler: 'syncMedia.getMorphLinks',       config: { policies: [] } },
   { method: 'POST',   path: '/media-sync/morph-links/apply',    handler: 'syncMedia.applyMorphLinks',     config: { policies: [] } },

package/server/src/services/bulk-transfer.js

@@ -140,6 +140,49 @@ module.exports = ({ strapi }) => {
     return out;
   }
 
+  function orderByDependencies(uids) {
+    const depResolver = plugin().service('dependencyResolver');
+    const uidSet = new Set(uids);
+    const inDegree = new Map();
+    const adjacency = new Map();
+
+    uids.forEach((uid) => {
+      inDegree.set(uid, 0);
+      adjacency.set(uid, []);
+    });
+
+    for (const uid of uids) {
+      try {
+        const rels = depResolver.analyzeContentType(uid)?.relations || [];
+        for (const rel of rels) {
+          const depUid = rel.target;
+          if (!uidSet.has(depUid) || depUid === uid) continue;
+          adjacency.get(depUid).push(uid);
+          inDegree.set(uid, (inDegree.get(uid) || 0) + 1);
+        }
+      } catch (_) {
+        // Ignore bad schema and keep fallback order.
+      }
+    }
+
+    const queue = uids.filter((uid) => (inDegree.get(uid) || 0) === 0);
+    const ordered = [];
+    while (queue.length > 0) {
+      const uid = queue.shift();
+      ordered.push(uid);
+      for (const next of adjacency.get(uid) || []) {
+        const deg = (inDegree.get(next) || 0) - 1;
+        inDegree.set(next, deg);
+        if (deg === 0) queue.push(next);
+      }
+    }
+
+    for (const uid of uids) {
+      if (!ordered.includes(uid)) ordered.push(uid);
+    }
+    return ordered;
+  }
+
   function listMediaProfilesToRun() {
     // Use the media service's own active-profile semantics by delegating
     // to runActiveProfiles at execute time; here we just need chunk labels.
@@ -153,7 +196,8 @@ module.exports = ({ strapi }) => {
     const chunks = [];
 
     if (scopes.content) {
-      for (const uid of listSyncableContentTypeUids()) {
+      const orderedContentTypes = orderByDependencies(listSyncableContentTypeUids());
+      for (const uid of orderedContentTypes) {
         chunks.push({ kind: 'content', uid, label: uid });
       }
     }

package/server/src/services/dependency-resolver.js

@@ -195,6 +195,43 @@ module.exports = ({ strapi }) => {
       return order;
     },
 
+    /**
+     * Get constrained dependency targets for a content type under one-pass rules:
+     *   - depth fixed to 1
+     *   - only direct owner-side relation targets (no mappedBy / inversedBy)
+     *   - only targets in sync scope (scopeUids set)
+     * Returns array of { uid, field, relation } objects.
+     */
+    getConstrainedDependencyTargets(uid, scopeUids = new Set()) {
+      const analysis = this.analyzeContentType(uid);
+      const results = [];
+
+      for (const rel of analysis.relations) {
+        // Owner/declaring side only: skip inverse and mapped-by sides
+        if (rel.mappedBy || rel.inversedBy) continue;
+        // Skip self-references
+        if (rel.target === uid) continue;
+        // Skip targets not in sync scope
+        if (scopeUids.size > 0 && !scopeUids.has(rel.target)) continue;
+        // Skip plugin-internal types unless users-permissions
+        if (rel.target.startsWith('plugin::') && !rel.target.startsWith('plugin::users-permissions')) continue;
+
+        results.push({
+          uid: rel.target,
+          field: rel.field,
+          relation: rel.relation,
+        });
+      }
+
+      // Deduplicate by target uid (keep first occurrence)
+      const seen = new Set();
+      return results.filter((r) => {
+        if (seen.has(r.uid)) return false;
+        seen.add(r.uid);
+        return true;
+      });
+    },
+
     /**
      * Extract related entity IDs from a record for dependency syncing
      */

package/server/src/services/sync-execution.js

@@ -277,7 +277,8 @@ module.exports = ({ strapi }) => {
 
       const executionSettings = await this.getProfileExecutionSettings(profileId);
       const syncDependencies = options.syncDependencies ?? executionSettings.syncDependencies;
-      const dependencyDepth = options.dependencyDepth ?? executionSettings.dependencyDepth ?? 1;
+      // dependencyDepth is always 1 per strategy constraints regardless of stored setting
+      const dependencyDepth = 1;
 
       const startTime = new Date();
       const reportHandle = await syncStatsService.createRunReport({
@@ -299,14 +300,25 @@ module.exports = ({ strapi }) => {
 
         const dependencyResults = [];
         if (syncDependencies) {
-          const dependencyOrder = dependencyResolver
-            .getSyncOrder(profile.contentType, dependencyDepth)
-            .filter((uid) => uid !== profile.contentType && uid.startsWith('api::') && !!strapi.contentTypes[uid]);
-
-          for (const dependencyUid of dependencyOrder) {
-            const syncConfigService = plugin().service('syncConfig');
-            const syncConfig = await syncConfigService.getSyncConfig();
-            const depEnabled = (syncConfig.contentTypes || []).some((ct) => ct.uid === dependencyUid && ct.enabled);
+          // Constrained dependency expansion:
+          //   - depth fixed to 1
+          //   - owner/declaring side only (no mappedBy/inversedBy traversal)
+          //   - only targets in sync scope (enabled content types)
+          const syncConfigService = plugin().service('syncConfig');
+          const syncConfig = await syncConfigService.getSyncConfig();
+          const scopeUids = new Set(
+            (syncConfig.contentTypes || [])
+              .filter((ct) => ct.enabled && ct.uid !== profile.contentType)
+              .map((ct) => ct.uid)
+          );
+
+          const constrainedTargets = dependencyResolver.getConstrainedDependencyTargets(
+            profile.contentType,
+            scopeUids
+          );
+
+          for (const { uid: dependencyUid } of constrainedTargets) {
+            const depEnabled = scopeUids.has(dependencyUid);
             if (!depEnabled) {
               dependencyResults.push({
                 uid: dependencyUid,