scene-capability-engine 3.6.65 → 3.6.67

package/lib/semantic/shared-source-config.js

@@ -0,0 +1,183 @@
+const path = require('path');
+const fs = require('fs-extra');
+const {
+  SEMANTIC_SHARED_SOURCE_CONFIG,
+  resolveSemanticSharedSourceConfigPath
+} = require('./shared-sync-intake');
+
+const SEMANTIC_SHARED_SOURCE_CONFIG_API_VERSION = 'sce.semantic.shared-source-config/v0.1';
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeBoolean(value, fallback = true) {
+  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 sanitizeSource(source = {}) {
+  if (!isObject(source)) {
+    return null;
+  }
+  const bundle = normalizeString(source.bundle || source.source || source.url || source.file);
+  if (!bundle) {
+    return null;
+  }
+  return {
+    name: normalizeString(source.name) || 'semantic-shared',
+    enabled: normalizeBoolean(source.enabled, true),
+    bundle,
+    root: normalizeString(source.root || source.base || source.base_url || source.base_path) || null,
+    required_release_state: normalizeString(source.required_release_state || source.requiredReleaseState) || null
+  };
+}
+
+function toPayloadItems(sources = []) {
+  return sources
+    .map((item) => sanitizeSource(item))
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+async function loadSourceDescriptor(projectPath, inputFile = '', fileSystem = fs) {
+  const normalized = normalizeString(inputFile);
+  if (!normalized) {
+    return null;
+  }
+  const absolutePath = path.isAbsolute(normalized)
+    ? normalized
+    : path.resolve(projectPath, normalized);
+  if (!await fileSystem.pathExists(absolutePath)) {
+    throw new Error(`shared source descriptor not found: ${inputFile}`);
+  }
+  const payload = await fileSystem.readJson(absolutePath);
+  if (!isObject(payload) || !isObject(payload.source)) {
+    throw new Error(`invalid shared source descriptor: ${inputFile}`);
+  }
+  return {
+    descriptor_file: absolutePath,
+    descriptor: payload
+  };
+}
+
+async function readSemanticSharedSourceConfigForUpdate(projectPath, configPath = '', fileSystem = fs) {
+  const absoluteConfigPath = resolveSemanticSharedSourceConfigPath(projectPath, configPath || SEMANTIC_SHARED_SOURCE_CONFIG);
+  if (!await fileSystem.pathExists(absoluteConfigPath)) {
+    return {
+      config_file: absoluteConfigPath,
+      config: {
+        enabled: true,
+        mirror_root: '.sce/knowledge/semantic-shared',
+        sources: []
+      }
+    };
+  }
+  const config = await fileSystem.readJson(absoluteConfigPath);
+  if (!isObject(config)) {
+    throw new Error(`semantic shared source config must be a JSON object: ${absoluteConfigPath}`);
+  }
+  return {
+    config_file: absoluteConfigPath,
+    config: {
+      enabled: normalizeBoolean(config.enabled, true),
+      mirror_root: normalizeString(config.mirror_root) || '.sce/knowledge/semantic-shared',
+      sources: Array.isArray(config.sources) ? config.sources : []
+    }
+  };
+}
+
+async function listSemanticSharedSources(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const { config_file, config } = await readSemanticSharedSourceConfigForUpdate(projectPath, options.config, fileSystem);
+  const items = toPayloadItems(config.sources);
+  return {
+    api_version: SEMANTIC_SHARED_SOURCE_CONFIG_API_VERSION,
+    mode: 'semantic-list-shared-sources',
+    success: true,
+    enabled: normalizeBoolean(config.enabled, true),
+    mirror_root: normalizeString(config.mirror_root) || '.sce/knowledge/semantic-shared',
+    config_file,
+    total: items.length,
+    items
+  };
+}
+
+async function upsertSemanticSharedSource(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const { config_file, config } = await readSemanticSharedSourceConfigForUpdate(projectPath, options.config, fileSystem);
+  const descriptorPayload = await loadSourceDescriptor(projectPath, options.inputFile || options.input_file, fileSystem);
+  const descriptorSource = descriptorPayload && descriptorPayload.descriptor && descriptorPayload.descriptor.source;
+  const name = normalizeString(options.name) || normalizeString(descriptorSource && descriptorSource.name);
+  const bundle = normalizeString(options.bundle || options.source || options.url || options.file)
+    || normalizeString(descriptorSource && descriptorSource.bundle);
+  if (!name) {
+    throw new Error('shared source name is required');
+  }
+  if (!bundle) {
+    throw new Error('shared source bundle is required');
+  }
+
+  const nextSource = sanitizeSource({
+    name,
+    enabled: options.enabled ?? (descriptorSource && descriptorSource.enabled),
+    bundle,
+    root: options.root || (descriptorSource && descriptorSource.root),
+    required_release_state: options.requiredReleaseState || options.required_release_state || (descriptorSource && descriptorSource.required_release_state)
+  });
+  if (!nextSource) {
+    throw new Error('failed to normalize shared source configuration');
+  }
+
+  const existingSources = toPayloadItems(config.sources);
+  const nextSources = existingSources.filter((item) => item.name !== nextSource.name);
+  nextSources.push(nextSource);
+  nextSources.sort((left, right) => left.name.localeCompare(right.name));
+
+  const nextConfig = {
+    enabled: normalizeBoolean(config.enabled, true),
+    mirror_root: normalizeString(config.mirror_root) || '.sce/knowledge/semantic-shared',
+    sources: nextSources
+  };
+  await fileSystem.ensureDir(require('path').dirname(config_file));
+  await fileSystem.writeJson(config_file, nextConfig, { spaces: 2 });
+
+  return {
+    api_version: SEMANTIC_SHARED_SOURCE_CONFIG_API_VERSION,
+    mode: 'semantic-set-shared-source',
+    success: true,
+    config_file,
+    descriptor_file: descriptorPayload ? descriptorPayload.descriptor_file : null,
+    source: nextSource,
+    total: nextSources.length,
+    items: nextSources
+  };
+}
+
+module.exports = {
+  SEMANTIC_SHARED_SOURCE_CONFIG_API_VERSION,
+  loadSourceDescriptor,
+  listSemanticSharedSources,
+  upsertSemanticSharedSource
+};

package/lib/semantic/shared-source-connect.js

@@ -0,0 +1,139 @@
+const fs = require('fs-extra');
+const { loadSourceDescriptor, upsertSemanticSharedSource } = require('./shared-source-config');
+const { inspectSemanticSharedSource, syncSemanticSharedBundle } = require('./shared-sync-intake');
+const { resolveDefaultSemanticSharedPublishedSourceDescriptorOutFile } = require('./shared-sync-release');
+
+const SEMANTIC_SHARED_SOURCE_CONNECT_API_VERSION = 'sce.semantic.shared-source-connect/v0.1';
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+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 readDescriptorReleaseState(descriptor = {}) {
+  if (!descriptor || typeof descriptor !== 'object') {
+    return '';
+  }
+  const publication = descriptor.publication && typeof descriptor.publication === 'object'
+    ? descriptor.publication
+    : {};
+  return normalizeString(publication.release_state)
+    || normalizeString(descriptor.source && descriptor.source.required_release_state);
+}
+
+async function connectSemanticSharedSource(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const specId = normalizeString(options.spec);
+  const descriptorInput = normalizeString(options.inputFile || options.input_file)
+    || (specId ? resolveDefaultSemanticSharedPublishedSourceDescriptorOutFile(specId) : '');
+  if (!descriptorInput) {
+    throw new Error('shared source descriptor is required (use --input-file or provide --spec)');
+  }
+
+  const descriptorPayload = await loadSourceDescriptor(projectPath, descriptorInput, fileSystem);
+  const descriptor = descriptorPayload.descriptor;
+  const descriptorReleaseState = readDescriptorReleaseState(descriptor) || null;
+  const allowNonApproved = normalizeBoolean(options.allowNonApproved || options.allow_non_approved, false);
+  const blocked = [];
+  if (!allowNonApproved && descriptorReleaseState !== 'approved-central') {
+    blocked.push({
+      reason: 'descriptor-not-approved-central',
+      descriptor_release_state: descriptorReleaseState
+    });
+  }
+
+  let registration = null;
+  let health = null;
+  let sync = null;
+
+  if (blocked.length === 0) {
+    registration = await upsertSemanticSharedSource({
+      inputFile: descriptorInput,
+      name: options.name,
+      bundle: options.bundle,
+      root: options.root,
+      enabled: options.enabled,
+      requiredReleaseState: options.requiredReleaseState || options.required_release_state,
+      config: options.config
+    }, {
+      projectPath,
+      fileSystem
+    });
+
+    const shouldHealthCheck = options.healthCheck !== false;
+    if (shouldHealthCheck) {
+      health = await inspectSemanticSharedSource({
+        sourceName: registration.source.name,
+        requiredReleaseState: registration.source.required_release_state,
+        config: options.config
+      }, {
+        projectPath,
+        fileSystem
+      });
+      if (!health.success) {
+        blocked.push({
+          reason: 'health-check-failed',
+          source_name: registration.source.name
+        });
+      }
+    }
+
+    const shouldSyncNow = options.syncNow !== false;
+    if (blocked.length === 0 && shouldSyncNow) {
+      sync = await syncSemanticSharedBundle({
+        sourceName: registration.source.name,
+        requiredReleaseState: registration.source.required_release_state,
+        config: options.config,
+        spec: specId || normalizeString(descriptor.spec_id)
+      }, {
+        projectPath,
+        fileSystem
+      });
+      if (!sync.success) {
+        blocked.push({
+          reason: 'sync-failed',
+          source_name: registration.source.name
+        });
+      }
+    }
+  }
+
+  return {
+    api_version: SEMANTIC_SHARED_SOURCE_CONNECT_API_VERSION,
+    mode: 'semantic-connect-shared-source',
+    success: blocked.length === 0,
+    descriptor_file: descriptorPayload.descriptor_file,
+    descriptor_release_state: descriptorReleaseState,
+    source_name: registration && registration.source ? registration.source.name : normalizeString(descriptor.source && descriptor.source.name) || null,
+    config_file: registration ? registration.config_file : null,
+    registration,
+    health,
+    sync,
+    blocked
+  };
+}
+
+module.exports = {
+  SEMANTIC_SHARED_SOURCE_CONNECT_API_VERSION,
+  connectSemanticSharedSource
+};

package/lib/semantic/shared-source-discovery.js

@@ -0,0 +1,98 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const SEMANTIC_SHARED_SOURCE_DISCOVERY_API_VERSION = 'sce.semantic.shared-source-discovery/v0.1';
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function toProjectRelative(projectPath, targetPath) {
+  return path.relative(projectPath, targetPath).replace(/\\/g, '/');
+}
+
+async function listDescriptorFiles(projectPath, fileSystem = fs) {
+  const specsRoot = path.join(projectPath, '.sce', 'specs');
+  if (!await fileSystem.pathExists(specsRoot)) {
+    return [];
+  }
+  const specEntries = await fileSystem.readdir(specsRoot);
+  const descriptorFiles = [];
+  for (const specEntry of specEntries) {
+    const candidate = path.join(specsRoot, specEntry, 'registry', 'semantic-shared', 'published', 'source-descriptor.json');
+    if (await fileSystem.pathExists(candidate)) {
+      descriptorFiles.push(candidate);
+    }
+  }
+  return descriptorFiles;
+}
+
+function buildDiscoveryItem(projectPath, absolutePath, payload = {}) {
+  const source = payload && typeof payload.source === 'object' ? payload.source : {};
+  const publication = payload && typeof payload.publication === 'object' ? payload.publication : {};
+  const releaseState = normalizeString(publication.release_state)
+    || normalizeString(source.required_release_state)
+    || null;
+  const descriptorFile = toProjectRelative(projectPath, absolutePath);
+  return {
+    descriptor_file: descriptorFile,
+    spec_id: normalizeString(payload.spec_id) || null,
+    source_name: normalizeString(source.name) || 'semantic-shared',
+    bundle: normalizeString(source.bundle) || null,
+    root: normalizeString(source.root) || null,
+    required_release_state: normalizeString(source.required_release_state) || null,
+    publication_release_state: releaseState,
+    approved: releaseState === 'approved-central',
+    suggested_connect_command: `sce semantic connect-shared-source --input-file ${descriptorFile} --json`
+  };
+}
+
+async function discoverSemanticSharedSourceDescriptors(projectPath, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const descriptorFiles = await listDescriptorFiles(projectPath, fileSystem);
+  const items = [];
+  const blocked = [];
+
+  for (const absolutePath of descriptorFiles) {
+    try {
+      const payload = await fileSystem.readJson(absolutePath);
+      if (!payload || typeof payload !== 'object' || !payload.source || typeof payload.source !== 'object') {
+        blocked.push({
+          descriptor_file: toProjectRelative(projectPath, absolutePath),
+          reason: 'invalid-descriptor-payload'
+        });
+        continue;
+      }
+      items.push(buildDiscoveryItem(projectPath, absolutePath, payload));
+    } catch (error) {
+      blocked.push({
+        descriptor_file: toProjectRelative(projectPath, absolutePath),
+        reason: 'failed-to-read-descriptor',
+        detail: error.message
+      });
+    }
+  }
+
+  items.sort((left, right) => left.descriptor_file.localeCompare(right.descriptor_file));
+
+  return {
+    api_version: SEMANTIC_SHARED_SOURCE_DISCOVERY_API_VERSION,
+    mode: 'semantic-shared-source-discovery',
+    project_path: projectPath,
+    summary: {
+      total: items.length,
+      approved: items.filter((item) => item.approved).length,
+      blocked: blocked.length
+    },
+    items,
+    blocked
+  };
+}
+
+module.exports = {
+  SEMANTIC_SHARED_SOURCE_DISCOVERY_API_VERSION,
+  discoverSemanticSharedSourceDescriptors
+};