fuli-context 0.2.0

package/src/setup/uninstall.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+
+import { stopLocalRuntime } from '../local-runtime/lifecycle.js';
+import { backupAgentConfig } from './config-backup.js';
+import { disconnectAgent, discoverAgents } from './agents.js';
+import { resolveSetupPaths } from './paths.js';
+import { removeBundledSkill } from './session-skill.js';
+
+export function planLocalUninstall(options, {
+  env = process.env,
+  resolvePaths = resolveSetupPaths,
+  discover = discoverAgents,
+  fileExists = existsSync
+} = {}) {
+  const paths = resolvePaths({ dataDir: options.dataDir, env });
+  const agents = discover({ env }).filter((agent) => (
+    agent.available ||
+    (agent.configPath && fileExists(agent.configPath)) ||
+    (agent.globalInstructionsPath && fileExists(agent.globalInstructionsPath)) ||
+    (agent.globalInstructionsOverridePath &&
+      fileExists(agent.globalInstructionsOverridePath)) ||
+    (agent.skillPath && fileExists(agent.skillPath)) ||
+    (agent.projectSkillPath && fileExists(agent.projectSkillPath))
+  ));
+  return { paths, agents };
+}
+
+export async function applyLocalUninstall(plan, dependencies = {}) {
+  const stopRuntime = dependencies.stopRuntime ?? stopLocalRuntime;
+  const backupConfig = dependencies.backupConfig ?? backupAgentConfig;
+  const disconnect = dependencies.disconnect ?? disconnectAgent;
+  const removeSkill = dependencies.removeSkill ?? removeBundledSkill;
+  let runtime;
+
+  try {
+    runtime = await stopRuntime({
+      paths: plan.paths,
+      port: dependencies.port,
+      env: dependencies.env ?? process.env
+    });
+  } catch (error) {
+    runtime = {
+      status: 'failed',
+      message: error instanceof Error ? error.message : 'Could not stop the local runtime'
+    };
+  }
+
+  const agents = plan.agents.map((agent) => {
+    const errors = [];
+    let backupPath = null;
+    let connection;
+    const skills = [];
+    try {
+      backupPath = backupConfig(agent, { backupDir: plan.paths.backupDir });
+      connection = disconnect(agent);
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : 'Agent disconnect failed');
+      connection = { status: 'failed' };
+    }
+
+    for (const [skillPath, sourcePath] of [
+      [agent.skillPath, plan.paths.sessionSkillPath],
+      [agent.projectSkillPath, plan.paths.projectSkillPath]
+    ]) {
+      try {
+        skills.push(removeSkill({ ...agent, skillPath }, { sourcePath }));
+      } catch (error) {
+        errors.push(error instanceof Error ? error.message : 'Skill removal failed');
+      }
+    }
+
+    return {
+      id: agent.id,
+      label: agent.label,
+      status: errors.length ? 'partial' : connection.status,
+      backupPath,
+      skills,
+      ...(errors.length ? { errors } : {})
+    };
+  });
+
+  const partial = runtime.status !== 'stopped' ||
+    agents.some(({ status }) => status === 'partial');
+  return {
+    status: partial ? 'partial' : 'ready',
+    runtime,
+    agents,
+    data: { status: 'preserved', path: plan.paths.dataDir }
+  };
+}

package/src/storage/episode-evidence-preview.js

@@ -0,0 +1,100 @@
+export const MAX_EPISODE_EVIDENCE_BODY_BYTES = 16 * 1024;
+export const MAX_EPISODE_METADATA_BYTES = 16 * 1024;
+export const MAX_EPISODE_METADATA_FIELD_BYTES = 2048;
+export const DEFAULT_CORRECTION_EVIDENCE_PER_FACT = 5;
+export const MAX_CORRECTION_EVIDENCE_PER_FACT = 20;
+
+export function normalizeEvidencePreviewOptions(options = {}) {
+  const maxBodyBytes = options.maxBodyBytes ?? MAX_EPISODE_EVIDENCE_BODY_BYTES;
+  if (
+    !Number.isInteger(maxBodyBytes) ||
+    maxBodyBytes < 0 ||
+    maxBodyBytes > MAX_EPISODE_EVIDENCE_BODY_BYTES
+  ) {
+    throw new TypeError(
+      `Episode evidence body limit must be between 0 and ${MAX_EPISODE_EVIDENCE_BODY_BYTES}`
+    );
+  }
+  return {
+    maxBodyBytes,
+    includeRestricted: options.includeRestricted === true
+  };
+}
+
+export function normalizeCorrectionEvidencePreviewOptions(options = {}) {
+  const normalized = normalizeEvidencePreviewOptions(options);
+  const maxCorrectionsPerFact = options.maxCorrectionsPerFact ??
+    DEFAULT_CORRECTION_EVIDENCE_PER_FACT;
+  if (
+    !Number.isInteger(maxCorrectionsPerFact) ||
+    maxCorrectionsPerFact < 1 ||
+    maxCorrectionsPerFact > MAX_CORRECTION_EVIDENCE_PER_FACT
+  ) {
+    throw new TypeError(
+      `Correction evidence limit must be between 1 and ${MAX_CORRECTION_EVIDENCE_PER_FACT}`
+    );
+  }
+  return { ...normalized, maxCorrectionsPerFact };
+}
+
+export function previewEpisode(episode, options, { correction = false } = {}) {
+  if (!episode) return null;
+  const { value: body, truncated: bodyTruncated } = clipUtf8(
+    episode.body,
+    options.maxBodyBytes
+  );
+  const metadata = correction
+    ? previewCorrectionMetadata(episode.metadata)
+    : previewSourceMetadata(episode.metadata);
+  const truncatedFields = [];
+  if (bodyTruncated || episode.bodyTruncated) truncatedFields.push('body');
+  if (metadata.truncated || episode.metadataTruncated) truncatedFields.push('metadata');
+
+  return {
+    id: episode.id,
+    spaceId: episode.spaceId,
+    sourceKind: episode.sourceKind,
+    body,
+    sourceUri: episode.sourceUri,
+    metadata: metadata.value,
+    createdAt: episode.createdAt,
+    truncatedFields
+  };
+}
+
+export function clipUtf8(value, maxBytes) {
+  const text = typeof value === 'string' ? value : '';
+  const encoded = Buffer.from(text, 'utf8');
+  if (encoded.length <= maxBytes) return { value: text, truncated: false };
+  let end = maxBytes;
+  while (end > 0 && (encoded[end] & 0xc0) === 0x80) end -= 1;
+  return { value: encoded.subarray(0, end).toString('utf8'), truncated: true };
+}
+
+function previewSourceMetadata(metadata) {
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    return { value: {}, truncated: metadata !== undefined };
+  }
+  const serialized = JSON.stringify(metadata);
+  if (Buffer.byteLength(serialized, 'utf8') > MAX_EPISODE_METADATA_BYTES) {
+    return { value: {}, truncated: true };
+  }
+  return { value: JSON.parse(serialized), truncated: false };
+}
+
+function previewCorrectionMetadata(metadata) {
+  const source = metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+    ? metadata
+    : {};
+  const value = {};
+  let truncated = Object.keys(source).some(
+    (key) => !['kind', 'factId', 'action'].includes(key)
+  );
+  for (const key of ['kind', 'factId', 'action']) {
+    if (typeof source[key] !== 'string') continue;
+    const clipped = clipUtf8(source[key], MAX_EPISODE_METADATA_FIELD_BYTES);
+    value[key] = clipped.value;
+    truncated ||= clipped.truncated;
+  }
+  return { value, truncated };
+}

package/src/storage/fact-search-order.js

@@ -0,0 +1,18 @@
+export function compareSearchFacts(left, right) {
+  return compareText(right.validAt, left.validAt) || compareText(left.id, right.id);
+}
+
+export function searchTextSortKey(value) {
+  const text = String(value ?? '');
+  const key = Buffer.allocUnsafe(text.length * 2);
+  for (let index = 0; index < text.length; index += 1) {
+    key.writeUInt16BE(text.charCodeAt(index), index * 2);
+  }
+  return key;
+}
+
+function compareText(left, right) {
+  const first = String(left ?? '');
+  const second = String(right ?? '');
+  return first === second ? 0 : (first < second ? -1 : 1);
+}

package/src/storage/file/episode-evidence.js

@@ -0,0 +1,37 @@
+import { isRestrictedEpisode } from '../../security/episode-visibility.js';
+import {
+  normalizeCorrectionEvidencePreviewOptions,
+  normalizeEvidencePreviewOptions,
+  previewEpisode
+} from '../episode-evidence-preview.js';
+
+export function fileEpisodeEvidencePreview(index, spaceId, episodeId, options = {}) {
+  const normalized = normalizeEvidencePreviewOptions(options);
+  const episode = index.get(episodeId);
+  if (!isVisibleEpisode(episode, spaceId, normalized.includeRestricted)) return null;
+  return previewEpisode(episode, normalized);
+}
+
+export function fileCorrectionEpisodeEvidencePreviews(
+  index,
+  spaceId,
+  factIds,
+  options = {}
+) {
+  const normalized = normalizeCorrectionEvidencePreviewOptions(options);
+  return index.correctionWindows(spaceId, factIds, {
+    includeRestricted: normalized.includeRestricted,
+    limit: normalized.maxCorrectionsPerFact
+  }).map((group) => ({
+    factId: group.factId,
+    episodes: group.episodes.map(
+      (episode) => previewEpisode(episode, normalized, { correction: true })
+    ),
+    truncated: group.truncated
+  }));
+}
+
+function isVisibleEpisode(episode, spaceId, includeRestricted) {
+  return episode?.spaceId === spaceId &&
+    (includeRestricted || !isRestrictedEpisode(episode));
+}

package/src/storage/file/episode-index.js

@@ -0,0 +1,59 @@
+import { isRestrictedEpisode } from '../../security/episode-visibility.js';
+
+export class FileEpisodeIndex {
+  #byId = new Map();
+  #correctionsBySpace = new Map();
+  #safeCorrectionsBySpace = new Map();
+
+  constructor(episodes) {
+    this.rebuild(episodes);
+  }
+
+  rebuild(episodes) {
+    this.#byId = new Map();
+    this.#correctionsBySpace = new Map();
+    this.#safeCorrectionsBySpace = new Map();
+    for (const episode of episodes) this.add(episode);
+  }
+
+  add(episode) {
+    this.#byId.set(episode.id, episode);
+    const factId = episode.metadata?.kind === 'lens_correction'
+      ? episode.metadata.factId
+      : null;
+    if (typeof factId !== 'string') return;
+
+    addCorrection(this.#correctionsBySpace, episode, factId);
+    if (!isRestrictedEpisode(episode)) {
+      addCorrection(this.#safeCorrectionsBySpace, episode, factId);
+    }
+  }
+
+  get(id) {
+    return this.#byId.get(id) ?? null;
+  }
+
+  correctionWindows(spaceId, factIds, { includeRestricted, limit }) {
+    const index = includeRestricted
+      ? this.#correctionsBySpace
+      : this.#safeCorrectionsBySpace;
+    const byFact = index.get(spaceId) ?? new Map();
+    return [...new Set(factIds)].map((factId) => {
+      const episodes = byFact.get(factId) ?? [];
+      return {
+        factId,
+        episodes: episodes.slice(Math.max(0, episodes.length - limit)).reverse(),
+        truncated: episodes.length > limit
+      };
+    });
+  }
+}
+
+function addCorrection(index, episode, factId) {
+  const byFact = index.get(episode.spaceId) ?? new Map();
+  const episodes = byFact.get(factId) ?? [];
+  episodes.push(episode);
+  episodes.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  byFact.set(factId, episodes);
+  index.set(episode.spaceId, byFact);
+}

package/src/storage/file/fact-search.js

@@ -0,0 +1,60 @@
+import { isCurrentFact } from '../../models.js';
+import { isRestrictedEpisode } from '../../security/episode-visibility.js';
+import { isRestrictedFact } from '../../security/fact-visibility.js';
+import { compareSearchFacts } from '../fact-search-order.js';
+
+export function searchFileFacts(facts, episodeIndex, spaceIds, query, options = {}) {
+  return searchFileFactsPage(facts, episodeIndex, spaceIds, query, options).facts;
+}
+
+export function searchFileFactsPage(facts, episodeIndex, spaceIds, query, options = {}) {
+  const search = {
+    includeHistorical: options.includeHistorical ?? false,
+    scope: options.scope ?? null,
+    limit: options.limit ?? null,
+    excludeRestricted: options.excludeRestricted === true,
+    safeSourceSpaceId: options.safeSourceSpaceId ?? null,
+    maxObjectBytes: options.maxObjectBytes ?? null,
+    query: query.toLowerCase()
+  };
+
+  if (search.limit !== null && (!Number.isInteger(search.limit) || search.limit <= 0)) {
+    throw new TypeError('Fact search limit must be a positive integer');
+  }
+
+  const selected = [];
+  let objectLimitTruncated = false;
+  for (const fact of facts) {
+    if (!matchesSearchWithoutObjectLimit(fact, episodeIndex, spaceIds, search)) continue;
+    if (
+      search.maxObjectBytes !== null &&
+      Buffer.byteLength(fact.object, 'utf8') > search.maxObjectBytes
+    ) {
+      objectLimitTruncated = true;
+      continue;
+    }
+    selected.push(fact);
+    if (search.limit === null) continue;
+    selected.sort(compareSearchFacts);
+    if (selected.length > search.limit) selected.pop();
+  }
+  return { facts: selected, objectLimitTruncated };
+}
+
+function matchesSearchWithoutObjectLimit(fact, episodeIndex, spaceIds, search) {
+  if (!spaceIds.includes(fact.spaceId)) return false;
+  if (search.scope !== null && fact.scope !== search.scope) return false;
+  if (!search.includeHistorical && !isCurrentFact(fact)) return false;
+  if (search.excludeRestricted && isRestrictedFact(fact)) return false;
+  if (search.safeSourceSpaceId !== null) {
+    const source = episodeIndex.get(fact.sourceEpisodeId);
+    if (
+      !source ||
+      source.spaceId !== search.safeSourceSpaceId ||
+      isRestrictedEpisode(source)
+    ) return false;
+  }
+  return `${fact.subject} ${fact.predicate} ${fact.object}`
+    .toLowerCase()
+    .includes(search.query);
+}