@pintawebware/strapi-sync 1.0.4

package/README.md

@@ -0,0 +1,322 @@
+# strapi-sync
+
+Export Strapi schemas and content to a snapshot file and apply snapshot changes back to Strapi.
+
+## Configuration
+
+Optional config file in the project root: `.strapi-sync.json`, `strapi-sync.config.json`, or `strapi-sync.json`.
+
+`strapi-sync` also loads `.env` from the project root before resolving environment fallback values.
+
+`.env` example:
+
+```env
+STRAPI_URL=https://cms.example.com
+STRAPI_API_TOKEN=your-api-token
+STRAPI_PROJECT_PATH=/var/www/strapi-app
+STRAPI_SSH_HOST=cms.example.com
+STRAPI_SSH_USER=deploy
+STRAPI_SSH_PORT=22
+STRAPI_SSH_PASSWORD=your-password
+STRAPI_SSH_PRIVATE_KEY_PATH=C:/Users/Ivan/.ssh/id_rsa
+```
+
+Minimal config example:
+
+```json
+{
+  "strapiUrl": "https://your-strapi.example.com",
+  "apiToken": "your-api-token",
+  "strapiProjectPath": "/var/www/strapi-app",
+  "strapiSSHUser": "deploy",
+  "strapiSSHPassword": "your-password",
+  "strapiSSHPrivateKeyPath": "C:/Users/Ivan/.ssh/id_rsa"
+}
+```
+
+For local schema writes, set `strapiProjectPath` to the local project path.
+
+For remote schema writes, set `strapiProjectPath` to the remote project path and add `strapiSSHHost` with either `strapiSSHPassword` or `strapiSSHPrivateKeyPath`.
+
+Config values are applied in this order, from lower priority to higher priority:
+
+1. `.env` or process environment values for fallback-supported fields
+2. Project json config file
+3. CLI flags
+
+Supported environment variables:
+
+- `STRAPI_URL`
+- `STRAPI_API_TOKEN`
+- `STRAPI_PROJECT_PATH`
+- `STRAPI_SSH_HOST`
+- `STRAPI_SSH_USER`
+- `STRAPI_SSH_PORT`
+- `STRAPI_SSH_PASSWORD`
+- `STRAPI_SSH_PRIVATE_KEY_PATH`
+
+Only these exact environment variable names are read by the CLI.
+
+Environment variables are used only when the corresponding CLI or config value is missing.
+
+Supported config fields:
+
+- `strapiUrl` - required
+- `apiToken` - required
+- `output` - optional, default `strapi-snapshot.json`
+- `strapiProjectPath` - optional for export and content-only sync; required for local or remote schema writes
+- `strapiSSHHost` - optional, enables remote SSH schema writes when set
+- `updateSchema` - optional, default `true`
+- `strapiSSHUser` - optional, default `root` for remote SSH writes
+- `strapiSSHPort` - optional, default `22` for remote SSH writes
+- `strapiSSHPassword` - optional, no default
+- `strapiSSHPrivateKeyPath` - optional, no default
+
+## Usage
+
+Export a snapshot from Strapi:
+
+```bash
+strapi-sync --export
+```
+
+Apply the current snapshot:
+
+```bash
+strapi-sync
+```
+
+Show package version:
+
+```bash
+strapi-sync --version
+```
+
+## Options
+
+- `--export` – Optional. Export from Strapi to snapshot and exit. Default behavior without this flag is apply mode.
+- `--output <path>` – Optional. Snapshot file path. Default `strapi-snapshot.json`.
+- `-p, --project <path>` – Optional. Project directory used for config and snapshot resolution. Default is current working directory.
+- `-u, --strapi-url <url>` – Optional if `strapiUrl` exists in config. Otherwise required.
+- `--api-token <token>` – Optional if `apiToken` exists in config. Otherwise required.
+- `--config <path>` – Optional. Use a custom JSON config file instead of the auto-discovered one.
+- `--strapi-project <path>` – Optional. Override `strapiProjectPath` from config or `STRAPI_PROJECT_PATH`.
+- `--strapi-ssh-host <host>` – Optional. Set the SSH host for remote schema writes.
+- `--strapi-ssh-user <user>` – Optional. Override the SSH user for remote schema writes.
+- `--strapi-ssh-port <port>` – Optional. Override the SSH port for remote schema writes.
+- `--strapi-ssh-password <pwd>` – Optional. Use SSH password auth for remote schema writes.
+- `--strapi-ssh-key <path>` – Optional. Use a private key file for remote schema writes.
+- `-h, --help` – Optional. Show help and exit.
+- `-v, --version` – Optional. Show the installed package version and exit.
+
+## Behavior
+
+- Running `strapi-sync` always prints a preview before confirmation.
+- Running `strapi-sync --export` asks for confirmation before overwriting the snapshot file.
+- Schema writes are controlled by `updateSchema` in config.
+- When `strapiSSHHost` is set, `strapiProjectPath` is treated as a remote filesystem path and schema writes are executed over SSH.
+- When `strapiSSHHost` is not set, `strapiProjectPath` is treated as a local filesystem path.
+- Remote schema writes support password auth or private key auth.
+- After any successful change, the snapshot is exported again from Strapi.
+- Adding a field to schema without adding a value for that field in snapshot entries is treated as a schema-only change.
+- Media fields are exported and shown in schema definitions, but content writes skip them.
+- Unknown CLI arguments stop the command with an error.
+- Invalid snapshot syntax stops the command with detailed validation errors.
+
+## Snapshot Format
+
+The snapshot file contains:
+
+- `version`
+- `contentTypes`
+- `components`
+
+Component definitions live in the top-level `components` block:
+
+```json
+{
+  "components": {
+    "shared.seo": {
+      "attributes": {
+        "metaTitle": "string",
+        "metaDescription": "string"
+      }
+    }
+  }
+}
+```
+
+Each content type includes `singleType`, `attributes`, and `entries`.
+
+Collection type example:
+
+```json
+{
+  "singleType": false,
+  "attributes": {
+    "title": "string"
+  },
+  "entries": [
+    {
+      "title": "Example"
+    }
+  ]
+}
+```
+
+Localized collection type example:
+
+```json
+{
+  "singleType": false,
+  "attributes": {
+    "title": "string"
+  },
+  "entries": {
+    "en": [
+      {
+        "title": "Example"
+      }
+    ],
+    "uk": [
+      {
+        "title": "Приклад"
+      }
+    ]
+  }
+}
+```
+
+Single type example:
+
+```json
+{
+  "singleType": true,
+  "attributes": {
+    "title": "string"
+  },
+  "entries": {
+    "title": "Example"
+  }
+}
+```
+
+Localized single type example:
+
+```json
+{
+  "singleType": true,
+  "attributes": {
+    "title": "string"
+  },
+  "entries": {
+    "en": {
+      "title": "Example"
+    },
+    "uk": {
+      "title": "Приклад"
+    }
+  }
+}
+```
+
+For `singleType: false`, `entries` must be an array or an object with locale keys.
+
+For `singleType: true`, `entries` must be a single object or an object with locale keys that point to objects.
+
+Supported attribute examples:
+
+- `string`
+- `number`
+- `boolean`
+- `date`
+- `json`
+- `media`
+- `media[]`
+- `component:shared.seo`
+- `component:shared.gallery:repeatable`
+- `["shared.media", "shared.rich-text"]` for dynamic zones
+- `relation:article:oneToMany`
+
+Component field example:
+
+```json
+{
+  "singleType": false,
+  "attributes": {
+    "seo": "component:shared.seo"
+  },
+  "entries": [
+    {
+      "seo": {
+        "metaTitle": "Example",
+        "metaDescription": "Example description"
+      }
+    }
+  ]
+}
+```
+
+Repeatable component example:
+
+```json
+{
+  "singleType": false,
+  "attributes": {
+    "gallery": "component:shared.gallery:repeatable"
+  },
+  "entries": [
+    {
+      "gallery": [
+        {
+          "title": "Slide 1"
+        },
+        {
+          "title": "Slide 2"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Dynamic zone example:
+
+```json
+{
+  "singleType": false,
+  "attributes": {
+    "blocks": [
+      "shared.media",
+      "shared.rich-text"
+    ]
+  },
+  "entries": [
+    {
+      "blocks": [
+        {
+          "__component": "shared.rich-text",
+          "body": "Example text"
+        },
+        {
+          "__component": "shared.media",
+          "caption": "Example image"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Relation attributes must use the short form like `relation:article:oneToMany`. During schema writes it is expanded to the full Strapi UID automatically.
+
+Supported relation examples:
+
+- `relation:article:oneToOne`
+- `relation:article:oneToMany`
+- `relation:article:manyToOne`
+- `relation:article:manyToMany`
+- `relation:article:oneWay`
+- `relation:article:manyWay`
+- `relation:article:morphOne`
+- `relation:article:morphMany`

package/bin/cli.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const readline = require('readline');
+const { version } = require('../package.json');
+const { StrapiSyncClient } = require('../lib/strapi-client');
+const { getSchemaUpdater } = require('../lib/schema-writer');
+const { parseArgs } = require('../lib/config');
+const { exportSnapshot, loadSnapshotFile } = require('../lib/snapshot-io');
+const { contentTypeDisplayName, formatContentForLog } = require('../lib/format');
+const { computeChangeMaps, printPreview } = require('../lib/preview');
+const { getContentTypeId } = require('../lib/snapshot-utils');
+const {
+  fetchStrapiState,
+  computeComponentChanges,
+  getPreviewCounts,
+  getNonActionableNotes,
+  applySchemaChanges,
+  waitForStrapiReload,
+  applyContentChanges
+} = require('../lib/sync-engine');
+
+function askConfirmation(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+function printHelp() {
+  console.log(`
+Usage: strapi-sync [options]
+
+Commands:
+  strapi-sync              Preview and apply snapshot changes
+  strapi-sync --export     Export Strapi data to snapshot and exit
+
+Options:
+  --output <path>              Snapshot file path (default: strapi-snapshot.json)
+  -p, --project <path>         Project directory used for config and snapshot paths
+  -u, --strapi-url <url>       Strapi server URL
+  --api-token <token>          Strapi API token
+  --config <path>              Custom JSON config file
+  --strapi-project <path>      Strapi project path for schema updates
+  --strapi-ssh-host <host>     SSH host for remote schema updates
+  --strapi-ssh-user <user>     SSH user for remote schema updates
+  --strapi-ssh-port <port>     SSH port for remote schema updates
+  --strapi-ssh-password <pwd>  SSH password for remote schema updates
+  --strapi-ssh-key <path>      SSH private key for remote schema updates
+  -h, --help                   Show this help
+  -v, --version                Show package version
+
+Notes:
+  Media fields are exported but not applied back to Strapi.
+`);
+}
+
+function resolveOutputPath(output, projectPath) {
+  return path.isAbsolute(output) ? output : path.resolve(projectPath, output);
+}
+
+async function main() {
+  const options = parseArgs();
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+  if (options.version) {
+    console.log(version);
+    process.exit(0);
+  }
+  if (!options.apiToken) {
+    console.error('❌ Error: API token not specified. Set it in config file or pass via parameters.');
+    process.exit(1);
+  }
+  if (!options.strapiUrl) {
+    console.error('❌ Error: Strapi URL not specified. Set it in config file or use --strapi-url.');
+    process.exit(1);
+  }
+
+  const client = new StrapiSyncClient({
+    baseURL: options.strapiUrl,
+    apiToken: options.apiToken
+  });
+
+  if (options.export) {
+    try {
+      const outputPath = resolveOutputPath(options.output, options.projectPath);
+      console.log('');
+      const confirmed = await askConfirmation(`Export from Strapi and overwrite ${path.basename(outputPath)}? (y/N) `);
+      if (!confirmed) {
+        console.log('Aborted.');
+        process.exit(0);
+      }
+      console.log('📥 Exporting schema and content from Strapi...');
+      await exportSnapshot(client, outputPath);
+      console.log(`✓ Snapshot written: ${outputPath}`);
+      process.exit(0);
+    } catch (error) {
+      console.error('❌', error.message);
+      process.exit(1);
+    }
+  }
+
+  let groupedObjects = {};
+  let snapshotContentTypes = {};
+  let snapshotComponents = {};
+  let snapshotPath;
+
+  try {
+    snapshotPath = resolveOutputPath(options.output, options.projectPath);
+    console.log('📂 Loading snapshot...');
+    const loaded = loadSnapshotFile(snapshotPath);
+    groupedObjects = loaded.groupedObjects;
+    snapshotContentTypes = loaded.snapshotContentTypes ?? {};
+    snapshotComponents = loaded.snapshotComponents ?? {};
+    console.log(`✓ Loaded ${Object.keys(groupedObjects).length} content types`);
+    if (Object.keys(snapshotComponents).length > 0) {
+      console.log(`✓ Loaded ${Object.keys(snapshotComponents).length} components`);
+    }
+    if (Object.keys(groupedObjects).length === 0) {
+      console.log('⚠️  Snapshot has no content types.');
+      process.exit(0);
+    }
+  } catch (error) {
+    logCliError('❌', error.message);
+    process.exit(1);
+  }
+
+  console.log('📥 Fetching content types and entries from Strapi...');
+  const { apiTypes, existingSchemas, existingEntriesByType, apiIdByType } = await fetchStrapiState(
+    client,
+    groupedObjects
+  );
+  console.log('✓ Fetched\n');
+
+  const { schemaChangesByType, contentChangesByType, localizationChangesByType, singleTypeChangesByType } = computeChangeMaps(
+    groupedObjects,
+    snapshotContentTypes,
+    existingSchemas,
+    existingEntriesByType,
+    getContentTypeId
+  );
+  const onlyInStrapiContentTypes = apiTypes.map(getContentTypeId).filter((ct) => !(ct in groupedObjects));
+  const schemaUpdater = options.updateSchema && getSchemaUpdater(options);
+  let componentChanges = {
+    onlyInStrapiComponents: [],
+    onlyInSnapshotComponents: [],
+    componentSchemaChangesByUid: new Map()
+  };
+  try {
+    componentChanges = await computeComponentChanges(client, snapshotComponents, Boolean(schemaUpdater));
+  } catch (_) {}
+  const previewCounts = getPreviewCounts(
+    groupedObjects,
+    schemaChangesByType,
+    contentChangesByType,
+    onlyInStrapiContentTypes,
+    componentChanges,
+    Boolean(schemaUpdater)
+  );
+
+  if (previewCounts.detected > 0) {
+    printPreview(
+      groupedObjects,
+      snapshotContentTypes,
+      existingSchemas,
+      existingEntriesByType,
+      onlyInStrapiContentTypes,
+      schemaChangesByType,
+      contentChangesByType,
+      contentTypeDisplayName,
+      formatContentForLog,
+      componentChanges.onlyInStrapiComponents,
+      componentChanges.onlyInSnapshotComponents,
+      componentChanges.componentSchemaChangesByUid,
+      localizationChangesByType,
+      singleTypeChangesByType
+    );
+  }
+
+  getNonActionableNotes(
+    groupedObjects,
+    schemaChangesByType,
+    onlyInStrapiContentTypes,
+    componentChanges,
+    Boolean(schemaUpdater)
+  ).forEach((note) => console.log(`ℹ️  ${note}`));
+
+  if (previewCounts.actionable === 0) {
+    console.log('No actionable changes to apply.\n');
+    process.exit(0);
+  }
+
+  const confirmed = await askConfirmation('Proceed with actionable changes? (y/N) ');
+  if (!confirmed) {
+    console.log('Aborted.');
+    process.exit(0);
+  }
+  console.log('');
+
+  const schemaWasUpdated = await applySchemaChanges({
+    schemaUpdater,
+    snapshotComponents,
+    snapshotContentTypes,
+    onlyInSnapshotComponents: componentChanges.onlyInSnapshotComponents,
+    componentSchemaChangesByUid: componentChanges.componentSchemaChangesByUid,
+    schemaChangesByType,
+    localizationChangesByType,
+    singleTypeChangesByType,
+    existingSchemas,
+    onlyInStrapiContentTypes,
+    onlyInStrapiComponents: componentChanges.onlyInStrapiComponents
+  });
+
+  if (schemaWasUpdated) {
+    const ready = await waitForStrapiReload(client, options);
+    if (!ready) {
+      console.log('\n✅ Done (schema only).');
+      process.exit(0);
+    }
+    console.log('');
+  }
+
+  let activeSchemas = existingSchemas;
+  let activeEntriesByType = existingEntriesByType;
+  let activeApiIdByType = apiIdByType;
+  let activeContentChangesByType = contentChangesByType;
+
+  if (schemaWasUpdated) {
+    try {
+      const refetched = await fetchStrapiState(client, groupedObjects);
+      activeSchemas = refetched.existingSchemas;
+      activeEntriesByType = refetched.existingEntriesByType;
+      activeApiIdByType = refetched.apiIdByType;
+      const recomputed = computeChangeMaps(
+        groupedObjects,
+        snapshotContentTypes,
+        activeSchemas,
+        activeEntriesByType,
+        getContentTypeId
+      );
+      activeContentChangesByType = recomputed.contentChangesByType;
+    } catch (_) {}
+  }
+
+  const changesApplied = await applyContentChanges(
+    client,
+    groupedObjects,
+    snapshotContentTypes,
+    activeSchemas,
+    activeEntriesByType,
+    activeApiIdByType,
+    activeContentChangesByType,
+    schemaChangesByType
+  );
+
+  if (snapshotPath && (changesApplied || schemaWasUpdated)) {
+    console.log('\n📤 Updating snapshot from Strapi...');
+    await exportSnapshot(client, snapshotPath);
+    console.log(`✓ Snapshot updated: ${snapshotPath}`);
+  }
+
+  console.log('\n✅ Done.');
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('❌', error.message);
+    process.exit(1);
+  });
+}

package/index.js

@@ -0,0 +1,5 @@
+const { StrapiSyncClient } = require('./lib/strapi-client');
+
+module.exports = {
+  StrapiSyncClient
+};

package/lib/async.js

@@ -0,0 +1,22 @@
+async function mapWithConcurrency(items, limit, iteratee) {
+  const list = Array.isArray(items) ? items : [];
+  const size = Math.max(1, Number(limit) || 1);
+  const results = new Array(list.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < list.length) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+      results[currentIndex] = await iteratee(list[currentIndex], currentIndex);
+    }
+  }
+
+  const workerCount = Math.min(size, list.length || 1);
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  return results;
+}
+
+module.exports = {
+  mapWithConcurrency
+};