scene-capability-engine 3.6.65 → 3.6.67

package/lib/semantic/shared-sync-export.js

@@ -0,0 +1,413 @@
+const path = require('path');
+const crypto = require('crypto');
+const fs = require('fs-extra');
+const {
+  SHARED_LIBRARY_ROOT,
+  resolveSharedLibraryEntryRelativePath,
+  resolveSharedLibraryIndexRelativePath
+} = require('./shared-publication');
+
+const SUPPORTED_TARGET_LIBRARIES = [
+  'experience-library',
+  'ontology-capability-library',
+  'application-library'
+];
+
+const SEMANTIC_SHARED_SYNC_BUNDLE_API_VERSION = 'sce.semantic.shared-sync.bundle/v0.1';
+const SEMANTIC_SHARED_SYNC_INDEX_API_VERSION = 'sce.semantic.shared-sync.index/v0.1';
+const SEMANTIC_SHARED_SYNC_SHARD_API_VERSION = 'sce.semantic.shared-sync.shard/v0.1';
+const SEMANTIC_SHARED_SYNC_RECEIPT_API_VERSION = 'sce.semantic.shared-sync.receipt/v0.1';
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+async function readJsonIfExists(fileSystem, absolutePath, fallback) {
+  if (!await fileSystem.pathExists(absolutePath)) {
+    return fallback;
+  }
+  try {
+    return await fileSystem.readJson(absolutePath);
+  } catch (_error) {
+    return fallback;
+  }
+}
+
+function toProjectRelative(projectPath, targetPath) {
+  return path.relative(projectPath, targetPath).replace(/\\/g, '/');
+}
+
+function hashJson(value) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(value))
+    .digest('hex');
+}
+
+function buildSemanticSharedSyncExportId() {
+  return `sem-sync-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+function resolveSemanticSharedSyncBaseDir(specId = '') {
+  const normalizedSpecId = normalizeString(specId);
+  if (!normalizedSpecId) {
+    return '';
+  }
+  return `.sce/specs/${normalizedSpecId}/sync/semantic-shared`;
+}
+
+function resolveDefaultSemanticSharedSyncBundleOutFile(specId = '') {
+  const baseDir = resolveSemanticSharedSyncBaseDir(specId);
+  if (!baseDir) {
+    return '';
+  }
+  return `${baseDir}/latest.bundle.json`;
+}
+
+function resolveDefaultSemanticSharedSyncIndexOutFile(specId = '') {
+  const baseDir = resolveSemanticSharedSyncBaseDir(specId);
+  if (!baseDir) {
+    return '';
+  }
+  return `${baseDir}/latest.index.json`;
+}
+
+function resolveDefaultSemanticSharedSyncReceiptOutFile(specId = '') {
+  const baseDir = resolveSemanticSharedSyncBaseDir(specId);
+  if (!baseDir) {
+    return '';
+  }
+  return `${baseDir}/latest.receipt.json`;
+}
+
+function resolveDefaultSemanticSharedSyncShardOutFile(specId = '', targetLibrary = '') {
+  const baseDir = resolveSemanticSharedSyncBaseDir(specId);
+  const normalizedLibrary = normalizeString(targetLibrary);
+  if (!baseDir || !normalizedLibrary) {
+    return '';
+  }
+  return `${baseDir}/shards/${normalizedLibrary}.json`;
+}
+
+function deriveSiblingArtifactRelativePaths(bundleOutFile = '') {
+  const normalized = normalizeString(bundleOutFile);
+  if (!normalized) {
+    return {
+      indexFile: '',
+      receiptFile: '',
+      shardDir: ''
+    };
+  }
+  const parsed = path.posix.parse(normalized.replace(/\\/g, '/'));
+  const stem = parsed.name.endsWith('.bundle')
+    ? parsed.name.slice(0, -'.bundle'.length)
+    : parsed.name;
+  return {
+    indexFile: path.posix.join(parsed.dir, `${stem}.index${parsed.ext || '.json'}`),
+    receiptFile: path.posix.join(parsed.dir, `${stem}.receipt${parsed.ext || '.json'}`),
+    shardDir: path.posix.join(parsed.dir, 'shards')
+  };
+}
+
+function inferSpecIdFromEntries(entries = [], fallback = '') {
+  const requestedSpecId = normalizeString(fallback);
+  if (requestedSpecId) {
+    return requestedSpecId;
+  }
+  const candidates = Array.from(new Set(entries
+    .map((entry) => normalizeString(entry && entry.spec_id))
+    .filter(Boolean)));
+  return candidates.length === 1 ? candidates[0] : '';
+}
+
+async function exportSemanticSharedSyncBundle(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const projectId = normalizeString(options.project_id || options.projectId);
+  const specFilter = normalizeString(options.spec_id || options.specId);
+  const lessonId = normalizeString(options.lesson_id || options.lessonId);
+  const capabilityId = normalizeString(options.capability_id || options.capabilityId);
+  const targetLibraryFilter = normalizeString(options.target_library || options.targetLibrary);
+  const limit = normalizeInteger(options.limit, 100);
+  const generatedAt = new Date().toISOString();
+  const exportId = buildSemanticSharedSyncExportId();
+
+  const rootIndexRelativePath = `${SHARED_LIBRARY_ROOT}/index.json`;
+  const rootIndexAbsolutePath = path.join(projectPath, rootIndexRelativePath);
+  const rootIndex = await readJsonIfExists(fileSystem, rootIndexAbsolutePath, {
+    libraries: []
+  });
+  const indexedLibraries = Array.isArray(rootIndex.libraries)
+    ? rootIndex.libraries
+      .map((item) => normalizeString(item && item.target_library))
+      .filter(Boolean)
+    : [];
+  const librariesToScan = targetLibraryFilter
+    ? [targetLibraryFilter]
+    : Array.from(new Set([
+      ...SUPPORTED_TARGET_LIBRARIES,
+      ...indexedLibraries
+    ]));
+
+  const candidateRefs = [];
+  for (const targetLibrary of librariesToScan) {
+    const sourceIndexFile = resolveSharedLibraryIndexRelativePath(targetLibrary);
+    const sourceIndexAbsolutePath = path.join(projectPath, sourceIndexFile);
+    const sourceIndex = await readJsonIfExists(fileSystem, sourceIndexAbsolutePath, {
+      entries: []
+    });
+    const entries = Array.isArray(sourceIndex.entries) ? sourceIndex.entries : [];
+    for (const item of entries) {
+      if (projectId && normalizeString(item.project_id) !== projectId) {
+        continue;
+      }
+      if (specFilter && normalizeString(item.spec_id) !== specFilter) {
+        continue;
+      }
+      if (lessonId && normalizeString(item.lesson_id) !== lessonId) {
+        continue;
+      }
+      if (capabilityId && normalizeString(item.capability_id) !== capabilityId) {
+        continue;
+      }
+      candidateRefs.push({
+        target_library: targetLibrary,
+        source_index_file: sourceIndexFile,
+        capability_id: normalizeString(item.capability_id),
+        lesson_id: normalizeString(item.lesson_id),
+        project_id: normalizeString(item.project_id),
+        scene_id: normalizeString(item.scene_id),
+        spec_id: normalizeString(item.spec_id),
+        published_at: normalizeString(item.published_at),
+        entry_file: normalizeString(item.entry_file)
+      });
+    }
+  }
+
+  candidateRefs.sort((left, right) => {
+    const leftTime = Date.parse(left.published_at || '') || 0;
+    const rightTime = Date.parse(right.published_at || '') || 0;
+    return rightTime - leftTime;
+  });
+
+  const limitedRefs = limit > 0
+    ? candidateRefs.slice(0, limit)
+    : candidateRefs;
+  const exportedEntries = [];
+  const blocked = [];
+
+  for (const reference of limitedRefs) {
+    const entryFile = normalizeString(reference.entry_file)
+      || resolveSharedLibraryEntryRelativePath(reference.target_library, reference.capability_id);
+    if (!entryFile) {
+      blocked.push({
+        capability_id: reference.capability_id || null,
+        lesson_id: reference.lesson_id || null,
+        target_library: reference.target_library || null,
+        reason: 'missing-entry-file'
+      });
+      continue;
+    }
+    const absoluteEntryPath = path.join(projectPath, entryFile);
+    const entry = await readJsonIfExists(fileSystem, absoluteEntryPath, null);
+    if (!entry) {
+      blocked.push({
+        capability_id: reference.capability_id || null,
+        lesson_id: reference.lesson_id || null,
+        target_library: reference.target_library || null,
+        reason: 'entry-not-found',
+        entry_file: entryFile
+      });
+      continue;
+    }
+    exportedEntries.push({
+      ...entry,
+      source_entry_file: entryFile,
+      source_index_file: reference.source_index_file
+    });
+  }
+
+  const resolvedSpecId = inferSpecIdFromEntries(exportedEntries, specFilter);
+  let bundleOutFile = normalizeString(options.out_file || options.outFile);
+  if (!bundleOutFile && resolvedSpecId) {
+    bundleOutFile = resolveDefaultSemanticSharedSyncBundleOutFile(resolvedSpecId);
+  }
+
+  let indexOutFile = '';
+  let receiptOutFile = '';
+  let shardRootDir = '';
+  if (bundleOutFile) {
+    const siblings = deriveSiblingArtifactRelativePaths(bundleOutFile);
+    indexOutFile = siblings.indexFile;
+    receiptOutFile = siblings.receiptFile;
+    shardRootDir = siblings.shardDir;
+  } else if (resolvedSpecId) {
+    indexOutFile = resolveDefaultSemanticSharedSyncIndexOutFile(resolvedSpecId);
+    receiptOutFile = resolveDefaultSemanticSharedSyncReceiptOutFile(resolvedSpecId);
+    shardRootDir = `${resolveSemanticSharedSyncBaseDir(resolvedSpecId)}/shards`;
+  }
+
+  const entriesByLibrary = new Map();
+  for (const entry of exportedEntries) {
+    const targetLibrary = normalizeString(entry.target_library);
+    if (!targetLibrary) {
+      continue;
+    }
+    if (!entriesByLibrary.has(targetLibrary)) {
+      entriesByLibrary.set(targetLibrary, []);
+    }
+    entriesByLibrary.get(targetLibrary).push(entry);
+  }
+
+  const librarySummaries = [];
+  const shardIndex = {};
+  for (const [targetLibrary, entries] of entriesByLibrary.entries()) {
+    const shardEntries = [...entries]
+      .sort((left, right) => {
+        const leftTime = Date.parse(left.published_at || '') || 0;
+        const rightTime = Date.parse(right.published_at || '') || 0;
+        return rightTime - leftTime;
+      });
+    const shardPayload = {
+      api_version: SEMANTIC_SHARED_SYNC_SHARD_API_VERSION,
+      generated_at: generatedAt,
+      export_id: exportId,
+      project_id: projectId || null,
+      spec_id: resolvedSpecId || null,
+      target_library: targetLibrary,
+      mirror_root: SHARED_LIBRARY_ROOT,
+      source_index_file: resolveSharedLibraryIndexRelativePath(targetLibrary),
+      total_entries: shardEntries.length,
+      entries: shardEntries
+    };
+    const contentSha256 = hashJson(shardPayload);
+    const shardFile = shardRootDir
+      ? path.posix.join(shardRootDir.replace(/\\/g, '/'), `${targetLibrary}.json`)
+      : '';
+    librarySummaries.push({
+      target_library: targetLibrary,
+      source_index_file: shardPayload.source_index_file,
+      shard_file: shardFile || null,
+      entry_count: shardEntries.length,
+      latest_published_at: normalizeString(shardEntries[0] && shardEntries[0].published_at) || null,
+      content_sha256: contentSha256
+    });
+    shardIndex[targetLibrary] = {
+      shard_file: shardFile || null,
+      source_index_file: shardPayload.source_index_file,
+      entry_count: shardEntries.length,
+      latest_published_at: normalizeString(shardEntries[0] && shardEntries[0].published_at) || null,
+      content_sha256: contentSha256
+    };
+
+    if (shardFile) {
+      const absoluteShardPath = path.join(projectPath, shardFile);
+      await fileSystem.ensureDir(path.dirname(absoluteShardPath));
+      await fileSystem.writeJson(absoluteShardPath, shardPayload, { spaces: 2 });
+    }
+  }
+
+  librarySummaries.sort((left, right) => `${left.target_library}`.localeCompare(`${right.target_library}`));
+  const success = blocked.length === 0;
+  const bundlePayload = {
+    api_version: SEMANTIC_SHARED_SYNC_BUNDLE_API_VERSION,
+    mode: 'semantic-export-shared-sync',
+    success,
+    generated_at: generatedAt,
+    export_id: exportId,
+    project_id: projectId || null,
+    spec_id: resolvedSpecId || null,
+    mirror_root: SHARED_LIBRARY_ROOT,
+    source_root_index: rootIndexRelativePath,
+    filters: {
+      project_id: projectId || null,
+      spec_id: specFilter || null,
+      lesson_id: lessonId || null,
+      capability_id: capabilityId || null,
+      target_library: targetLibraryFilter || null,
+      limit
+    },
+    totals: {
+      libraries_scanned: librariesToScan.length,
+      libraries_exported: librarySummaries.length,
+      entries_matched: limitedRefs.length,
+      entries_exported: exportedEntries.length,
+      blocked: blocked.length
+    },
+    libraries: librarySummaries,
+    blocked
+  };
+
+  const indexPayload = {
+    api_version: SEMANTIC_SHARED_SYNC_INDEX_API_VERSION,
+    generated_at: generatedAt,
+    export_id: exportId,
+    project_id: projectId || null,
+    spec_id: resolvedSpecId || null,
+    bundle_file: bundleOutFile || null,
+    shard_count: librarySummaries.length,
+    shards: shardIndex
+  };
+
+  const receiptPayload = {
+    api_version: SEMANTIC_SHARED_SYNC_RECEIPT_API_VERSION,
+    mode: 'semantic-export-shared-sync',
+    success,
+    generated_at: generatedAt,
+    export_id: exportId,
+    project_id: projectId || null,
+    spec_id: resolvedSpecId || null,
+    mirror_root: SHARED_LIBRARY_ROOT,
+    source_root_index: rootIndexRelativePath,
+    totals: bundlePayload.totals,
+    filters: bundlePayload.filters,
+    libraries: librarySummaries,
+    blocked
+  };
+
+  if (bundleOutFile) {
+    const absoluteBundlePath = path.join(projectPath, bundleOutFile);
+    await fileSystem.ensureDir(path.dirname(absoluteBundlePath));
+    await fileSystem.writeJson(absoluteBundlePath, bundlePayload, { spaces: 2 });
+  }
+  if (indexOutFile) {
+    const absoluteIndexPath = path.join(projectPath, indexOutFile);
+    await fileSystem.ensureDir(path.dirname(absoluteIndexPath));
+    await fileSystem.writeJson(absoluteIndexPath, indexPayload, { spaces: 2 });
+  }
+  if (receiptOutFile) {
+    const absoluteReceiptPath = path.join(projectPath, receiptOutFile);
+    await fileSystem.ensureDir(path.dirname(absoluteReceiptPath));
+    await fileSystem.writeJson(absoluteReceiptPath, receiptPayload, { spaces: 2 });
+  }
+
+  return {
+    ...receiptPayload,
+    out_file: bundleOutFile || null,
+    index_file: indexOutFile || null,
+    receipt_file: receiptOutFile || null
+  };
+}
+
+module.exports = {
+  SEMANTIC_SHARED_SYNC_BUNDLE_API_VERSION,
+  SEMANTIC_SHARED_SYNC_INDEX_API_VERSION,
+  SEMANTIC_SHARED_SYNC_SHARD_API_VERSION,
+  SEMANTIC_SHARED_SYNC_RECEIPT_API_VERSION,
+  resolveDefaultSemanticSharedSyncBundleOutFile,
+  resolveDefaultSemanticSharedSyncIndexOutFile,
+  resolveDefaultSemanticSharedSyncReceiptOutFile,
+  resolveDefaultSemanticSharedSyncShardOutFile,
+  exportSemanticSharedSyncBundle
+};