fuli-context 0.2.0

package/src/context-pack.js

@@ -0,0 +1,206 @@
+import { isCurrentFact } from './models.js';
+import { listCandidates } from './candidates.js';
+import { getProjectRules } from './project-rules.js';
+import { getFactHistory } from './fact-history.js';
+
+export function buildContextPack(store, { personalSpaceId, spaceId, query = '' }) {
+  const personalSpace = store.getSpace(personalSpaceId);
+  const space = store.getSpace(spaceId);
+  const scopedSpaceIds = [...new Set([personalSpaceId, spaceId])];
+  const matches = store
+    .searchFacts(scopedSpaceIds, query, { includeHistorical: false })
+    .map((fact) => compactMatch(store, fact));
+  const histories = buildHistories(store, matches);
+  const rules = compactRules(getProjectRules(store, spaceId), store);
+  const candidates = listCandidates(store, personalSpaceId)
+    .filter((candidate) => !candidate.targetSpaceId || candidate.targetSpaceId === spaceId)
+    .map(compactCandidate);
+
+  return {
+    query,
+    personalSpace: compactSpace(personalSpace, personalSpaceId),
+    space: compactSpace(space, spaceId),
+    rules,
+    matches,
+    histories,
+    candidateCount: candidates.length,
+    candidates,
+    answer: formatPackAnswer(matches)
+  };
+}
+
+export function formatContextPack(pack) {
+  const lines = [
+    `Context ${pack.personalSpace.name} -> ${pack.space.name}`,
+    `Query ${pack.query || '(empty)'}`,
+    'Rules',
+    ...formatRules(pack.rules),
+    'Matches',
+    ...formatMatches(pack.matches),
+    ...formatHistories(pack.histories),
+    `Candidates ${pack.candidateCount}`
+  ];
+
+  return lines.join('\n');
+}
+
+function compactRules(rules, store) {
+  return {
+    spaceId: rules.spaceId,
+    spaceName: rules.spaceName,
+    forbidden: rules.forbidden.map((fact) => compactFact(store, fact)),
+    parameters: rules.parameters.map((fact) => compactFact(store, fact)),
+    links: rules.links.map((fact) => compactFact(store, fact))
+  };
+}
+
+function compactFact(store, fact) {
+  return {
+    id: fact.id,
+    spaceId: fact.spaceId,
+    spaceName: store.getSpace(fact.spaceId)?.name ?? fact.spaceId,
+    subject: fact.subject,
+    predicate: fact.predicate,
+    object: fact.object,
+    current: isCurrentFact(fact),
+    validAt: fact.validAt,
+    invalidAt: fact.invalidAt,
+    source: compactSource(store, fact.sourceEpisodeId)
+  };
+}
+
+function compactMatch(store, fact) {
+  const compact = compactFact(store, fact);
+  return {
+    spaceId: compact.spaceId,
+    spaceName: compact.spaceName,
+    current: compact.current,
+    fact: {
+      id: compact.id,
+      spaceId: compact.spaceId,
+      subject: compact.subject,
+      predicate: compact.predicate,
+      object: compact.object,
+      validAt: compact.validAt,
+      invalidAt: compact.invalidAt
+    },
+    source: compact.source
+  };
+}
+
+function buildHistories(store, matches) {
+  const keys = new Set();
+  const histories = [];
+
+  for (const match of matches) {
+    const key = `${match.fact.spaceId}:${match.fact.predicate}`;
+    if (keys.has(key)) continue;
+    keys.add(key);
+
+    const history = getFactHistory(store, {
+      spaceId: match.fact.spaceId,
+      predicate: match.fact.predicate
+    });
+    if (history.facts.length <= 1) continue;
+
+    histories.push({
+      spaceId: history.spaceId,
+      spaceName: history.spaceName,
+      predicate: history.predicate,
+      facts: history.facts.map((fact) => compactFact(store, fact))
+    });
+  }
+
+  return histories;
+}
+
+function compactCandidate(candidate) {
+  return {
+    id: candidate.id,
+    reason: candidate.reason,
+    createdAt: candidate.createdAt,
+    targetSpaceId: candidate.targetSpaceId,
+    targetSpaceName: candidate.targetSpaceName,
+    source: candidate.episode
+      ? {
+          id: candidate.episode.id,
+          kind: candidate.episode.sourceKind,
+          uri: candidate.episode.sourceUri,
+          createdAt: candidate.episode.createdAt,
+          preview: firstLine(candidate.episode.body)
+        }
+      : null
+  };
+}
+
+function compactSource(store, episodeId) {
+  const episode = store.getEpisode(episodeId);
+  if (!episode) return null;
+
+  return {
+    id: episode.id,
+    kind: episode.sourceKind,
+    uri: episode.sourceUri,
+    createdAt: episode.createdAt,
+    preview: firstLine(episode.body)
+  };
+}
+
+function compactSpace(space, fallbackId) {
+  return {
+    id: space?.id ?? fallbackId,
+    name: space?.name ?? fallbackId,
+    kind: space?.kind ?? null
+  };
+}
+
+function firstLine(value) {
+  return String(value).split(/\r?\n/)[0].slice(0, 160);
+}
+
+function formatPackAnswer(matches) {
+  if (matches.length === 0) {
+    return 'No matching current facts found.';
+  }
+
+  return matches
+    .map((match) => `${match.fact.subject} ${match.fact.predicate} ${match.fact.object}`)
+    .join('\n');
+}
+
+function formatRules(rules) {
+  const lines = [
+    ...rules.forbidden.map((fact) => `forbids ${fact.object}`),
+    ...rules.parameters.map((fact) => `${humanPredicate(fact.predicate)} ${fact.object}`),
+    ...rules.links.map((fact) => `url ${fact.object}`)
+  ];
+
+  return lines.length ? lines : ['(none)'];
+}
+
+function formatMatches(matches) {
+  return matches.length
+    ? matches.map(
+        (match) =>
+          `${match.spaceName} ${humanPredicate(match.fact.predicate)} ${match.fact.object}`
+      )
+    : ['(none)'];
+}
+
+function formatHistories(histories) {
+  if (!histories?.length) return [];
+
+  return [
+    'History',
+    ...histories.flatMap((history) =>
+      history.facts.map(
+        (fact) =>
+          `${fact.current ? 'current' : 'historical'} ${humanPredicate(history.predicate)} ${fact.object}`
+      )
+    )
+  ];
+}
+
+function humanPredicate(predicate) {
+  return predicate.startsWith('has_') ? predicate.slice(4) : predicate;
+}

package/src/defaults.js

@@ -0,0 +1 @@
+export const DEFAULT_FULI_PORT = 2727;

package/src/extractor.js

@@ -0,0 +1,77 @@
+const URL_PATTERN = /https?:\/\/[^\s"'，。)）]+/g;
+
+export function extractFactSpecs(subject, body) {
+  const lines = body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const specs = [];
+
+  for (const line of lines) {
+    const replacement = parseReplacement(subject, line);
+    if (replacement) {
+      specs.push(replacement);
+      continue;
+    }
+
+    const forbidden = parseForbidden(subject, line);
+    if (forbidden) {
+      specs.push(forbidden);
+      continue;
+    }
+
+    const keyValue = parseKeyValue(subject, line);
+    if (keyValue) {
+      specs.push(keyValue);
+      continue;
+    }
+
+    for (const url of line.match(URL_PATTERN) ?? []) {
+      specs.push({ kind: 'fact', subject, predicate: 'has_url', object: url });
+    }
+  }
+
+  return specs;
+}
+
+function parseReplacement(subject, line) {
+  const match = line.match(/^替代[:：]\s*(.+?)\s*=>\s*(.+)$/);
+  if (!match) return null;
+
+  return {
+    kind: 'replacement',
+    subject,
+    oldValue: match[1].trim(),
+    newValue: match[2].trim()
+  };
+}
+
+function parseForbidden(subject, line) {
+  const match =
+    line.match(/^禁止[:：]\s*(.+)$/) ??
+    line.match(/^(?:这个项目|本项目|项目)?\s*(?:禁止|不要|不允许)\s*(?:使用|采用|引入|用)?\s*(.+)$/);
+  if (!match) return null;
+
+  return {
+    kind: 'fact',
+    subject,
+    predicate: 'forbids',
+    object: cleanForbiddenObject(match[1])
+  };
+}
+
+function cleanForbiddenObject(value) {
+  return value.trim().replace(/[。.!！,，;；]+$/g, '').trim();
+}
+
+function parseKeyValue(subject, line) {
+  const match = line.match(/^([\p{L}\p{N}_.-]+)\s*[:：]\s*(.+)$/u);
+  if (!match) return null;
+
+  return {
+    kind: 'fact',
+    subject,
+    predicate: `has_${match[1].trim()}`,
+    object: match[2].trim()
+  };
+}

package/src/fact-history.js

@@ -0,0 +1,39 @@
+import { isCurrentFact } from './models.js';
+
+export function getFactHistory(store, { spaceId, predicate }) {
+  const normalizedPredicate = normalizePredicate(predicate);
+  const facts = store.listFacts({ includeHistorical: true })
+    .filter((fact) => fact.spaceId === spaceId && fact.predicate === normalizedPredicate)
+    .sort((left, right) => left.validAt.localeCompare(right.validAt))
+    .map((fact) => enrichFact(store, fact));
+
+  return {
+    spaceId,
+    spaceName: store.getSpace(spaceId)?.name ?? spaceId,
+    predicate: normalizedPredicate,
+    facts
+  };
+}
+
+export function normalizePredicate(value) {
+  if (value.startsWith('has_') || value === 'forbids') return value;
+  return `has_${value}`;
+}
+
+function enrichFact(store, fact) {
+  const episode = store.getEpisode(fact.sourceEpisodeId);
+
+  return {
+    ...fact,
+    current: isCurrentFact(fact),
+    source: episode
+      ? {
+          id: episode.id,
+          kind: episode.sourceKind,
+          uri: episode.sourceUri,
+          body: episode.body,
+          createdAt: episode.createdAt
+        }
+      : null
+  };
+}

package/src/facts/fact-service.js

@@ -0,0 +1,89 @@
+import { FactScope, FactStatus } from '../models.js';
+
+export class FactService {
+  constructor(store) {
+    this.store = store;
+  }
+
+  writeSpecs({ spaceId, subject, episodeId, specs, scope = FactScope.PERSONAL }) {
+    const written = [];
+    for (const spec of specs) {
+      if (spec.kind === 'replacement') {
+        written.push(...this.#replaceFact({ spaceId, subject, episodeId, spec, scope }));
+        continue;
+      }
+
+      if (this.#hasCurrentFact(spaceId, subject, spec.predicate, spec.object)) continue;
+
+      const supersededFacts = this.#supersededCurrentFacts(
+        spaceId,
+        subject,
+        spec.predicate,
+        spec.object
+      );
+      const newFact = this.store.addFact({
+        spaceId,
+        subject,
+        predicate: spec.predicate,
+        object: spec.object,
+        sourceEpisodeId: episodeId,
+        status: FactStatus.CONFIRMED,
+        scope
+      });
+      written.push(newFact);
+
+      for (const oldFact of supersededFacts) {
+        this.store.invalidateFact(oldFact.id, newFact.id);
+      }
+    }
+    return written;
+  }
+
+  #hasCurrentFact(spaceId, subject, predicate, object) {
+    return this.store.currentFacts(spaceId).some(
+      (fact) =>
+        fact.subject === subject &&
+        fact.predicate === predicate &&
+        fact.object === object
+    );
+  }
+
+  #supersededCurrentFacts(spaceId, subject, predicate, object) {
+    if (!isUniqueParameterPredicate(predicate)) return [];
+
+    return this.store.currentFacts(spaceId).filter(
+      (fact) =>
+        fact.subject === subject &&
+        fact.predicate === predicate &&
+        fact.object !== object
+    );
+  }
+
+  #replaceFact({ spaceId, subject, episodeId, spec, scope }) {
+    const oldFacts = this.store.currentFacts(spaceId).filter(
+      (fact) => fact.subject === subject && fact.object === spec.oldValue
+    );
+    const predicates = oldFacts.length
+      ? [...new Set(oldFacts.map((fact) => fact.predicate))]
+      : ['has_replacement'];
+    const newFacts = predicates.map((predicate) => this.store.addFact({
+      spaceId,
+      subject,
+      predicate,
+      object: spec.newValue,
+      sourceEpisodeId: episodeId,
+      status: FactStatus.CONFIRMED,
+      scope
+    }));
+
+    for (const oldFact of oldFacts) {
+      const replacement = newFacts.find((fact) => fact.predicate === oldFact.predicate) ?? newFacts[0];
+      this.store.invalidateFact(oldFact.id, replacement.id);
+    }
+    return newFacts;
+  }
+}
+
+function isUniqueParameterPredicate(predicate) {
+  return predicate.startsWith('has_') && predicate !== 'has_url';
+}

package/src/graphiti/agent-access-policy.js

@@ -0,0 +1,88 @@
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+
+const DEFAULT_POLICY = Object.freeze({
+  enabled: true,
+  updatedAt: null
+});
+
+export class AgentAccessPolicyConfigurationError extends TypeError {}
+
+export class AgentAccessPolicyStore {
+  constructor(path = null, { now = () => new Date().toISOString() } = {}) {
+    this.path = path ? resolve(path) : null;
+    this.now = now;
+    this.memory = { ...DEFAULT_POLICY };
+  }
+
+  read() {
+    if (!this.path) return { ...this.memory };
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { ...DEFAULT_POLICY };
+      throw new AgentAccessPolicyConfigurationError(
+        'Agent access policy could not be read'
+      );
+    }
+    return validateStoredPolicy(parsed);
+  }
+
+  update(input) {
+    if (!input || typeof input.enabled !== 'boolean') {
+      throw new TypeError('Agent access policy enabled must be a boolean');
+    }
+    const next = {
+      enabled: input.enabled,
+      updatedAt: this.now()
+    };
+    if (!this.path) {
+      this.memory = next;
+      return { ...next };
+    }
+    writeAtomically(this.path, { version: 1, ...next });
+    return { ...next };
+  }
+}
+
+export function agentAccessPolicyPathForRuntime(runtimeConfigPath) {
+  if (!runtimeConfigPath) return null;
+  return join(dirname(resolve(runtimeConfigPath)), 'agent-access-policy.json');
+}
+
+function validateStoredPolicy(value) {
+  if (value?.version !== 1 || typeof value.enabled !== 'boolean') {
+    throw new AgentAccessPolicyConfigurationError('Agent access policy is invalid');
+  }
+  if (value.updatedAt !== null && typeof value.updatedAt !== 'string') {
+    throw new AgentAccessPolicyConfigurationError(
+      'Agent access policy updatedAt is invalid'
+    );
+  }
+  return {
+    enabled: value.enabled,
+    updatedAt: value.updatedAt ?? null
+  };
+}
+
+function writeAtomically(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600
+    });
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}

package/src/graphiti/capture-policy.js

@@ -0,0 +1,84 @@
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const DEFAULT_POLICY = Object.freeze({
+  enabled: true,
+  updatedAt: null
+});
+
+export class CapturePolicyConfigurationError extends TypeError {}
+
+export class CapturePolicyStore {
+  constructor(path = null, { now = () => new Date().toISOString() } = {}) {
+    this.path = path ? resolve(path) : null;
+    this.now = now;
+    this.memory = { ...DEFAULT_POLICY };
+  }
+
+  read() {
+    if (!this.path) return { ...this.memory };
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { ...DEFAULT_POLICY };
+      throw new CapturePolicyConfigurationError('Capture policy could not be read');
+    }
+    return validateStoredPolicy(parsed);
+  }
+
+  update(input) {
+    if (!input || typeof input.enabled !== 'boolean') {
+      throw new TypeError('Capture policy enabled must be a boolean');
+    }
+    const next = {
+      enabled: input.enabled,
+      updatedAt: this.now()
+    };
+    if (!this.path) {
+      this.memory = next;
+      return { ...next };
+    }
+    writeAtomically(this.path, { version: 1, ...next });
+    return { ...next };
+  }
+}
+
+export function capturePolicyPathForRuntime(runtimeConfigPath) {
+  if (!runtimeConfigPath) return null;
+  return join(dirname(resolve(runtimeConfigPath)), 'capture-policy.json');
+}
+
+function validateStoredPolicy(value) {
+  if (value?.version !== 1 || typeof value.enabled !== 'boolean') {
+    throw new CapturePolicyConfigurationError('Capture policy is invalid');
+  }
+  if (value.updatedAt !== null && typeof value.updatedAt !== 'string') {
+    throw new CapturePolicyConfigurationError('Capture policy updatedAt is invalid');
+  }
+  return {
+    enabled: value.enabled,
+    updatedAt: value.updatedAt ?? null
+  };
+}
+
+function writeAtomically(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600
+    });
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}