fuli-context 0.2.0

package/src/graphiti/personal-context.js

@@ -0,0 +1,29 @@
+const PERSONAL_PROJECT_SEARCH_BATCH_SIZE = 16;
+
+export function personalContextProjectIds(activeProjectId, contextProjectIds = []) {
+  const values = [activeProjectId, ...contextProjectIds]
+    .filter((value) => typeof value === 'string' && value.length > 0);
+  return [...new Set(values)];
+}
+
+export function personalProjectSearchBatches(projectIds) {
+  if (projectIds.length === 0) return [[]];
+  const batches = [];
+  for (let index = 0; index < projectIds.length; index += PERSONAL_PROJECT_SEARCH_BATCH_SIZE) {
+    batches.push(projectIds.slice(index, index + PERSONAL_PROJECT_SEARCH_BATCH_SIZE));
+  }
+  return batches;
+}
+
+export function scopedSearchItems(result, scope, providerUrl = null, defaultSpaceId = null) {
+  const project = (item) => ({
+    ...item,
+    scope,
+    providerUrl,
+    spaceId: item.space_id ?? defaultSpaceId
+  });
+  return {
+    facts: (result.facts ?? []).map(project),
+    entities: (result.entities ?? []).map(project)
+  };
+}

package/src/graphiti/project-path-context.js

@@ -0,0 +1,159 @@
+import {
+  existsSync,
+  readFileSync,
+  realpathSync,
+  statSync
+} from 'node:fs';
+import path from 'node:path';
+
+const CHILD_PROJECT_MARKERS = Object.freeze([
+  '.git',
+  'package.json',
+  'pyproject.toml',
+  'Cargo.toml',
+  'go.mod'
+]);
+
+export function resolvePersonalProjectPath(projectPath, projects, {
+  fileExists = existsSync,
+  isDirectory = defaultIsDirectory,
+  realPath = defaultRealPath,
+  readText = defaultReadText,
+  pathApi = path
+} = {}) {
+  if (projectPath === undefined || projectPath === null) {
+    return unresolved('not_provided');
+  }
+  if (
+    typeof projectPath !== 'string'
+    || !projectPath.trim()
+    || !pathApi.isAbsolute(projectPath)
+  ) {
+    throw new TypeError('projectPath must be an existing absolute directory');
+  }
+
+  const currentPath = realPath(pathApi.resolve(projectPath));
+  if (!fileExists(currentPath) || !isDirectory(currentPath)) {
+    throw new TypeError('projectPath must be an existing absolute directory');
+  }
+
+  const projectIds = new Set(
+    projects
+      .map(({ project_id: projectId }) => projectId)
+      .filter((projectId) => safeProjectId(projectId, pathApi))
+  );
+  const repositoryRoot = findRepositoryRoot(currentPath, {
+    fileExists,
+    pathApi
+  });
+  if (repositoryRoot) {
+    const repositoryId = pathApi.basename(repositoryRoot);
+    if (projectIds.has(repositoryId)) {
+      return matched(repositoryId, 'repository_root');
+    }
+    const worktreeId = worktreeOriginProjectId(
+      pathApi.join(repositoryRoot, '.git'),
+      { readText, pathApi }
+    );
+    if (worktreeId && projectIds.has(worktreeId)) {
+      return matched(worktreeId, 'git_worktree_origin');
+    }
+  }
+
+  const directoryId = pathApi.basename(currentPath);
+  if (projectIds.has(directoryId)) {
+    return matched(directoryId, 'directory_name');
+  }
+
+  const childMatches = [...projectIds].filter((projectId) => (
+    CHILD_PROJECT_MARKERS.some((marker) =>
+      fileExists(pathApi.join(currentPath, projectId, marker))
+    )
+  ));
+  if (childMatches.length === 1) {
+    return matched(childMatches[0], 'workspace_child');
+  }
+  if (childMatches.length > 1) {
+    return unresolved('ambiguous', { candidateCount: childMatches.length });
+  }
+  return unresolved('unmatched');
+}
+
+export function findRepositoryRoot(projectPath, {
+  fileExists = existsSync,
+  pathApi = path
+} = {}) {
+  let current = pathApi.resolve(projectPath);
+  const filesystemRoot = pathApi.parse(current).root;
+  while (true) {
+    if (fileExists(pathApi.join(current, '.git'))) return current;
+    if (current === filesystemRoot) return null;
+    const parent = pathApi.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function worktreeOriginProjectId(gitMarkerPath, {
+  readText,
+  pathApi
+}) {
+  const source = readText(gitMarkerPath);
+  const gitDirectory = /^gitdir:\s*(.+)$/im.exec(source)?.[1]?.trim();
+  if (!gitDirectory) return null;
+  const resolved = pathApi.isAbsolute(gitDirectory)
+    ? pathApi.normalize(gitDirectory)
+    : pathApi.resolve(pathApi.dirname(gitMarkerPath), gitDirectory);
+  const marker = /[\\/]\.git[\\/]worktrees[\\/]/i.exec(resolved);
+  if (!marker) return null;
+  return pathApi.basename(resolved.slice(0, marker.index));
+}
+
+function safeProjectId(projectId, pathApi) {
+  return typeof projectId === 'string'
+    && projectId.length > 0
+    && projectId !== '.'
+    && projectId !== '..'
+    && pathApi.basename(projectId) === projectId;
+}
+
+function matched(personalProjectId, basis) {
+  return {
+    status: 'matched',
+    basis,
+    personalProjectId
+  };
+}
+
+function unresolved(status, extra = {}) {
+  return {
+    status,
+    basis: null,
+    personalProjectId: null,
+    ...extra
+  };
+}
+
+function defaultReadText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function defaultIsDirectory(filePath) {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function defaultRealPath(filePath) {
+  try {
+    return realpathSync.native(filePath);
+  } catch {
+    return filePath;
+  }
+}

package/src/graphiti/provider-client.js

@@ -0,0 +1,288 @@
+import { ApplicationError } from '../app/application-error.js';
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const MAX_REQUEST_TIMEOUT_MS = 2_147_483_647;
+
+export class ProviderRequestError extends ApplicationError {
+  constructor(message, { status = 0, code = 'provider_error', details = null } = {}) {
+    super(code, message);
+    this.name = 'ProviderRequestError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class GraphitiProviderClient {
+  constructor({
+    baseUrl,
+    accessToken,
+    fetchImpl = globalThis.fetch,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
+  }) {
+    if (!baseUrl) throw new TypeError('Graphiti provider baseUrl is required');
+    if (!accessToken) throw new TypeError('Graphiti provider accessToken is required');
+    if (typeof fetchImpl !== 'function') throw new TypeError('fetch implementation is required');
+    if (!Number.isSafeInteger(requestTimeoutMs) ||
+        requestTimeoutMs < 1 ||
+        requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+      throw new TypeError('Graphiti provider timeout must be a positive safe integer');
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.accessToken = accessToken;
+    this.fetch = fetchImpl;
+    this.requestTimeoutMs = requestTimeoutMs;
+  }
+
+  health() { return this.#request('/health', { authenticated: false }); }
+  listSpaces() { return this.#request('/v1/spaces'); }
+  createSpace(input) { return this.#request('/v1/spaces', { method: 'POST', body: input }); }
+  listProjectReleases(projectId) {
+    return this.#request(`/v1/projects/${encodeURIComponent(projectId)}/releases`);
+  }
+  deleteProject(projectId) {
+    return this.#request(`/v1/projects/${encodeURIComponent(projectId)}`, { method: 'DELETE' });
+  }
+  upsertPersonalProject(input) {
+    return this.#request('/v1/personal-projects', { method: 'PUT', body: input });
+  }
+  listPersonalProjects(personalSpaceId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(`/v1/personal-projects?${query}`);
+  }
+  getPersonalProject(personalSpaceId, projectId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(
+      `/v1/personal-projects/${encodeURIComponent(projectId)}?${query}`
+    );
+  }
+  createPublicationDraft(input) {
+    return this.#request('/v1/publication-drafts', { method: 'POST', body: input });
+  }
+  listPublicationDrafts(personalSpaceId, status = 'pending') {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId, status });
+    return this.#request(`/v1/publication-drafts?${query}`);
+  }
+  getPublicationDraft(personalSpaceId, draftId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(
+      `/v1/publication-drafts/${encodeURIComponent(draftId)}?${query}`
+    );
+  }
+  decidePublicationDraft(personalSpaceId, draftId, input) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(
+      `/v1/publication-drafts/${encodeURIComponent(draftId)}/decision?${query}`,
+      { method: 'POST', body: input }
+    );
+  }
+  createPrincipal(input) {
+    return this.#request('/v1/principals', { method: 'POST', body: input });
+  }
+  addMember(projectId, input) {
+    return this.#request(`/v1/projects/${encodeURIComponent(projectId)}/members`, {
+      method: 'POST', body: input
+    });
+  }
+  createProjectRelation(projectId, input) {
+    return this.#request(`/v1/projects/${encodeURIComponent(projectId)}/relations`, {
+      method: 'POST', body: input
+    });
+  }
+  listProjectRelations(projectId) {
+    return this.#request(`/v1/projects/${encodeURIComponent(projectId)}/relations`);
+  }
+  decideProjectRelation(projectId, relationId, input) {
+    return this.#request(
+      `/v1/projects/${encodeURIComponent(projectId)}/relations/` +
+      `${encodeURIComponent(relationId)}/decision`,
+      { method: 'POST', body: input }
+    );
+  }
+  subscribe(input) {
+    return this.#request('/v1/subscriptions', { method: 'POST', body: input });
+  }
+  listSubscriptions(personalSpaceId) {
+    const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    return this.#request(`/v1/subscriptions?${query}`);
+  }
+  unsubscribe(personalSpaceId, projectId, providerUrl) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId,
+      provider_url: providerUrl
+    });
+    return this.#request(`/v1/subscriptions/${encodeURIComponent(projectId)}?${query}`, {
+      method: 'DELETE'
+    });
+  }
+  commit(input) {
+    return this.#request('/v1/knowledge/commits', { method: 'POST', body: input });
+  }
+  reviseKnowledgeItem(itemId, input) {
+    return this.#request(`/v1/knowledge/items/${encodeURIComponent(itemId)}`, {
+      method: 'PATCH', body: input
+    });
+  }
+  recordAgentViews(input) {
+    return this.#request('/v1/knowledge/agent-views', {
+      method: 'POST', body: input
+    });
+  }
+  recordKnowledgeUsage(input) {
+    return this.#request('/v1/knowledge/usage', {
+      method: 'POST', body: input
+    });
+  }
+  reviewHumanChange(itemId, input) {
+    return this.#request(
+      `/v1/knowledge/items/${encodeURIComponent(itemId)}/agent-review`,
+      { method: 'POST', body: input }
+    );
+  }
+  searchHumanChanges(input) {
+    return this.#request('/v1/knowledge/human-changes/search', {
+      method: 'POST', body: input
+    });
+  }
+  confirmKnowledgeBatch(input) {
+    return this.#request('/v1/knowledge/batch-confirmations', {
+      method: 'POST', body: input
+    });
+  }
+  reassignKnowledgeItem(itemId, input) {
+    return this.#request(
+      `/v1/knowledge/items/${encodeURIComponent(itemId)}/assignment`,
+      { method: 'POST', body: input }
+    );
+  }
+  setPreferenceScope(itemId, input) {
+    return this.#request(
+      `/v1/knowledge/items/${encodeURIComponent(itemId)}/preference-scope`,
+      { method: 'POST', body: input }
+    );
+  }
+  deferPreferenceConflict(input) {
+    return this.#request('/v1/preference-conflicts/defer', {
+      method: 'POST', body: input
+    });
+  }
+  listPreferenceConflicts(personalSpaceId, status = null, limit = 500) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId,
+      limit: String(limit)
+    });
+    if (status) query.set('status', status);
+    return this.#request(`/v1/preference-conflicts?${query}`);
+  }
+  resolvePreferenceConflict(conflictId, input) {
+    return this.#request(
+      `/v1/preference-conflicts/${encodeURIComponent(conflictId)}/resolve`,
+      { method: 'POST', body: input }
+    );
+  }
+  completePreferenceConflict(conflictId, input) {
+    return this.#request(
+      `/v1/preference-conflicts/${encodeURIComponent(conflictId)}/complete`,
+      { method: 'POST', body: input }
+    );
+  }
+  previewKnowledgeProjectAction(itemId, input) {
+    return this.#request(
+      `/v1/knowledge/items/${encodeURIComponent(itemId)}/project-action/preview`,
+      { method: 'POST', body: input }
+    );
+  }
+  applyKnowledgeProjectAction(itemId, input) {
+    return this.#request(
+      `/v1/knowledge/items/${encodeURIComponent(itemId)}/project-action`,
+      { method: 'POST', body: input }
+    );
+  }
+  createProposal(projectId, input) {
+    return this.#request(`/v1/projects/${encodeURIComponent(projectId)}/proposals`, {
+      method: 'POST', body: input
+    });
+  }
+  listProposals(projectId, status = 'pending') {
+    const query = new URLSearchParams({ status });
+    return this.#request(
+      `/v1/projects/${encodeURIComponent(projectId)}/proposals?${query}`
+    );
+  }
+  decideProposal(projectId, proposalId, input) {
+    return this.#request(
+      `/v1/projects/${encodeURIComponent(projectId)}/proposals/` +
+      `${encodeURIComponent(proposalId)}/decision`,
+      { method: 'POST', body: input }
+    );
+  }
+  search(input) { return this.#request('/v1/search', { method: 'POST', body: input }); }
+  collaborationPreferences(personalSpaceId, personalProjectId = null, limit = 100) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId,
+      limit: String(limit)
+    });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    return this.#request(`/v1/collaboration-preferences?${query}`);
+  }
+  graph(spaceId, limit = 500, personalProjectId = null) {
+    const query = new URLSearchParams({ limit: String(limit) });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
+    return this.#request(`/v1/spaces/${encodeURIComponent(spaceId)}/graph?${query}`);
+  }
+
+  async #request(path, {
+    method = 'GET',
+    body,
+    authenticated = true
+  } = {}) {
+    const headers = { accept: 'application/json' };
+    if (authenticated) headers.authorization = `Bearer ${this.accessToken}`;
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort(new Error('Graphiti provider request timed out'));
+    }, this.requestTimeoutMs);
+    const { signal } = controller;
+    let response;
+    let payload;
+    try {
+      response = await this.fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal
+      });
+      payload = await parseResponse(response);
+    } catch (error) {
+      throw new ProviderRequestError(
+        timedOut
+          ? 'Graphiti provider request timed out'
+          : 'Graphiti provider is unavailable',
+        {
+          status: timedOut ? 504 : 0,
+          code: timedOut ? 'provider_timeout' : 'provider_unavailable',
+          details: timedOut ? null : error instanceof Error ? error.message : null
+        }
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!response.ok) {
+      throw new ProviderRequestError(
+        typeof payload?.detail === 'string' ? payload.detail : 'Graphiti provider request failed',
+        { status: response.status, details: payload }
+      );
+    }
+    return payload;
+  }
+}
+
+async function parseResponse(response) {
+  const type = response.headers.get('content-type') ?? '';
+  if (type.includes('application/json')) return response.json();
+  const text = await response.text();
+  return text ? { detail: text } : null;
+}

package/src/graphiti/runtime-config.js

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { resolveSetupPaths } from '../setup/paths.js';
+
+export class GraphRuntimeConfigurationError extends TypeError {}
+
+export function resolveGraphRuntimeOptions(args = [], env = process.env, options = {}) {
+  const configuredPath = runtimeValue(args, '--runtime-config') ??
+    nonEmpty(env.FULI_GRAPH_RUNTIME_CONFIG);
+  const dataDir = resolveSetupPaths({ env, ...options.setupPaths }).dataDir;
+  return {
+    runtimeConfigPath: resolve(configuredPath ?? join(dataDir, 'graph-runtime.json'))
+  };
+}
+
+export function readGraphRuntimeConfig(path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new GraphRuntimeConfigurationError(
+      `Graphiti runtime is not configured. Run: node src/graphiti/setup.js`
+    );
+  }
+  validateConfig(parsed);
+  return parsed;
+}
+
+function validateConfig(config) {
+  if (config?.version !== 1) fail('unsupported graph runtime config version');
+  provider(config.personal, 'personal');
+  if (!config.personal.spaceId) fail('personal.spaceId is required');
+  if (!Array.isArray(config.workspaces)) fail('workspaces must be an array');
+  for (const [index, workspace] of config.workspaces.entries()) {
+    provider(workspace, `workspaces[${index}]`);
+  }
+}
+
+function provider(value, label) {
+  if (!value || typeof value !== 'object') fail(`${label} is required`);
+  for (const property of ['providerUrl', 'accessToken', 'principalId']) {
+    if (!nonEmpty(value[property])) fail(`${label}.${property} is required`);
+  }
+  value.providerUrl = canonicalProviderUrl(value.providerUrl);
+}
+
+export function canonicalProviderUrl(value) {
+  const normalized = String(value).replace(/\/$/, '');
+  let url;
+  try {
+    url = new URL(normalized);
+  } catch {
+    fail('provider URL is invalid');
+  }
+  const loopback = ['127.0.0.1', 'localhost', '::1'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    fail('provider URL must use HTTPS or loopback HTTP');
+  }
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    fail('provider URL must contain only scheme, host, and optional port');
+  }
+  return normalized;
+}
+
+function runtimeValue(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!nonEmpty(value) || value.startsWith('--')) {
+    throw new GraphRuntimeConfigurationError(`Missing value for ${flag}`);
+  }
+  if (args.indexOf(flag, index + 1) !== -1) {
+    throw new GraphRuntimeConfigurationError(`Duplicate ${flag}`);
+  }
+  return value;
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function fail(message) {
+  throw new GraphRuntimeConfigurationError(message);
+}

package/src/graphiti/setup.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+
+import { DEFAULT_FULI_PORT } from '../defaults.js';
+import { ensureGraphRuntime } from '../setup/graph-runtime.js';
+import { resolveSetupPaths } from '../setup/paths.js';
+
+export async function main(args = process.argv.slice(2), env = process.env) {
+  const paths = resolveSetupPaths({ dataDir: option(args, '--data-dir'), env });
+  const result = await ensureGraphRuntime({
+    paths,
+    personalSpaceName: option(args, '--personal-space') ?? '我',
+    port: numberOption(args, '--port', DEFAULT_FULI_PORT),
+    personalOnly: args.includes('--personal-only'),
+    noStart: args.includes('--no-start')
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+function option(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) throw new TypeError(`Missing value for ${flag}`);
+  return value;
+}
+
+function numberOption(args, flag, fallback) {
+  const value = option(args, flag);
+  if (value === null) return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new TypeError(`${flag} must be a positive integer`);
+  }
+  return parsed;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}