scene-capability-engine 3.6.65 → 3.6.67

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

@@ -0,0 +1,463 @@
+const path = require('path');
+const http = require('http');
+const https = require('https');
+const fs = require('fs-extra');
+const {
+  SEMANTIC_SHARED_SYNC_BUNDLE_API_VERSION,
+  SEMANTIC_SHARED_SYNC_INDEX_API_VERSION,
+  SEMANTIC_SHARED_SYNC_SHARD_API_VERSION
+} = require('./shared-sync-export');
+
+const SEMANTIC_SHARED_SYNC_RELEASE_RECEIPT_API_VERSION = 'sce.semantic.shared-sync.release-receipt/v0.1';
+const SEMANTIC_SHARED_SOURCE_DESCRIPTOR_API_VERSION = 'sce.semantic.shared-source-descriptor/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;
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = normalizeString(`${value || ''}`).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isHttpSource(source = '') {
+  return /^https?:\/\//i.test(normalizeString(source));
+}
+
+function inferSourceRootFromSource(source = '') {
+  const normalized = normalizeString(source);
+  if (!normalized) {
+    return '';
+  }
+  if (isHttpSource(normalized)) {
+    const sceMarkerIndex = normalized.indexOf('/.sce/');
+    if (sceMarkerIndex > 0) {
+      return normalized.slice(0, sceMarkerIndex);
+    }
+    return normalizeString(normalized.replace(/\/[^/]*$/, ''));
+  }
+  const normalizedPath = path.resolve(normalized);
+  const marker = `${path.sep}.sce${path.sep}`;
+  const markerIndex = normalizedPath.indexOf(marker);
+  if (markerIndex > -1) {
+    return normalizedPath.slice(0, markerIndex);
+  }
+  return path.dirname(normalizedPath);
+}
+
+function toProjectRelative(projectPath, targetPath) {
+  return path.relative(projectPath, targetPath).replace(/\\/g, '/');
+}
+
+function resolveDefaultSemanticSharedPublishedBaseDir(specId = '') {
+  const normalizedSpecId = normalizeString(specId);
+  if (!normalizedSpecId) {
+    return '';
+  }
+  return `.sce/specs/${normalizedSpecId}/registry/semantic-shared/published`;
+}
+
+function resolveDefaultSemanticSharedPublishedBundleOutFile(specId = '') {
+  const baseDir = resolveDefaultSemanticSharedPublishedBaseDir(specId);
+  return baseDir ? `${baseDir}/latest.bundle.json` : '';
+}
+
+function resolveDefaultSemanticSharedPublishedIndexOutFile(specId = '') {
+  const baseDir = resolveDefaultSemanticSharedPublishedBaseDir(specId);
+  return baseDir ? `${baseDir}/latest.index.json` : '';
+}
+
+function resolveDefaultSemanticSharedPublishedReceiptOutFile(specId = '') {
+  const baseDir = resolveDefaultSemanticSharedPublishedBaseDir(specId);
+  return baseDir ? `${baseDir}/latest.receipt.json` : '';
+}
+
+function resolveDefaultSemanticSharedPublishedSourceDescriptorOutFile(specId = '') {
+  const baseDir = resolveDefaultSemanticSharedPublishedBaseDir(specId);
+  return baseDir ? `${baseDir}/source-descriptor.json` : '';
+}
+
+function resolveDefaultSemanticSharedPublishedShardOutFile(specId = '', targetLibrary = '') {
+  const baseDir = resolveDefaultSemanticSharedPublishedBaseDir(specId);
+  const normalizedLibrary = normalizeString(targetLibrary);
+  return baseDir && normalizedLibrary
+    ? `${baseDir}/shards/${normalizedLibrary}.json`
+    : '';
+}
+
+function fetchJsonFromHttp(source, timeoutMs = 15000) {
+  const normalized = normalizeString(source);
+  if (!normalized) {
+    return Promise.reject(new Error('shared release source is required'));
+  }
+  const client = normalized.startsWith('https://') ? https : http;
+  return new Promise((resolve, reject) => {
+    const request = client.get(normalized, {
+      timeout: timeoutMs,
+      headers: {
+        Accept: 'application/json'
+      }
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`shared release source responded ${response.statusCode}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(new Error(`shared release source returned invalid JSON: ${error.message}`));
+        }
+      });
+    });
+    request.on('timeout', () => {
+      request.destroy(new Error('shared release source request timed out'));
+    });
+    request.on('error', reject);
+  });
+}
+
+async function loadJsonSource(projectPath, source, fileSystem = fs) {
+  const normalized = normalizeString(source);
+  if (!normalized) {
+    throw new Error('shared release source is required');
+  }
+  if (isHttpSource(normalized)) {
+    return fetchJsonFromHttp(normalized);
+  }
+  const absolutePath = path.isAbsolute(normalized)
+    ? normalized
+    : path.resolve(projectPath, normalized);
+  if (!await fileSystem.pathExists(absolutePath)) {
+    throw new Error(`shared release source file not found: ${source}`);
+  }
+  return fileSystem.readJson(absolutePath);
+}
+
+function resolveCandidateShardSource(projectPath, bundleSource, shardFile) {
+  const normalizedShardFile = normalizeString(shardFile);
+  if (!normalizedShardFile) {
+    return '';
+  }
+  if (isHttpSource(normalizedShardFile) || path.isAbsolute(normalizedShardFile)) {
+    return normalizedShardFile;
+  }
+  if (/^\.sce[\\/]/i.test(normalizedShardFile)) {
+    const sourceRoot = inferSourceRootFromSource(path.isAbsolute(bundleSource) ? bundleSource : path.resolve(projectPath, bundleSource));
+    if (isHttpSource(sourceRoot)) {
+      return `${sourceRoot.replace(/\/+$/, '')}/${normalizedShardFile.replace(/^\/+/, '')}`;
+    }
+    if (sourceRoot) {
+      return path.resolve(sourceRoot, normalizedShardFile);
+    }
+    return path.resolve(projectPath, normalizedShardFile);
+  }
+  if (isHttpSource(bundleSource)) {
+    return new URL(normalizedShardFile, bundleSource).toString();
+  }
+  const bundleDir = path.dirname(path.isAbsolute(bundleSource) ? bundleSource : path.resolve(projectPath, bundleSource));
+  return path.resolve(bundleDir, normalizedShardFile);
+}
+
+function assessApprovedCentralEntryGate(entry = {}) {
+  const publication = isObject(entry.publication) ? entry.publication : {};
+  const publishState = normalizeString(publication.publish_state);
+  const blockedReason = normalizeString(publication.blocked_reason);
+  const blockedGate = isObject(publication.blocked_gate) ? publication.blocked_gate : null;
+  const reasons = [];
+
+  if (publishState && publishState !== 'published-shared') {
+    reasons.push({
+      reason: 'entry-not-shared-ready',
+      publish_state: publishState
+    });
+  }
+  if (blockedReason) {
+    reasons.push({
+      reason: 'entry-has-blocked-reason',
+      blocked_reason: blockedReason
+    });
+  }
+  if (blockedGate) {
+    reasons.push({
+      reason: 'entry-has-blocked-gate',
+      blocked_gate: blockedGate
+    });
+  }
+
+  return {
+    allowed: reasons.length === 0,
+    reasons
+  };
+}
+
+async function publishSemanticSharedRegistry(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const specId = normalizeString(options.spec);
+  const inputFile = normalizeString(options.inputFile || options.input_file)
+    || (specId ? `.sce/specs/${specId}/registry/semantic-shared/latest.bundle.json` : '');
+  if (!inputFile) {
+    throw new Error('candidate bundle source is required (use --input-file or provide --spec)');
+  }
+
+  const candidateBundle = await loadJsonSource(projectPath, inputFile, fileSystem);
+  if (!isObject(candidateBundle) || normalizeString(candidateBundle.api_version) !== SEMANTIC_SHARED_SYNC_BUNDLE_API_VERSION) {
+    throw new Error(`invalid semantic shared candidate bundle: ${inputFile}`);
+  }
+
+  const minSources = normalizeInteger(options.minSources || options.min_sources, 1);
+  const minEntries = normalizeInteger(options.minEntries || options.min_entries, 1);
+  const requireZeroBlocked = normalizeBoolean(options.requireZeroBlocked ?? options.require_zero_blocked, true);
+  const generatedAt = new Date().toISOString();
+  const blocked = [];
+
+  const totals = isObject(candidateBundle.totals) ? candidateBundle.totals : {};
+  const sourceReports = Array.isArray(candidateBundle.sources) ? candidateBundle.sources : [];
+  const libraries = Array.isArray(candidateBundle.libraries) ? candidateBundle.libraries : [];
+
+  if (sourceReports.length < minSources) {
+    blocked.push({
+      reason: 'insufficient-sources',
+      required_sources: minSources,
+      actual_sources: sourceReports.length
+    });
+  }
+  if (normalizeInteger(totals.merged_entries, 0) < minEntries) {
+    blocked.push({
+      reason: 'insufficient-merged-entries',
+      required_entries: minEntries,
+      actual_entries: normalizeInteger(totals.merged_entries, 0)
+    });
+  }
+  if (requireZeroBlocked && normalizeInteger(totals.blocked, 0) > 0) {
+    blocked.push({
+      reason: 'candidate-has-blocked-entries',
+      blocked_entries: normalizeInteger(totals.blocked, 0)
+    });
+  }
+
+  const publishedLibraries = [];
+  const publishedIndexShards = {};
+  for (const library of libraries) {
+    const targetLibrary = normalizeString(library && library.target_library);
+    const publishedShardFile = resolveDefaultSemanticSharedPublishedShardOutFile(specId, targetLibrary);
+    const candidateShardSource = resolveCandidateShardSource(projectPath, inputFile, normalizeString(library && library.shard_file));
+    let shardPayload = {
+      api_version: SEMANTIC_SHARED_SYNC_SHARD_API_VERSION,
+      generated_at: generatedAt,
+      target_library: targetLibrary,
+      total_entries: 0,
+      entries: []
+    };
+    if (candidateShardSource) {
+      const loadedShard = await loadJsonSource(projectPath, candidateShardSource, fileSystem);
+      if (isObject(loadedShard) && normalizeString(loadedShard.api_version) === SEMANTIC_SHARED_SYNC_SHARD_API_VERSION) {
+        const shardEntries = Array.isArray(loadedShard.entries) ? loadedShard.entries : [];
+        const shardBlockedEntries = [];
+        for (const entry of shardEntries) {
+          const gate = assessApprovedCentralEntryGate(entry);
+          if (!gate.allowed) {
+            shardBlockedEntries.push({
+              capability_id: normalizeString(entry && entry.capability_id) || null,
+              lesson_id: normalizeString(entry && entry.lesson_id) || null,
+              target_library: targetLibrary || normalizeString(entry && entry.target_library) || null,
+              reason: 'entry-failed-approved-central-gate',
+              gate
+            });
+          }
+        }
+        if (shardBlockedEntries.length > 0) {
+          blocked.push(...shardBlockedEntries);
+        }
+        shardPayload = {
+          ...loadedShard,
+          generated_at: generatedAt,
+          publication: {
+            publish_state: blocked.length === 0 ? 'approved-central' : 'publish-blocked',
+            source_bundle: inputFile
+          }
+        };
+      }
+    }
+    if (publishedShardFile) {
+      const absoluteShardPath = path.join(projectPath, publishedShardFile);
+      await fileSystem.ensureDir(path.dirname(absoluteShardPath));
+      await fileSystem.writeJson(absoluteShardPath, shardPayload, { spaces: 2 });
+    }
+    publishedLibraries.push({
+      target_library: targetLibrary,
+      shard_file: publishedShardFile || null,
+      entry_count: normalizeInteger(shardPayload.total_entries, 0),
+      latest_published_at: normalizeString(library && library.latest_published_at) || null
+    });
+    publishedIndexShards[targetLibrary] = {
+      shard_file: publishedShardFile || null,
+      entry_count: normalizeInteger(shardPayload.total_entries, 0),
+      latest_published_at: normalizeString(library && library.latest_published_at) || null
+    };
+  }
+
+  const success = blocked.length === 0;
+  const bundlePayload = {
+    api_version: SEMANTIC_SHARED_SYNC_BUNDLE_API_VERSION,
+    mode: 'semantic-publish-shared-registry',
+    success,
+    generated_at: generatedAt,
+    spec_id: specId || normalizeString(candidateBundle.spec_id) || null,
+    mirror_root: normalizeString(candidateBundle.mirror_root) || '.sce/knowledge/semantic-shared',
+    governance: {
+      release_state: success ? 'approved-central' : 'publish-blocked',
+      candidate_bundle: normalizeString(inputFile),
+      min_sources: minSources,
+      min_entries: minEntries,
+      require_zero_blocked: requireZeroBlocked
+    },
+    totals: {
+      sources: sourceReports.length,
+      merged_entries: normalizeInteger(totals.merged_entries, 0),
+      superseded: normalizeInteger(totals.superseded, 0),
+      blocked: blocked.length
+    },
+    sources: sourceReports,
+    libraries: publishedLibraries,
+    blocked
+  };
+
+  const bundleOutFile = normalizeString(options.outFile || options.out_file)
+    || resolveDefaultSemanticSharedPublishedBundleOutFile(specId);
+  const indexOutFile = normalizeString(options.indexFile || options.index_file)
+    || resolveDefaultSemanticSharedPublishedIndexOutFile(specId);
+  const receiptOutFile = normalizeString(options.receiptFile || options.receipt_file)
+    || resolveDefaultSemanticSharedPublishedReceiptOutFile(specId);
+  const sourceDescriptorOutFile = normalizeString(options.sourceDescriptorFile || options.source_descriptor_file)
+    || resolveDefaultSemanticSharedPublishedSourceDescriptorOutFile(specId);
+  const sourceName = normalizeString(options.sourceName || options.source_name) || 'central';
+  const publicBundle = normalizeString(options.publicBundle || options.public_bundle);
+  const publicRoot = normalizeString(options.publicRoot || options.public_root);
+
+  const indexPayload = {
+    api_version: SEMANTIC_SHARED_SYNC_INDEX_API_VERSION,
+    generated_at: generatedAt,
+    spec_id: specId || normalizeString(candidateBundle.spec_id) || null,
+    bundle_file: bundleOutFile || null,
+    shard_count: publishedLibraries.length,
+    shards: publishedIndexShards
+  };
+
+  const receiptPayload = {
+    api_version: SEMANTIC_SHARED_SYNC_RELEASE_RECEIPT_API_VERSION,
+    mode: 'semantic-publish-shared-registry',
+    success,
+    generated_at: generatedAt,
+    spec_id: specId || normalizeString(candidateBundle.spec_id) || null,
+    candidate_bundle: normalizeString(inputFile),
+    governance: bundlePayload.governance,
+    totals: bundlePayload.totals,
+    libraries: publishedLibraries,
+    blocked
+  };
+
+  let absoluteBundlePath = '';
+  if (bundleOutFile) {
+    absoluteBundlePath = path.isAbsolute(bundleOutFile)
+      ? bundleOutFile
+      : path.join(projectPath, bundleOutFile);
+    await fileSystem.ensureDir(path.dirname(absoluteBundlePath));
+    await fileSystem.writeJson(absoluteBundlePath, bundlePayload, { spaces: 2 });
+    bundlePayload.out_file = toProjectRelative(projectPath, absoluteBundlePath);
+  }
+  if (indexOutFile) {
+    const absoluteIndexPath = path.isAbsolute(indexOutFile)
+      ? indexOutFile
+      : path.join(projectPath, indexOutFile);
+    await fileSystem.ensureDir(path.dirname(absoluteIndexPath));
+    await fileSystem.writeJson(absoluteIndexPath, indexPayload, { spaces: 2 });
+  }
+  if (receiptOutFile) {
+    const absoluteReceiptPath = path.isAbsolute(receiptOutFile)
+      ? receiptOutFile
+      : path.join(projectPath, receiptOutFile);
+    await fileSystem.ensureDir(path.dirname(absoluteReceiptPath));
+    await fileSystem.writeJson(absoluteReceiptPath, receiptPayload, { spaces: 2 });
+  }
+
+  let sourceDescriptor = null;
+  if (sourceDescriptorOutFile) {
+    const absoluteDescriptorPath = path.isAbsolute(sourceDescriptorOutFile)
+      ? sourceDescriptorOutFile
+      : path.join(projectPath, sourceDescriptorOutFile);
+    const sourceBundle = publicBundle || absoluteBundlePath || bundlePayload.out_file || bundleOutFile || null;
+    const inferredRoot = publicRoot || inferSourceRootFromSource(sourceBundle || '');
+    sourceDescriptor = {
+      api_version: SEMANTIC_SHARED_SOURCE_DESCRIPTOR_API_VERSION,
+      mode: 'semantic-shared-source-descriptor',
+      generated_at: generatedAt,
+      spec_id: specId || normalizeString(candidateBundle.spec_id) || null,
+      source: {
+        name: sourceName,
+        enabled: true,
+        bundle: sourceBundle,
+        root: inferredRoot || null,
+        required_release_state: success ? 'approved-central' : 'publish-blocked'
+      },
+      publication: {
+        release_state: bundlePayload.governance.release_state,
+        bundle_file: bundlePayload.out_file || bundleOutFile || null,
+        receipt_file: receiptOutFile || null
+      }
+    };
+    await fileSystem.ensureDir(path.dirname(absoluteDescriptorPath));
+    await fileSystem.writeJson(absoluteDescriptorPath, sourceDescriptor, { spaces: 2 });
+  }
+
+  return {
+    ...receiptPayload,
+    out_file: bundlePayload.out_file || bundleOutFile || null,
+    index_file: indexOutFile || null,
+    receipt_file: receiptOutFile || null,
+    source_descriptor_file: sourceDescriptorOutFile || null,
+    source_descriptor: sourceDescriptor
+  };
+}
+
+module.exports = {
+  SEMANTIC_SHARED_SYNC_RELEASE_RECEIPT_API_VERSION,
+  SEMANTIC_SHARED_SOURCE_DESCRIPTOR_API_VERSION,
+  resolveDefaultSemanticSharedPublishedBundleOutFile,
+  resolveDefaultSemanticSharedPublishedIndexOutFile,
+  resolveDefaultSemanticSharedPublishedReceiptOutFile,
+  resolveDefaultSemanticSharedPublishedSourceDescriptorOutFile,
+  resolveDefaultSemanticSharedPublishedShardOutFile,
+  publishSemanticSharedRegistry
+};