fuli-context 0.4.0 → 0.7.2

package/src/external-knowledge/index.js

@@ -0,0 +1,8 @@
+export { ExternalKnowledgeRegistry } from './registry.js';
+export { ExternalKnowledgeService } from './service.js';
+export { KnowledgeConflictPolicyStore } from './conflict-policy.js';
+export { ConnectedKnowledgeSearch } from './connected-search.js';
+export {
+  attachExternalKnowledgeRuntime,
+  openExternalKnowledgeRuntime
+} from './runtime.js';

package/src/external-knowledge/registry.js

@@ -0,0 +1,91 @@
+import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
+
+const CURRENT_VERSION = 2;
+const EMPTY_REGISTRY = Object.freeze({ version: CURRENT_VERSION, bindings: [] });
+
+export class ExternalKnowledgeRegistry {
+  constructor(filePath) {
+    if (typeof filePath !== 'string' || !filePath.trim()) {
+      throw new TypeError('External knowledge registry path is required');
+    }
+    this.filePath = filePath;
+  }
+
+  list() {
+    return clone(this.#read().bindings);
+  }
+
+  get(id) {
+    const binding = this.#read().bindings.find((item) => item.id === id);
+    return binding ? clone(binding) : null;
+  }
+
+  put(binding) {
+    const document = this.#read();
+    const index = document.bindings.findIndex((item) => item.id === binding.id);
+    if (index === -1) document.bindings.push(clone(binding));
+    else document.bindings[index] = clone(binding);
+    writeJsonFileAtomic(this.filePath, document);
+    return clone(binding);
+  }
+
+  delete(id) {
+    const document = this.#read();
+    const next = document.bindings.filter((item) => item.id !== id);
+    if (next.length === document.bindings.length) return false;
+    writeJsonFileAtomic(this.filePath, { ...document, bindings: next });
+    return true;
+  }
+
+  #read() {
+    const document = readJsonFile(this.filePath, EMPTY_REGISTRY);
+    if (!Array.isArray(document?.bindings)) {
+      throw new TypeError('Unsupported external knowledge registry format');
+    }
+    if (document.version === CURRENT_VERSION) return clone(document);
+    if (document.version === 1) return migrateVersionOne(document);
+    throw new TypeError('Unsupported external knowledge registry format');
+  }
+}
+
+function migrateVersionOne(document) {
+  return {
+    version: CURRENT_VERSION,
+    bindings: document.bindings.map((binding) => {
+      if (!binding?.target || typeof binding.target !== 'object') {
+        throw new TypeError('Legacy external knowledge binding target is invalid');
+      }
+      const {
+        target,
+        mode = 'hybrid',
+        sync = emptySyncState(),
+        ...source
+      } = binding;
+      return {
+        ...source,
+        targets: [{
+          id: binding.id,
+          personalSpaceId: target.personalSpaceId,
+          personalProjectId: target.personalProjectId,
+          mode,
+          status: binding.status ?? 'ready',
+          sync
+        }]
+      };
+    })
+  };
+}
+
+function emptySyncState() {
+  return {
+    cursor: null,
+    lastSyncedAt: null,
+    error: null,
+    skippedCredentials: 0,
+    items: {}
+  };
+}
+
+function clone(value) {
+  return structuredClone(value);
+}

package/src/external-knowledge/runtime.js

@@ -0,0 +1,68 @@
+import { mkdirSync } from 'node:fs';
+
+import { createConnectorCatalog } from './catalog.js';
+import { ConnectedKnowledgeSearch } from './connected-search.js';
+import { KnowledgeConflictPolicyStore } from './conflict-policy.js';
+import { ExternalKnowledgeRegistry } from './registry.js';
+import { ExternalKnowledgeService } from './service.js';
+
+export function openExternalKnowledgeRuntime({
+  app,
+  paths,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  mcpOpenSession,
+  sleep
+}) {
+  assertPaths(paths);
+  mkdirSync(paths.externalKnowledgeConnectorDir, { recursive: true });
+  const connectors = createConnectorCatalog({
+    customConnectorDirectory: paths.externalKnowledgeConnectorDir,
+    fetchImpl,
+    mcpOpenSession,
+    sleep
+  });
+  const externalKnowledge = new ExternalKnowledgeService({
+    app,
+    registry: new ExternalKnowledgeRegistry(paths.externalKnowledgeRegistryPath),
+    connectors,
+    env
+  });
+  const connectedKnowledge = new ConnectedKnowledgeSearch({
+    app,
+    externalKnowledge,
+    policies: new KnowledgeConflictPolicyStore(
+      paths.externalKnowledgeConflictPolicyPath
+    )
+  });
+  return { externalKnowledge, connectedKnowledge };
+}
+
+export function attachExternalKnowledgeRuntime(app, options) {
+  const runtime = openExternalKnowledgeRuntime({ app, ...options });
+  Object.defineProperties(app, {
+    externalKnowledge: {
+      configurable: true,
+      enumerable: false,
+      value: runtime.externalKnowledge
+    },
+    connectedKnowledge: {
+      configurable: true,
+      enumerable: false,
+      value: runtime.connectedKnowledge
+    }
+  });
+  return app;
+}
+
+function assertPaths(paths) {
+  for (const name of [
+    'externalKnowledgeRegistryPath',
+    'externalKnowledgeConflictPolicyPath',
+    'externalKnowledgeConnectorDir'
+  ]) {
+    if (typeof paths?.[name] !== 'string' || !paths[name]) {
+      throw new TypeError(`External knowledge path is required: ${name}`);
+    }
+  }
+}

package/src/external-knowledge/safe-diagnostic.js

@@ -0,0 +1,14 @@
+import { detectSensitiveContent } from '../security/sensitive-content.js';
+
+const PROTECTED_DIAGNOSTIC = 'External source failed; protected diagnostic omitted.';
+
+export function safeExternalSourceDiagnostic(reason) {
+  const message = reason instanceof Error ? reason.message : String(reason ?? '');
+  if (detectSensitiveContent(message).restricted) return PROTECTED_DIAGNOSTIC;
+  const normalized = message
+    .replace(/[\p{Cc}\p{Cf}\p{Cs}]+/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .slice(0, 1_000);
+  return normalized || 'External source failed without a diagnostic.';
+}