scene-capability-engine 3.0.0

package/lib/scene-runtime/binding-plugin-loader.js

@@ -0,0 +1,351 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const DEFAULT_BINDING_PLUGIN_DIRS = [
+  '.kiro/plugins/scene-bindings',
+  '.kiro/config/scene-bindings'
+];
+const DEFAULT_BINDING_PLUGIN_MANIFEST = '.kiro/config/scene-binding-plugins.json';
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizePath(projectRoot, targetPath) {
+  if (!targetPath) {
+    return null;
+  }
+
+  if (path.isAbsolute(targetPath)) {
+    return targetPath;
+  }
+
+  return path.join(projectRoot, targetPath);
+}
+
+function normalizePluginFileToken(value) {
+  const normalized = String(value || '').trim().replace(/\\/g, '/');
+  if (!normalized) {
+    return null;
+  }
+
+  return path.posix.basename(normalized);
+}
+
+function extractPluginDefinitions(exportedValue, filePath, warnings = []) {
+  let value = exportedValue;
+
+  if (value && isPlainObject(value) && value.__esModule && value.default) {
+    value = value.default;
+  }
+
+  if (typeof value === 'function') {
+    try {
+      value = value();
+    } catch (error) {
+      warnings.push(`binding plugin factory failed: ${filePath} (${error.message})`);
+      return [];
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value;
+  }
+
+  if (isPlainObject(value)) {
+    return [value];
+  }
+
+  warnings.push(`binding plugin export must be object/array/function: ${filePath}`);
+  return [];
+}
+
+function normalizePluginHandler(handler, fallbackId) {
+  if (!isPlainObject(handler) || typeof handler.execute !== 'function') {
+    return null;
+  }
+
+  return {
+    ...handler,
+    id: handler.id || fallbackId
+  };
+}
+
+function normalizePluginManifest(rawManifest, manifestPath, warnings = []) {
+  if (!isPlainObject(rawManifest)) {
+    warnings.push(`binding plugin manifest must be a JSON object: ${manifestPath}`);
+    return null;
+  }
+
+  const strict = rawManifest.strict === true;
+  const enabledByDefault = rawManifest.enabled_by_default !== false;
+  const defaultPriority = Number.isFinite(rawManifest.default_priority) ? Number(rawManifest.default_priority) : 1000;
+
+  const allowedFiles = new Set(
+    (Array.isArray(rawManifest.allowed_files) ? rawManifest.allowed_files : [])
+      .map(normalizePluginFileToken)
+      .filter(Boolean)
+  );
+
+  const blockedFiles = new Set(
+    (Array.isArray(rawManifest.blocked_files) ? rawManifest.blocked_files : [])
+      .map(normalizePluginFileToken)
+      .filter(Boolean)
+  );
+
+  const pluginEntries = new Map();
+
+  if (Array.isArray(rawManifest.plugins)) {
+    let order = 0;
+
+    for (const entry of rawManifest.plugins) {
+      order += 1;
+
+      if (!isPlainObject(entry)) {
+        warnings.push(`invalid plugin manifest entry ignored at index ${order}: ${manifestPath}`);
+        continue;
+      }
+
+      const fileToken = normalizePluginFileToken(entry.file);
+      if (!fileToken) {
+        warnings.push(`plugin manifest entry missing file at index ${order}: ${manifestPath}`);
+        continue;
+      }
+
+      pluginEntries.set(fileToken, {
+        enabled: entry.enabled !== false,
+        priority: Number.isFinite(entry.priority) ? Number(entry.priority) : defaultPriority,
+        order
+      });
+    }
+  }
+
+  return {
+    strict,
+    enabledByDefault,
+    defaultPriority,
+    allowedFiles,
+    blockedFiles,
+    pluginEntries,
+    manifestPath
+  };
+}
+
+function loadPluginManifest(projectRoot, options = {}, warnings = []) {
+  const manifestEnabled = options.manifestEnabled !== false;
+  if (!manifestEnabled) {
+    return {
+      manifest: null,
+      manifestPath: null,
+      manifestLoaded: false
+    };
+  }
+
+  const explicitManifestPath = typeof options.manifestPath === 'string' && options.manifestPath.trim().length > 0;
+  const manifestPath = explicitManifestPath
+    ? normalizePath(projectRoot, options.manifestPath)
+    : path.join(projectRoot, DEFAULT_BINDING_PLUGIN_MANIFEST);
+
+  if (!manifestPath || !fs.pathExistsSync(manifestPath)) {
+    if (explicitManifestPath) {
+      warnings.push(`binding plugin manifest not found: ${manifestPath}`);
+    }
+
+    return {
+      manifest: null,
+      manifestPath: explicitManifestPath ? manifestPath : null,
+      manifestLoaded: false
+    };
+  }
+
+  try {
+    const rawManifest = fs.readJsonSync(manifestPath);
+    const manifest = normalizePluginManifest(rawManifest, manifestPath, warnings);
+
+    if (!manifest) {
+      return {
+        manifest: null,
+        manifestPath,
+        manifestLoaded: false
+      };
+    }
+
+    return {
+      manifest,
+      manifestPath,
+      manifestLoaded: true
+    };
+  } catch (error) {
+    warnings.push(`failed to read binding plugin manifest: ${manifestPath} (${error.message})`);
+
+    return {
+      manifest: null,
+      manifestPath,
+      manifestLoaded: false
+    };
+  }
+}
+
+function resolvePluginFilePlan(discoveredFiles = [], manifest = null, candidateDir = '', warnings = []) {
+  const orderedFiles = [];
+  const discoveredSet = new Set(discoveredFiles);
+
+  if (!manifest) {
+    for (const fileName of discoveredFiles) {
+      orderedFiles.push({ fileName, priority: 1000, order: Number.MAX_SAFE_INTEGER });
+    }
+
+    return orderedFiles
+      .sort((left, right) => left.fileName.localeCompare(right.fileName))
+      .map((item) => item.fileName);
+  }
+
+  for (const fileName of discoveredFiles) {
+    const entry = manifest.pluginEntries.get(fileName);
+
+    if (manifest.blockedFiles.has(fileName)) {
+      warnings.push(`binding plugin blocked by manifest: ${path.join(candidateDir, fileName)}`);
+      continue;
+    }
+
+    if (manifest.allowedFiles.size > 0 && !manifest.allowedFiles.has(fileName)) {
+      warnings.push(`binding plugin skipped (not allowed): ${path.join(candidateDir, fileName)}`);
+      continue;
+    }
+
+    if (entry && entry.enabled === false) {
+      continue;
+    }
+
+    if (!entry && (manifest.strict || !manifest.enabledByDefault)) {
+      warnings.push(`binding plugin skipped by manifest policy: ${path.join(candidateDir, fileName)}`);
+      continue;
+    }
+
+    orderedFiles.push({
+      fileName,
+      priority: entry ? entry.priority : manifest.defaultPriority,
+      order: entry ? entry.order : Number.MAX_SAFE_INTEGER
+    });
+  }
+
+  for (const declaredFile of manifest.pluginEntries.keys()) {
+    if (!discoveredSet.has(declaredFile)) {
+      warnings.push(`binding plugin declared but missing: ${path.join(candidateDir, declaredFile)}`);
+    }
+  }
+
+  return orderedFiles
+    .sort((left, right) => {
+      if (left.priority !== right.priority) {
+        return left.priority - right.priority;
+      }
+
+      if (left.order !== right.order) {
+        return left.order - right.order;
+      }
+
+      return left.fileName.localeCompare(right.fileName);
+    })
+    .map((item) => item.fileName);
+}
+
+function loadBindingPlugins(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const pluginDir = options.pluginDir || null;
+  const autoDiscovery = options.autoDiscovery !== false;
+
+  const warnings = [];
+  const pluginDirs = [];
+  const pluginFiles = [];
+  const handlers = [];
+
+  const manifestResolution = loadPluginManifest(projectRoot, {
+    manifestPath: options.manifestPath,
+    manifestEnabled: options.manifestEnabled !== false
+  }, warnings);
+
+  const candidateDirs = [];
+
+  if (pluginDir) {
+    const resolved = normalizePath(projectRoot, pluginDir);
+    if (resolved) {
+      candidateDirs.push(resolved);
+    }
+  } else if (autoDiscovery) {
+    for (const relativeDir of DEFAULT_BINDING_PLUGIN_DIRS) {
+      candidateDirs.push(path.join(projectRoot, relativeDir));
+    }
+  }
+
+  for (const candidateDir of candidateDirs) {
+    if (!candidateDir || !fs.pathExistsSync(candidateDir)) {
+      continue;
+    }
+
+    pluginDirs.push(candidateDir);
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(candidateDir, { withFileTypes: true });
+    } catch (error) {
+      warnings.push(`failed to list binding plugin dir: ${candidateDir} (${error.message})`);
+      continue;
+    }
+
+    const discoveredFiles = entries
+      .filter((entry) => entry && typeof entry.isFile === 'function' && entry.isFile() && /\.(js|cjs)$/i.test(entry.name || ''))
+      .map((entry) => normalizePluginFileToken(entry.name))
+      .filter(Boolean)
+      .sort((left, right) => left.localeCompare(right));
+
+    const filesToLoad = resolvePluginFilePlan(
+      discoveredFiles,
+      manifestResolution.manifest,
+      candidateDir,
+      warnings
+    );
+
+    for (const fileName of filesToLoad) {
+      const absolutePath = path.join(candidateDir, fileName);
+
+      try {
+        const resolvedPath = require.resolve(absolutePath);
+        delete require.cache[resolvedPath];
+        const pluginExport = require(resolvedPath);
+        const rawHandlers = extractPluginDefinitions(pluginExport, absolutePath, warnings);
+
+        let localIndex = 0;
+        for (const rawHandler of rawHandlers) {
+          localIndex += 1;
+          const handler = normalizePluginHandler(rawHandler, `${path.basename(fileName, path.extname(fileName))}-${localIndex}`);
+          if (!handler) {
+            warnings.push(`invalid binding handler in plugin: ${absolutePath}`);
+            continue;
+          }
+
+          handlers.push(handler);
+        }
+
+        pluginFiles.push(absolutePath);
+      } catch (error) {
+        warnings.push(`failed to load binding plugin: ${absolutePath} (${error.message})`);
+      }
+    }
+  }
+
+  return {
+    handlers,
+    warnings,
+    plugin_dirs: pluginDirs,
+    plugin_files: pluginFiles,
+    manifest_path: manifestResolution.manifestPath,
+    manifest_loaded: manifestResolution.manifestLoaded
+  };
+}
+
+module.exports = {
+  DEFAULT_BINDING_PLUGIN_DIRS,
+  DEFAULT_BINDING_PLUGIN_MANIFEST,
+  loadBindingPlugins
+};

package/lib/scene-runtime/binding-registry.js

@@ -0,0 +1,349 @@
+const { createMoquiAdapterHandler } = require('./moqui-adapter');
+
+const DEFAULT_READINESS_SUCCESS = {
+  passed: true,
+  reason: 'default-ready'
+};
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeNodeType(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+
+  if (!normalized) {
+    return null;
+  }
+
+  return normalized;
+}
+
+function normalizeRef(value) {
+  return String(value || '').trim();
+}
+
+function normalizePatternList(value) {
+  if (!value) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value;
+  }
+
+  return [value];
+}
+
+function createMatcher(match = null) {
+  if (typeof match === 'function') {
+    return match;
+  }
+
+  const normalizedMatch = isPlainObject(match)
+    ? match
+    : (typeof match === 'string' ? { refPrefix: match } : {});
+
+  const nodeTypes = normalizePatternList(normalizedMatch.nodeType || normalizedMatch.nodeTypes)
+    .map(normalizeNodeType)
+    .filter(Boolean);
+  const refPrefixes = normalizePatternList(normalizedMatch.refPrefix || normalizedMatch.refPrefixes)
+    .map((item) => normalizeRef(item).toLowerCase())
+    .filter(Boolean);
+
+  const refRegexes = [];
+  for (const item of normalizePatternList(normalizedMatch.refPattern || normalizedMatch.refPatterns)) {
+    if (!item) {
+      continue;
+    }
+
+    if (item instanceof RegExp) {
+      refRegexes.push(item);
+      continue;
+    }
+
+    const pattern = String(item).trim();
+    if (!pattern) {
+      continue;
+    }
+
+    try {
+      refRegexes.push(new RegExp(pattern, 'i'));
+    } catch (error) {
+      continue;
+    }
+  }
+
+  if (nodeTypes.length === 0 && refPrefixes.length === 0 && refRegexes.length === 0) {
+    return () => true;
+  }
+
+  return (node = {}) => {
+    const nodeType = normalizeNodeType(node.node_type || node.type);
+    const bindingRef = normalizeRef(node.binding_ref || node.ref);
+    const bindingRefLower = bindingRef.toLowerCase();
+
+    if (nodeTypes.length > 0 && !nodeTypes.includes(nodeType)) {
+      return false;
+    }
+
+    if (refPrefixes.length > 0) {
+      const matchedPrefix = refPrefixes.some((prefix) => bindingRefLower.startsWith(prefix));
+      if (!matchedPrefix) {
+        return false;
+      }
+    }
+
+    if (refRegexes.length > 0) {
+      const matchedRegex = refRegexes.some((regex) => regex.test(bindingRef));
+      if (!matchedRegex) {
+        return false;
+      }
+    }
+
+    return true;
+  };
+}
+
+function normalizeReadinessResult(rawResult, fallbackName) {
+  if (rawResult === true) {
+    return { ...DEFAULT_READINESS_SUCCESS, name: fallbackName };
+  }
+
+  if (rawResult === false) {
+    return {
+      passed: false,
+      reason: 'readiness-failed',
+      name: fallbackName
+    };
+  }
+
+  if (!isPlainObject(rawResult)) {
+    return { ...DEFAULT_READINESS_SUCCESS, name: fallbackName };
+  }
+
+  return {
+    name: rawResult.name || fallbackName,
+    passed: rawResult.passed !== false,
+    reason: rawResult.reason || (rawResult.passed === false ? 'readiness-failed' : 'ready'),
+    detail: rawResult.detail
+  };
+}
+
+class BindingRegistry {
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.moquiConfigPath = typeof options.moquiConfigPath === 'string' && options.moquiConfigPath.trim().length > 0
+      ? options.moquiConfigPath.trim()
+      : undefined;
+    this.useMoquiAdapter = options.useMoquiAdapter !== false;
+
+    this.handlers = [];
+    this.fallbackHandler = {
+      id: 'builtin.default',
+      matcher: () => true,
+      execute: async (node) => ({
+        status: 'success',
+        binding_ref: node.binding_ref,
+        provider: 'default'
+      }),
+      readiness: async () => ({ ...DEFAULT_READINESS_SUCCESS })
+    };
+
+    if (options.useDefaultHandlers !== false) {
+      this.registerDefaultHandlers();
+    }
+
+    if (Array.isArray(options.handlers)) {
+      for (const handler of options.handlers) {
+        this.register(handler);
+      }
+    }
+
+    if (options.fallbackHandler) {
+      this.setFallbackHandler(options.fallbackHandler);
+    }
+  }
+
+  registerDefaultHandlers() {
+    if (this.useMoquiAdapter) {
+      this.register(createMoquiAdapterHandler({
+        projectRoot: this.projectRoot,
+        configPath: this.moquiConfigPath,
+        allowSpecErpFallback: true
+      }));
+    }
+
+    this.register({
+      id: 'builtin.erp-sim',
+      match: { refPrefix: 'spec.erp.' },
+      execute: async (node) => ({
+        status: 'success',
+        provider: 'erp-sim',
+        binding_ref: node.binding_ref
+      })
+    });
+
+    this.register({
+      id: 'builtin.robot-sim',
+      match: { refPrefix: 'spec.robot.' },
+      execute: async (node) => ({
+        status: 'success',
+        provider: 'robot-sim',
+        binding_ref: node.binding_ref
+      }),
+      readiness: async (node, payload = {}) => {
+        const context = payload.context || {};
+        const safetyChecks = context.safetyChecks || {};
+
+        if (normalizeNodeType(node.node_type || node.type) !== 'adapter') {
+          return {
+            passed: true,
+            reason: 'not-adapter'
+          };
+        }
+
+        if (!safetyChecks.preflight) {
+          return {
+            passed: false,
+            reason: 'missing-preflight'
+          };
+        }
+
+        if (!safetyChecks.stopChannel) {
+          return {
+            passed: false,
+            reason: 'missing-stop-channel'
+          };
+        }
+
+        return {
+          passed: true,
+          reason: 'robot-safety-ready'
+        };
+      }
+    });
+
+    this.register({
+      id: 'builtin.adapter-sim',
+      match: { nodeType: 'adapter' },
+      execute: async (node) => ({
+        status: 'success',
+        provider: 'adapter-sim',
+        binding_ref: node.binding_ref
+      }),
+      readiness: async () => ({
+        passed: true,
+        reason: 'adapter-ready'
+      })
+    });
+  }
+
+  register(handler = {}) {
+    if (!isPlainObject(handler)) {
+      throw new Error('binding handler must be an object');
+    }
+
+    if (typeof handler.execute !== 'function') {
+      throw new Error('binding handler requires execute function');
+    }
+
+    const id = normalizeRef(handler.id) || `handler-${this.handlers.length + 1}`;
+    const matcher = createMatcher(handler.matcher || handler.match || null);
+
+    this.handlers.push({
+      ...handler,
+      id,
+      matcher
+    });
+
+    return id;
+  }
+
+  setFallbackHandler(handler = {}) {
+    if (!isPlainObject(handler) || typeof handler.execute !== 'function') {
+      throw new Error('fallback handler requires execute function');
+    }
+
+    this.fallbackHandler = {
+      ...handler,
+      id: normalizeRef(handler.id) || 'fallback',
+      matcher: () => true
+    };
+  }
+
+  resolve(node = {}, payload = {}) {
+    for (const handler of this.handlers) {
+      try {
+        if (handler.matcher(node, payload)) {
+          return handler;
+        }
+      } catch (error) {
+        continue;
+      }
+    }
+
+    return this.fallbackHandler;
+  }
+
+  async execute(node = {}, payload = {}) {
+    const handler = this.resolve(node, payload);
+    const rawResult = await handler.execute(node, payload);
+
+    if (!isPlainObject(rawResult)) {
+      return {
+        status: 'success',
+        output: rawResult,
+        handler_id: handler.id
+      };
+    }
+
+    return {
+      status: rawResult.status === 'failed' ? 'failed' : 'success',
+      ...rawResult,
+      handler_id: rawResult.handler_id || handler.id
+    };
+  }
+
+  async checkReadiness(sceneManifest = {}, payload = {}) {
+    const bindings = ((((sceneManifest || {}).spec || {}).capability_contract || {}).bindings) || [];
+    const checks = [];
+
+    for (const binding of bindings) {
+      const nodeType = normalizeNodeType(binding.type);
+      if (nodeType !== 'adapter') {
+        continue;
+      }
+
+      const node = {
+        node_type: nodeType,
+        binding_ref: binding.ref
+      };
+      const handler = this.resolve(node, payload);
+
+      if (typeof handler.readiness !== 'function') {
+        checks.push({
+          name: `adapter:${node.binding_ref}`,
+          passed: true,
+          reason: 'no-readiness-hook',
+          handler_id: handler.id
+        });
+        continue;
+      }
+
+      const readinessRaw = await handler.readiness(node, payload);
+      const readiness = normalizeReadinessResult(readinessRaw, `adapter:${node.binding_ref}`);
+      checks.push({
+        ...readiness,
+        handler_id: handler.id
+      });
+    }
+
+    return {
+      ready: checks.every((item) => item.passed !== false),
+      checks
+    };
+  }
+}
+
+module.exports = BindingRegistry;