@truewatchtech/cocos-sdk 0.1.0-alpha.4 → 0.1.0-alpha.7

package/extensions/creator2/managed-assets.cjs

@@ -0,0 +1,67 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const legacyHashes = new Set(require('./legacy-asset-hashes.json'));
+// Older combined installations predate the ownership manifest. Never leave a
+// locally modified obsolete Replay bridge compiling beside the new bridge.
+const legacyReplayNames = new Set(['FTCocosReplayImageJobs.java', 'FTCocosReplayImageJobs.h', 'FTCocosReplayImageJobs.m', 'FTReplayFileBridge.h', 'FTReplayFileWorker.h']);
+const manifestName = '.cocos-sdk-managed.json';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function files(root) {
+  const result = [];
+  if (!fs.existsSync(root)) return result;
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === manifestName || entry.name === '.DS_Store') continue;
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`[cocos-sdk] Refusing to copy symbolic link: ${file}`);
+      if (entry.isDirectory()) visit(file);
+      else result.push(path.relative(root, file).split(path.sep).join('/'));
+    }
+  }
+  visit(root);
+  return result;
+}
+
+/** Reconciles only files written by the SDK, preserving unrelated project assets. */
+function syncManagedDirectory(destination, sources, overrides = {}) {
+  const desired = new Map();
+  for (const { root, prefix = '' } of sources) {
+    if (!fs.existsSync(root)) throw new Error(`[cocos-sdk] Missing package assets: ${root}`);
+    for (const file of files(root)) desired.set(prefix + file, fs.readFileSync(path.join(root, file)));
+  }
+  for (const [file, content] of Object.entries(overrides)) desired.set(file, Buffer.from(content));
+  const manifest = path.join(destination, manifestName);
+  const previous = fs.existsSync(manifest) ? JSON.parse(fs.readFileSync(manifest, 'utf8')) : {};
+  const existing = files(destination);
+  const remove = [];
+  // Check every conflict before writing or deleting any managed file.
+  for (const file of existing) {
+    const digest = hash(fs.readFileSync(path.join(destination, file)));
+    const old = previous[file];
+    const next = desired.get(file);
+    const legacy = legacyHashes.has(digest);
+    if (!next && !old && !legacy && legacyReplayNames.has(path.basename(file))) {
+      throw new Error(`[cocos-sdk] Preserve or reconcile modified legacy Replay asset before reinstalling: ${path.join(destination, file)}`);
+    }
+    if ((old || next) && digest !== old && !legacy && (!next || digest !== hash(next))) {
+      throw new Error(`[cocos-sdk] Preserve or reconcile modified SDK asset before reinstalling: ${path.join(destination, file)}`);
+    }
+    if (!next && (old || legacy) && !file.endsWith('.meta')) remove.push(file);
+  }
+  fs.mkdirSync(destination, { recursive: true });
+  for (const file of remove) fs.unlinkSync(path.join(destination, file));
+  const nextManifest = {};
+  for (const [file, content] of desired) {
+    const target = path.resolve(destination, file);
+    if (!target.startsWith(path.resolve(destination) + path.sep)) throw new Error('Invalid SDK asset path');
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (!fs.existsSync(target) || hash(fs.readFileSync(target)) !== hash(content)) fs.writeFileSync(target, content);
+    nextManifest[file] = hash(content);
+  }
+  fs.writeFileSync(manifest, `${JSON.stringify(nextManifest, null, 2)}\n`);
+}
+
+module.exports = { syncManagedDirectory };

package/extensions/creator3/install-native.cjs

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { syncManagedDirectory } = require('./managed-assets.cjs');
 
 const BEGIN = '/* COCOS_SDK_BEGIN */';
 const END = '/* COCOS_SDK_END */';
@@ -22,19 +23,38 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   buildRoot = path.resolve(buildRoot);
   extensionRoot = path.resolve(extensionRoot);
   if (!fs.existsSync(buildRoot)) return;
+  const dependencyManager = readIosDependencyManager(buildRoot, extensionRoot);
   const nativeSource = path.join(extensionRoot, 'native');
   if (!fs.existsSync(nativeSource)) {
     logger.warn(`[cocos-sdk] Native bridge not found at ${nativeSource}`);
     return;
   }
+  const replayDescriptor = path.join(extensionRoot, 'replay-integration.json');
+  const replay = fs.existsSync(replayDescriptor) ? JSON.parse(fs.readFileSync(replayDescriptor, 'utf8')) : null;
+  const installedFile = path.join(extensionRoot, 'sdk-integration.json');
+  const installed = fs.existsSync(installedFile) ? JSON.parse(fs.readFileSync(installedFile, 'utf8')) : null;
+  if (installed?.replay && !replay) throw new Error('[cocos-sdk] Replay assets are missing. Run truewatch-cocos install --replay.');
+  if (replay && (replay.schemaVersion !== 1 || !installed || replay.baseVersion !== installed.version || replay.version !== installed.version || replay.iosSdkVersion !== '1.6.8-alpha.5')) {
+    throw new Error('[cocos-sdk] Replay native integration version does not match the base SDK. Reinstall matching packages.');
+  }
+  const replaySource = path.join(extensionRoot, 'replay-native');
   const buildNative = path.join(buildRoot, 'cocos-sdk-native');
-  copyDirectory(nativeSource, buildNative);
-  const files = findFiles(buildRoot, 7);
-  const replayHeader = path.join(buildNative, 'shared', 'FTReplayFileBridge.h');
-  if (fs.existsSync(replayHeader)) {
-    findReplayEntryFiles(files)
-      .forEach((file) => patchReplayFileBridge(file, replayHeader));
+  const sources = [{ root: nativeSource }];
+  if (replay) sources.push({ root: replaySource, prefix: 'replay/' });
+  if (dependencyManager === 'spm') {
+    sources.push({ root: path.join(nativeSource, 'ios'), prefix: 'FTCocosBridge/' });
+    if (replay) sources.push({ root: path.join(replaySource, 'ios'), prefix: 'FTCocosReplayBridge/' });
   }
+  const modules = 'android/src/main/java/com/ft/sdk/cocos/FTCocosBridgeModules.java';
+  const dispatcher = fs.readFileSync(path.join(nativeSource, modules), 'utf8');
+  const configuredDispatcher = replay ? dispatcher.replace(
+    '        return "{',
+    '        if ("session-replay".equals(endpoint)) return FTCocosReplayBridge.invokeLocal(method, payload);\n        return "{',
+  ) : dispatcher;
+  syncManagedDirectory(buildNative, sources, { [modules]: configuredDispatcher });
+  const files = findFiles(buildRoot, 7);
+  const replayHeader = replay ? path.join(buildNative, 'replay', 'shared', 'FTReplayFileBridge.h') : null;
+  findReplayEntryFiles(files).forEach(file => patchReplayFileBridge(file, replayHeader));
   const gradlePropertiesFiles = files.filter((file) => path.basename(file) === 'gradle.properties');
   const gradleFiles = uniqueFiles([
     ...files.filter((file) => /(?:^|\/)app\/build\.gradle$/.test(normalize(file))),
@@ -47,7 +67,10 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   const iosApplicationProjects = xcodeProjects
     .map((projectFile) => ({ projectFile, target: findIosApplicationTarget(projectFile) }))
     .filter((project) => project.target);
-  if (podfiles.length === 0) {
+  if (dependencyManager === 'spm' && iosApplicationProjects.length > 0) {
+    migrateManagedPods(podfiles, logger);
+  }
+  if (dependencyManager === 'cocoapods' && podfiles.length === 0) {
     iosApplicationProjects.forEach(({ projectFile, target }) => {
       const projectDirectory = path.dirname(path.dirname(projectFile));
       const podfile = path.join(projectDirectory, 'Podfile');
@@ -57,12 +80,21 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   }
   iosApplicationProjects.forEach(({ projectFile, target }) => {
     patchCocos2IosConfiguration(projectFile, target);
+    if (dependencyManager === 'spm') {
+      const spm = require('./install-spm.cjs');
+      if (!replay) spm.removeSwiftPackages(projectFile, ['FTCocosReplayBridge']);
+      spm.installSwiftPackage(projectFile, path.join(buildNative, 'FTCocosBridge'), 'FTCocosBridge', target);
+      if (replay) spm.installSwiftPackage(projectFile, path.join(buildNative, 'FTCocosReplayBridge'), 'FTCocosReplayBridge', target);
+    } else if (fs.readFileSync(projectFile, 'utf8').includes('XCLocalSwiftPackageReference')
+      || fs.existsSync(path.join(path.dirname(projectFile), 'cocos-sdk-spm.json'))) {
+      require('./install-spm.cjs').removeSwiftPackages(projectFile);
+    }
   });
-  gradleFiles.forEach((file) => patchGradle(file, buildNative));
+  gradleFiles.forEach((file) => patchGradle(file, buildNative, replay));
   gradlePropertiesFiles.forEach(patchGradleProperties);
-  podfiles.forEach((file) => patchPodfile(file, buildNative));
+  if (dependencyManager === 'cocoapods') podfiles.forEach((file) => patchPodfile(file, buildNative, replay));
   logger.info(
-    `[cocos-sdk] Installed native bridge (${gradleFiles.length} Android, ${podfiles.length} iOS project files).`,
+    `[cocos-sdk] Installed native bridge (${gradleFiles.length} Android, ${dependencyManager === 'spm' ? iosApplicationProjects.length : podfiles.length} iOS project files; iOS: ${dependencyManager}).`,
   );
 }
 
@@ -75,6 +107,12 @@ function patchReplayFileBridge(file, header) {
   // Creator 3 shares Game.cpp across iOS/Android builds. Keep its include stable
   // when another platform's build directory is cleaned or regenerated.
   const sharedDirectory = path.join(path.dirname(file), 'cocos-sdk-replay');
+  if (!header) {
+    const next = original.replace(markedPattern(includeBegin, includeEnd), '').replace(markedPattern(initBegin, initEnd), '');
+    if (fs.existsSync(sharedDirectory)) syncManagedDirectory(sharedDirectory, []);
+    if (next !== original) fs.writeFileSync(file, next);
+    return;
+  }
   const include = `${includeBegin}\n#include "cocos-sdk-replay/FTReplayFileBridge.h"\n${includeEnd}`;
   const init = `${initBegin}\n    ft_cocos::installReplayFileBridge();\n    ${initEnd}\n    `;
   let next = original;
@@ -90,7 +128,7 @@ function patchReplayFileBridge(file, header) {
   next = markedPattern(includeBegin, includeEnd).test(next)
     ? next.replace(markedPattern(includeBegin, includeEnd), include)
     : `${include}\n${next}`;
-  copyDirectory(path.dirname(header), sharedDirectory);
+  syncManagedDirectory(sharedDirectory, [{ root: path.dirname(header) }]);
   if (next !== original) fs.writeFileSync(file, next);
 }
 
@@ -241,34 +279,37 @@ function compareVersions(left, right) {
   return 0;
 }
 
-function patchGradle(file, nativeRoot) {
+function patchGradle(file, nativeRoot, replay) {
   const javaDir = normalize(path.join(nativeRoot, 'android', 'src', 'main', 'java'));
+  const javaDirs = [javaDir];
+  if (replay) javaDirs.push(normalize(path.join(nativeRoot, 'replay', 'android', 'src', 'main', 'java')));
   replaceMarkedBlock(file, [
     BEGIN,
     'android {',
-    `    sourceSets { main.java.srcDirs += ['${escapeGroovy(javaDir)}'] }`,
+    `    sourceSets { main.java.srcDirs += [${javaDirs.map(dir => `'${escapeGroovy(dir)}'`).join(', ')}] }`,
     '}',
     'repositories {',
     "    maven { url 'https://mvnrepo.truewatch.com/repository/maven-releases' }",
     '}',
     'dependencies {',
-    "    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-sdk:1.7.6-alpha02'",
+    "    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-sdk:1.7.6-alpha03'",
     "    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-native:1.1.3'",
-    "    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-session-replay:0.1.9-alpha03'",
+    ...(replay ? [`    implementation '${escapeGroovy(replay.androidReplay)}'`] : []),
     "    implementation 'com.google.code.gson:gson:2.10.1'",
     "    implementation platform('org.jetbrains.kotlin:kotlin-bom:1.8.22')",
     "    implementation 'androidx.appcompat:appcompat:1.1.0'",
-    "    implementation 'androidx.fragment:fragment:1.8.0'",
+    ...(replay ? [`    implementation '${escapeGroovy(replay.androidFragment)}'`] : []),
     '}',
     END,
   ].join('\n'), BEGIN, END, [[LEGACY_BEGIN, LEGACY_END]]);
 }
 
-function patchPodfile(file, nativeRoot) {
+function patchPodfile(file, nativeRoot, replay) {
   const iosDir = normalize(path.join(nativeRoot, 'ios'));
   const block = [
     POD_BEGIN,
     `pod 'FTCocosBridge', :path => '${escapeRuby(iosDir)}'`,
+    ...(replay ? [`pod 'FTCocosReplayBridge', :path => '${escapeRuby(normalize(path.join(nativeRoot, 'replay', 'ios')))}'`] : []),
     POD_END,
   ].join('\n');
   const original = fs.readFileSync(file, 'utf8');
@@ -298,6 +339,11 @@ function replaceIndentedMarkedBlock(contents, begin, end, block) {
 
 function findIosApplicationTarget(projectFile) {
   const contents = fs.readFileSync(projectFile, 'utf8');
+  if (contents.includes('COCOS_SDK_XCODE_PROJECT')
+    || fs.existsSync(path.join(path.dirname(projectFile), 'cocos-sdk-spm.json'))) {
+    const { readProject, applicationTarget } = require('./install-spm.cjs');
+    return applicationTarget(readProject(projectFile))?.[1].name || null;
+  }
   const nativeTarget = /\/\* ([^*]+) \*\/ = \{\s*isa = PBXNativeTarget;([\s\S]*?)\n\s*\};/g;
   const targets = [];
   let match;
@@ -352,16 +398,6 @@ function markedPattern(begin, end) {
   return new RegExp(`${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}`, 'm');
 }
 
-function copyDirectory(source, destination) {
-  fs.mkdirSync(destination, { recursive: true });
-  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-    const from = path.join(source, entry.name);
-    const to = path.join(destination, entry.name);
-    if (entry.isDirectory()) copyDirectory(from, to);
-    else fs.copyFileSync(from, to);
-  }
-}
-
 function findFiles(root, maxDepth) {
   const result = [];
   function visit(directory, depth) {
@@ -382,4 +418,58 @@ function escapeGroovy(value) { return value.replace(/\\/g, '\\\\').replace(/'/g,
 function escapeRuby(value) { return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'"); }
 function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 
-module.exports = { installNative };
+function readIosDependencyManager(buildRoot, extensionRoot) {
+  for (const start of [buildRoot, extensionRoot]) {
+    let directory = path.resolve(start);
+    while (true) {
+      const file = path.join(directory, 'cocos-sdk.config.json');
+      if (fs.existsSync(file)) {
+        const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const manager = config.ios?.dependencyManager ?? 'cocoapods';
+        if (!['spm', 'cocoapods'].includes(manager)) {
+          throw new Error(`[cocos-sdk] Invalid ios.dependencyManager in ${file}: expected spm or cocoapods.`);
+        }
+        return manager;
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return 'cocoapods';
+}
+
+function migrateManagedPods(podfiles, logger) {
+  for (const file of podfiles) {
+    const original = fs.readFileSync(file, 'utf8');
+    let next = original;
+    for (const [begin, end] of [
+      [POD_BEGIN, POD_END], [LEGACY_POD_BEGIN, LEGACY_POD_END], [LEGACY_BEGIN, LEGACY_END],
+      ['# COCOS_HYBRID_SAMPLE_BEGIN', '# COCOS_HYBRID_SAMPLE_END'],
+    ]) next = next.replace(markedPattern(begin, end), '');
+    if (/^\s*pod\s+['"](?:FTCocosBridge|FTCocosReplayBridge|HybridSampleHost|TrueWatchSDK)(?:\/[^'"]*)?['"]/m.test(next)) {
+      throw new Error(`[cocos-sdk] Remove the manually declared native SDK Pod from ${file} before switching to SPM.`);
+    }
+    if (next !== original) fs.writeFileSync(file, next);
+    const directory = path.dirname(file);
+    const existingLock = path.join(directory, 'Podfile.lock');
+    const hasSDKPods = fs.existsSync(existingLock)
+      && /^\s*- (?:FTCocosBridge|FTCocosReplayBridge|HybridSampleHost|TrueWatchSDK)(?:\/|\s|:)/m.test(fs.readFileSync(existingLock, 'utf8'));
+    if (next === original && !hasSDKPods) continue;
+    if (fs.existsSync(path.join(directory, 'Podfile.lock')) || fs.existsSync(path.join(directory, 'Pods'))) {
+      logger.info('[cocos-sdk] Updating existing Pods integration for the SPM switch.');
+      try {
+        execFileSync('pod', ['install'], { cwd: directory, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
+      } catch (error) {
+        fs.writeFileSync(file, original);
+        throw new Error(`[cocos-sdk] Unable to update existing Pods in ${directory}: ${error.message}`);
+      }
+      const lock = path.join(directory, 'Podfile.lock');
+      if (fs.existsSync(lock) && /^\s*- TrueWatchSDK(?:\/|\s|:)/m.test(fs.readFileSync(lock, 'utf8'))) {
+        throw new Error(`[cocos-sdk] Another Pod still depends on the native SDK in ${lock}; migrate that dependency before using SPM.`);
+      }
+    }
+  }
+}
+
+module.exports = { installNative, readIosDependencyManager };

package/extensions/creator3/install-spm.cjs

@@ -0,0 +1,198 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const { execFileSync } = require('child_process');
+
+function readProject(file) {
+  // plutil understands both Xcode's OpenStep format and XML plists, without Ruby/gems.
+  return JSON.parse(execFileSync('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file], {
+    encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  }));
+}
+
+function writeProject(file, project) {
+  const next = `// !$*UTF8*$!\n// COCOS_SDK_XCODE_PROJECT\n${serialize(project)}\n`;
+  if (fs.readFileSync(file, 'utf8') !== next) fs.writeFileSync(file, next);
+}
+
+function serialize(value, depth = 0) {
+  const indent = '\t'.repeat(depth);
+  if (Array.isArray(value)) {
+    return `(\n${value.map((entry) => `${indent}\t${serialize(entry, depth + 1)},\n`).join('')}${indent})`;
+  }
+  if (value && typeof value === 'object') {
+    return `{\n${Object.entries(value).sort(([a], [b]) => a === 'isa' ? -1 : b === 'isa' ? 1 : a.localeCompare(b)).map(([key, entry]) => (
+      `${indent}\t${serialize(key)} = ${serialize(entry, depth + 1)};\n`
+    )).join('')}${indent}}`;
+  }
+  const text = String(value);
+  return /^[A-Za-z0-9_./]+$/.test(text) ? text : JSON.stringify(text);
+}
+
+function applicationTarget(project, preferredName) {
+  const targets = Object.entries(project.objects).filter(([, object]) => (
+    object.isa === 'PBXNativeTarget' && object.productType === 'com.apple.product-type.application'
+  ));
+  return targets.find(([, object]) => object.name === preferredName)
+    || targets.find(([, object]) => /(?:^|[-_.])(?:mobile|ios)$/i.test(object.name))
+    || targets[0];
+}
+
+function add(list, value) {
+  if (!list.includes(value)) list.push(value);
+}
+
+function identifier(value) {
+  return createHash('sha256').update(`cocos-sdk:${value}`).digest('hex').slice(0, 24).toUpperCase();
+}
+
+function installSwiftPackage(projectFile, packageDirectory, productName, targetName) {
+  if (!fs.existsSync(path.join(packageDirectory, 'Package.swift'))) {
+    throw new Error(`[cocos-sdk] Missing Swift package: ${packageDirectory}`);
+  }
+  const project = readProject(projectFile);
+  const selected = applicationTarget(project, targetName);
+  if (!selected) throw new Error(`[cocos-sdk] No application target in ${projectFile}`);
+  const [targetID, target] = selected;
+  const objects = project.objects;
+  const root = objects[project.rootObject];
+  const projectDirectory = path.resolve(path.dirname(path.dirname(projectFile)), root.projectDirPath || '.');
+  const relativePath = path.relative(projectDirectory, packageDirectory).split(path.sep).join('/');
+  const packageID = identifier(`package:${productName}`);
+  const productID = identifier(`product:${targetID}:${productName}`);
+  const buildID = identifier(`framework:${targetID}:${productName}`);
+  const existing = (target.packageProductDependencies || []).find((id) => (
+    id !== productID && objects[id]?.productName === productName
+  ));
+  if (existing) throw new Error(`[cocos-sdk] ${productName} is already managed manually in ${target.name}; remove that reference before automatic installation.`);
+
+  objects[packageID] = { isa: 'XCLocalSwiftPackageReference', relativePath };
+  objects[productID] = { isa: 'XCSwiftPackageProductDependency', productName };
+  objects[buildID] = { isa: 'PBXBuildFile', productRef: productID };
+  add(root.packageReferences ||= [], packageID);
+  add(target.packageProductDependencies ||= [], productID);
+  let phaseID = (target.buildPhases || []).find((id) => objects[id]?.isa === 'PBXFrameworksBuildPhase');
+  if (!phaseID) {
+    phaseID = identifier(`frameworks:${targetID}`);
+    objects[phaseID] = { isa: 'PBXFrameworksBuildPhase', buildActionMask: '2147483647', files: [], runOnlyForDeploymentPostprocessing: '0' };
+    add(target.buildPhases ||= [], phaseID);
+  }
+  add(objects[phaseID].files ||= [], buildID);
+  const configurations = objects[target.buildConfigurationList]?.buildConfigurations || [];
+  for (const configID of configurations) {
+    const settings = objects[configID].buildSettings ||= {};
+    const flags = settings.OTHER_LDFLAGS;
+    if (Array.isArray(flags)) {
+      add(flags, '$(inherited)');
+      add(flags, '-ObjC');
+    } else {
+      const parts = [flags || '$(inherited)'];
+      if (!String(flags || '').includes('$(inherited)')) add(parts, '$(inherited)');
+      if (!/(?:^|\s)-ObjC(?:\s|$)/.test(flags || '')) add(parts, '-ObjC');
+      settings.OTHER_LDFLAGS = parts.join(' ');
+    }
+    if (Number(settings.IPHONEOS_DEPLOYMENT_TARGET || 0) < 12) settings.IPHONEOS_DEPLOYMENT_TARGET = '12.0';
+    settings.CLANG_ENABLE_MODULES = 'YES';
+  }
+  preserveCmakeIntegration(projectFile, project, { packageDirectory, productName, targetName: target.name });
+  writeProject(projectFile, project);
+}
+
+const RESTORE_BEGIN = '# COCOS_SDK_SPM_RESTORE_BEGIN';
+const RESTORE_END = '# COCOS_SDK_SPM_RESTORE_END';
+const restorePattern = /\n?# COCOS_SDK_SPM_RESTORE_BEGIN[\s\S]*?# COCOS_SDK_SPM_RESTORE_END\n?/g;
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function preserveCmakeIntegration(projectFile, project, entry) {
+  const objects = project.objects;
+  const zeroCheck = Object.values(objects).find((object) => object.name === 'ZERO_CHECK');
+  if (!zeroCheck) return;
+  // CMake's SYMROOT/OBJROOT overrides select Xcode's legacy build locations,
+  // which reject packages. Keep CONFIGURATION_BUILD_DIR (engine archives).
+  const stateFile = path.join(path.dirname(projectFile), 'cocos-sdk-spm.json');
+  const state = fs.existsSync(stateFile)
+    ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : { packages: [], buildLocations: {} };
+  for (const [id, object] of Object.entries(objects)) {
+    if (object.isa !== 'XCBuildConfiguration') continue;
+    for (const key of ['SYMROOT', 'OBJROOT']) {
+      if (object.buildSettings?.[key] === undefined) continue;
+      (state.buildLocations[id] ||= {})[key] = object.buildSettings[key];
+      delete object.buildSettings[key];
+    }
+  }
+  const relativeDirectory = path.relative(path.dirname(projectFile), entry.packageDirectory);
+  state.packages = state.packages.filter((item) => item.productName !== entry.productName);
+  state.packages.push({ ...entry, packageDirectory: relativeDirectory });
+  state.packages.sort((a, b) => a.productName.localeCompare(b.productName));
+  const helper = path.join(path.dirname(projectFile), 'cocos-sdk-spm.cjs');
+  if (path.resolve(helper) !== path.resolve(__filename)) fs.copyFileSync(__filename, helper);
+  const restore = [
+    RESTORE_BEGIN,
+    `${process.versions.electron ? 'ELECTRON_RUN_AS_NODE=1 ' : ''}${shellQuote(process.execPath)} ${shellQuote(helper)} --restore`,
+    RESTORE_END,
+  ].join('\n');
+  for (const id of zeroCheck.buildPhases || []) {
+    const phase = objects[id];
+    if (phase?.isa !== 'PBXShellScriptBuildPhase') continue;
+    phase.shellScript = `${(phase.shellScript || '').replace(restorePattern, '').trimEnd()}\n${restore}\n`;
+  }
+  const serialized = `${JSON.stringify(state, null, 2)}\n`;
+  if (!fs.existsSync(stateFile) || fs.readFileSync(stateFile, 'utf8') !== serialized) fs.writeFileSync(stateFile, serialized);
+}
+
+function removeSwiftPackages(projectFile, productNames = ['FTCocosBridge', 'FTCocosReplayBridge', 'HybridSampleHost']) {
+  const project = readProject(projectFile);
+  const objects = project.objects;
+  const removed = new Set();
+  for (const productName of productNames) {
+    const packageID = identifier(`package:${productName}`);
+    if (!objects[packageID]) continue;
+    removed.add(packageID);
+    for (const [id, object] of Object.entries(objects)) {
+      if (object.isa !== 'PBXNativeTarget') continue;
+      removed.add(identifier(`product:${id}:${productName}`));
+      removed.add(identifier(`framework:${id}:${productName}`));
+    }
+  }
+  for (const id of removed) delete objects[id];
+  for (const object of Object.values(objects)) {
+    for (const key of ['packageReferences', 'packageProductDependencies', 'files']) {
+      if (Array.isArray(object[key])) object[key] = object[key].filter((id) => !removed.has(id));
+    }
+
+  }
+  const stateFile = path.join(path.dirname(projectFile), 'cocos-sdk-spm.json');
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    state.packages = state.packages.filter(item => !productNames.includes(item.productName));
+    if (state.packages.length) {
+      fs.writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`);
+    } else {
+      for (const [id, settings] of Object.entries(state.buildLocations)) {
+        if (objects[id]) Object.assign(objects[id].buildSettings ||= {}, settings);
+      }
+      for (const object of Object.values(objects)) {
+        if (object.isa === 'PBXShellScriptBuildPhase') object.shellScript = (object.shellScript || '').replace(restorePattern, '');
+      }
+      fs.unlinkSync(stateFile);
+      fs.rmSync(path.join(path.dirname(projectFile), 'cocos-sdk-spm.cjs'), { force: true });
+    }
+  }
+
+  writeProject(projectFile, project);
+}
+
+module.exports = { installSwiftPackage, removeSwiftPackages, readProject, applicationTarget };
+
+if (require.main === module && process.argv[2] === '--restore') {
+  const directory = path.dirname(__filename);
+  const state = JSON.parse(fs.readFileSync(path.join(directory, 'cocos-sdk-spm.json'), 'utf8'));
+  for (const item of state.packages) {
+    installSwiftPackage(path.join(directory, 'project.pbxproj'), path.resolve(directory, item.packageDirectory), item.productName, item.targetName);
+  }
+}

package/extensions/creator3/legacy-asset-hashes.json

@@ -0,0 +1,32 @@
+[
+  "058341971ed42ddfde76c28ce19fcc0bba5020fec1f7e1c613c7bda7d2df7677",
+  "11ee16e609096ccfe90b17f61d87ab65275a39df4bef6f8c29577e7395aa00f8",
+  "15338071a78f1505265cc8efbdc9628e9362f7a2c9fc00989d57461126f8f3f5",
+  "1a51af27d68cdf0bf3ce709c9cd60f9b8a2d7defd46d06896ce9a916e1dfc767",
+  "2caa0d3d542f5cca0b6b7f3aa2851c7e296b08fce286202a844b52920b1f6dc0",
+  "3189144de638b936e14d64ddbf9d4c95e95146ceecc357021473ca8adcc757d1",
+  "48ff77a12a7b9b59172f5470a642f23e4c61e9f7e10ee6d9d3f4f41377d696ac",
+  "4d2dcd924f1073b8a6fb94d342bee33a281f93c19302104be172e5de9981b3f0",
+  "51c71e12df61cfe7e75c3d97080e31a398fbea8719a3e964cec5dd332df1202c",
+  "54340b775f6ba897ade2df2d9fcfc39d17372e246e951d77dd166f00265815a8",
+  "5f33108f27f38836214f2c11badd7bb76ba9ec090f9d5b1490834a9257976939",
+  "71e6ade990a65d1bec51fec02c94bfe804e591d47df7ed9a271c981e9cf1d71c",
+  "83df7e51a5e4f76aab6310870c665fc80334808c64fb9c92fee46b466e1b58c3",
+  "85ad9622480d954c33a4f9442a391f6d3d9d617a2f1261e5ad769170c6e9cf12",
+  "86cf732195aad676898520192ac8aa878267877dc09f85fcf425279d8badc9b8",
+  "910792f383c25cd46ddc7d851080a687fa532a93d605fb709b7baff9bb2789cf",
+  "95bdc516c4e1b72833af3bec13b18e3c2ac6ae83de284c3f711e97765ed1b461",
+  "a748564f0bba03effbf4aa381308f60eedcb618cbd2a37e1c67cdbee596e9ceb",
+  "a8a57b5892e7a5063078d561fce790b44d900d2bb3869e43ed4c4de82f1f62ed",
+  "cd03df57f7861d19b0a8e0a97e8aff1fa08e5c26d4f43152743968245632535b",
+  "d26fb42c6bee416eaf29bc2ed8579edc7a28ca3d0e18433dcb8abea11fac9920",
+  "d2d171e4ef1777facdb6fe665105372ea2e6452028d4c32f5e2ccc74dacc8850",
+  "d538d9eebaf181687ebf8537fc6ce7c8fae59fa424daeb45c3f900a8e210ecfc",
+  "d6c2cefddabd773d471138aad619ee9f90d0f39f18053efa4d43d8771668e410",
+  "df0be5a293b5259b02438e2555832a114548fed03ecdde5b80bbc621c800998d",
+  "df8e3014e583d60922cd1b7f7f16964c433b260a7e1a7e6c285cb08ce2d9e7e4",
+  "e70ca2a537cec56f8424ff4d551c1e97af133938fc7ba863a3944859dcfd194d",
+  "f0211acbaaa312bd5a4478bba81fa98293c855692ceca69f141600ff991c5904",
+  "f09f9b35ddfb17a7c4e4439384afae93ded6ee0285e778ad013d320cfc880cab",
+  "fa88198c5434613ff5ab2d44dce6e7eb8b825085b5b498402810eb144cf81f96"
+]

package/extensions/creator3/managed-assets.cjs

@@ -0,0 +1,67 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const legacyHashes = new Set(require('./legacy-asset-hashes.json'));
+// Older combined installations predate the ownership manifest. Never leave a
+// locally modified obsolete Replay bridge compiling beside the new bridge.
+const legacyReplayNames = new Set(['FTCocosReplayImageJobs.java', 'FTCocosReplayImageJobs.h', 'FTCocosReplayImageJobs.m', 'FTReplayFileBridge.h', 'FTReplayFileWorker.h']);
+const manifestName = '.cocos-sdk-managed.json';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function files(root) {
+  const result = [];
+  if (!fs.existsSync(root)) return result;
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === manifestName || entry.name === '.DS_Store') continue;
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`[cocos-sdk] Refusing to copy symbolic link: ${file}`);
+      if (entry.isDirectory()) visit(file);
+      else result.push(path.relative(root, file).split(path.sep).join('/'));
+    }
+  }
+  visit(root);
+  return result;
+}
+
+/** Reconciles only files written by the SDK, preserving unrelated project assets. */
+function syncManagedDirectory(destination, sources, overrides = {}) {
+  const desired = new Map();
+  for (const { root, prefix = '' } of sources) {
+    if (!fs.existsSync(root)) throw new Error(`[cocos-sdk] Missing package assets: ${root}`);
+    for (const file of files(root)) desired.set(prefix + file, fs.readFileSync(path.join(root, file)));
+  }
+  for (const [file, content] of Object.entries(overrides)) desired.set(file, Buffer.from(content));
+  const manifest = path.join(destination, manifestName);
+  const previous = fs.existsSync(manifest) ? JSON.parse(fs.readFileSync(manifest, 'utf8')) : {};
+  const existing = files(destination);
+  const remove = [];
+  // Check every conflict before writing or deleting any managed file.
+  for (const file of existing) {
+    const digest = hash(fs.readFileSync(path.join(destination, file)));
+    const old = previous[file];
+    const next = desired.get(file);
+    const legacy = legacyHashes.has(digest);
+    if (!next && !old && !legacy && legacyReplayNames.has(path.basename(file))) {
+      throw new Error(`[cocos-sdk] Preserve or reconcile modified legacy Replay asset before reinstalling: ${path.join(destination, file)}`);
+    }
+    if ((old || next) && digest !== old && !legacy && (!next || digest !== hash(next))) {
+      throw new Error(`[cocos-sdk] Preserve or reconcile modified SDK asset before reinstalling: ${path.join(destination, file)}`);
+    }
+    if (!next && (old || legacy) && !file.endsWith('.meta')) remove.push(file);
+  }
+  fs.mkdirSync(destination, { recursive: true });
+  for (const file of remove) fs.unlinkSync(path.join(destination, file));
+  const nextManifest = {};
+  for (const [file, content] of desired) {
+    const target = path.resolve(destination, file);
+    if (!target.startsWith(path.resolve(destination) + path.sep)) throw new Error('Invalid SDK asset path');
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (!fs.existsSync(target) || hash(fs.readFileSync(target)) !== hash(content)) fs.writeFileSync(target, content);
+    nextManifest[file] = hash(content);
+  }
+  fs.writeFileSync(manifest, `${JSON.stringify(nextManifest, null, 2)}\n`);
+}
+
+module.exports = { syncManagedDirectory };