fuli-context 0.2.0

package/src/cli/local-runtime-options.js

@@ -0,0 +1,64 @@
+import { DEFAULT_FULI_PORT } from '../defaults.js';
+
+const VALUE_OPTIONS = Object.freeze({
+  '--data-dir': 'dataDir',
+  '--personal-space': 'personalSpaceName',
+  '--port': 'port'
+});
+
+const BOOLEAN_OPTIONS = Object.freeze({
+  '--open': 'open',
+  '--rebuild': 'rebuild',
+  '--json': 'json'
+});
+
+const ALLOWED_BY_COMMAND = Object.freeze({
+  start: new Set(['--data-dir', '--personal-space', '--port', '--open', '--rebuild']),
+  stop: new Set(['--data-dir']),
+  restart: new Set(['--data-dir', '--personal-space', '--port', '--open', '--rebuild']),
+  status: new Set(['--data-dir', '--port', '--json']),
+  open: new Set(['--data-dir'])
+});
+
+export function parseLocalRuntimeOptions(command, args = []) {
+  const allowed = ALLOWED_BY_COMMAND[command];
+  if (!allowed) throw new TypeError(`Unknown local runtime command: ${command}`);
+  const result = {
+    dataDir: null,
+    personalSpaceName: '我',
+    port: DEFAULT_FULI_PORT,
+    open: false,
+    rebuild: false,
+    json: false
+  };
+  const seen = new Set();
+
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index];
+    if (!allowed.has(flag)) throw new TypeError(`Unknown ${command} option: ${flag}`);
+    if (seen.has(flag)) throw new TypeError(`Duplicate ${flag}`);
+    seen.add(flag);
+
+    const booleanKey = BOOLEAN_OPTIONS[flag];
+    if (booleanKey) {
+      result[booleanKey] = true;
+      continue;
+    }
+    const valueKey = VALUE_OPTIONS[flag];
+    const value = args[index + 1];
+    if (!valueKey || typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new TypeError(`Missing value for ${flag}`);
+    }
+    result[valueKey] = valueKey === 'port' ? parsePort(value) : value.trim();
+    index += 1;
+  }
+  return result;
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new TypeError('--port must be between 1 and 65535');
+  }
+  return port;
+}

package/src/cli/migrate-command.js

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+
+import {
+  applyPreparedJsonSnapshot,
+  prepareJsonSnapshot
+} from '../storage/import-json.js';
+import { SqliteStore } from '../storage/sqlite-store.js';
+import {
+  cleanupMigrationDestination,
+  planMigrationDestination,
+  publishMigrationDestination
+} from './migration-destination.js';
+
+export function migrateLegacyJson(args, { createStore = (path) => new SqliteStore(path) } = {}) {
+  const sourcePath = option(args, '--from');
+  const destinationPath = option(args, '--to');
+  if (!sourcePath || !destinationPath) throw new Error('migrate requires --from and --to');
+
+  const snapshot = readSnapshot(sourcePath);
+  const prepared = prepareJsonSnapshot(snapshot, sourcePath);
+  const destination = planMigrationDestination(destinationPath);
+  const replace = args.includes('--replace');
+  let store;
+  let result;
+  let failure;
+  try {
+    store = createStore(destination.storePath);
+    result = applyPreparedJsonSnapshot(store, prepared, { replace });
+  } catch (error) {
+    failure = error;
+  } finally {
+    try {
+      store?.close();
+    } catch (error) {
+      failure ??= error;
+    }
+  }
+  if (!failure) {
+    try {
+      publishMigrationDestination(destination);
+    } catch (error) {
+      failure = error;
+    }
+  }
+  try {
+    cleanupMigrationDestination(destination);
+  } catch (error) {
+    failure ??= error;
+  }
+  if (failure) throw failure;
+  return result;
+}
+
+function readSnapshot(sourcePath) {
+  let source;
+  try {
+    source = readFileSync(sourcePath, 'utf8');
+  } catch (error) {
+    throw new Error(`Unable to read ${sourcePath}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${sourcePath}: ${error.message}`);
+  }
+}
+
+function option(args, flag) {
+  const index = args.indexOf(flag);
+  return index === -1 ? null : args[index + 1] ?? null;
+}

package/src/cli/migration-destination.js

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+import {
+  closeSync,
+  existsSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  rmdirSync,
+  unlinkSync
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export function planMigrationDestination(destinationPath) {
+  const destination = resolve(destinationPath);
+  if (existsSync(destination)) {
+    return {
+      destination,
+      storePath: destination,
+      ownsStorePath: false,
+      createdParents: []
+    };
+  }
+
+  const parent = dirname(destination);
+  const createdParents = createParents(parent);
+  try {
+    return {
+      destination,
+      storePath: reserveTemporaryPath(destination),
+      ownsStorePath: true,
+      createdParents
+    };
+  } catch (error) {
+    removeEmptyParents(createdParents);
+    throw error;
+  }
+}
+
+export function publishMigrationDestination(plan) {
+  if (!plan.ownsStorePath) return;
+
+  try {
+    linkSync(plan.storePath, plan.destination);
+  } catch (error) {
+    if (existsSync(plan.destination)) {
+      throw new Error(
+        `Migration destination appeared while the import was running: ${plan.destination}`,
+        { cause: error }
+      );
+    }
+    throw new Error(`Unable to publish migrated SQLite database: ${error.message}`, {
+      cause: error
+    });
+  }
+}
+
+export function cleanupMigrationDestination(plan) {
+  if (!plan.ownsStorePath) return;
+
+  const errors = [];
+  for (const artifact of ownedArtifacts(plan.storePath)) {
+    try {
+      unlinkSync(artifact);
+    } catch (error) {
+      if (error.code !== 'ENOENT') errors.push(error);
+    }
+  }
+  removeEmptyParents(plan.createdParents, errors);
+
+  if (errors.length > 0) {
+    throw new AggregateError(errors, `Unable to clean migration temporary database: ${plan.storePath}`);
+  }
+}
+
+function reserveTemporaryPath(destination) {
+  const temporaryPath = join(
+    dirname(destination),
+    `.${basename(destination)}.${randomUUID()}.migration`
+  );
+  const descriptor = openSync(temporaryPath, 'wx');
+  closeSync(descriptor);
+  return temporaryPath;
+}
+
+function createParents(parent) {
+  const firstCreated = mkdirSync(parent, { recursive: true });
+  if (firstCreated === undefined) return [];
+
+  const parents = [];
+  const boundary = comparablePath(firstCreated);
+  let current = parent;
+  while (true) {
+    parents.push(current);
+    if (comparablePath(current) === boundary) return parents;
+    current = dirname(current);
+  }
+}
+
+function removeEmptyParents(parents, errors = []) {
+  for (const parent of parents) {
+    try {
+      if (readdirSync(parent).length === 0) rmdirSync(parent);
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTEMPTY') errors.push(error);
+    }
+  }
+}
+
+function ownedArtifacts(storePath) {
+  return [`${storePath}-wal`, `${storePath}-shm`, storePath];
+}
+
+function comparablePath(path) {
+  const resolved = resolve(path).replace(/^\\\\\?\\/, '');
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}

package/src/cli/setup-agent-selection.js

@@ -0,0 +1,195 @@
+import { emitKeypressEvents } from 'node:readline';
+import { createInterface } from 'node:readline/promises';
+
+const HIDE_CURSOR = '\u001B[?25l';
+const SHOW_CURSOR = '\u001B[?25h';
+
+export function shouldPromptForAgentSelection(plan, options) {
+  if (options.yes || options.skipAgents || options.codexOnly) return false;
+  return availableAgents(plan).length > 1;
+}
+
+export function applyAgentSelection(plan, selectedAgentIds) {
+  const selected = new Set(selectedAgentIds);
+  return {
+    ...plan,
+    agents: plan.agents.map((agent) => ({
+      ...agent,
+      selected: agent.available && selected.has(agent.id)
+    }))
+  };
+}
+
+export function parseAgentSelection(value, agents) {
+  const answer = value.trim();
+  if (!answer) return agents.map(({ id }) => id);
+  if (answer === '0') return [];
+
+  const tokens = answer.split(/[\s,，]+/).filter(Boolean);
+  if (tokens.includes('0')) {
+    throw new TypeError('0 不能与其他编号同时使用');
+  }
+  if (tokens.some((token) => !/^\d+$/.test(token))) {
+    throw new TypeError('请输入编号，不要输入 Agent 名称');
+  }
+
+  const positions = new Set(tokens.map(Number));
+  if ([...positions].some((position) => position < 1 || position > agents.length)) {
+    throw new RangeError(`可选范围是 1-${agents.length}`);
+  }
+  return agents
+    .filter((_, index) => positions.has(index + 1))
+    .map(({ id }) => id);
+}
+
+export function createAgentSelectionState(agents) {
+  return {
+    activeIndex: 0,
+    selected: agents.map(() => true)
+  };
+}
+
+export function handleAgentSelectionKey(state, key) {
+  if (key.ctrl && key.name === 'c') return { action: 'cancel', state };
+  if (key.name === 'return' || key.name === 'enter') return { action: 'submit', state };
+
+  if (key.name === 'up' || key.name === 'down') {
+    const direction = key.name === 'up' ? -1 : 1;
+    const activeIndex = (
+      state.activeIndex + direction + state.selected.length
+    ) % state.selected.length;
+    return { action: 'update', state: { ...state, activeIndex } };
+  }
+
+  if (key.name === 'space' || key.name === ' ') {
+    const selected = [...state.selected];
+    selected[state.activeIndex] = !selected[state.activeIndex];
+    return { action: 'update', state: { ...state, selected } };
+  }
+
+  if (key.name === 'a') {
+    const nextValue = !state.selected.every(Boolean);
+    return {
+      action: 'update',
+      state: { ...state, selected: state.selected.map(() => nextValue) }
+    };
+  }
+
+  return { action: 'ignore', state };
+}
+
+export function selectedAgentIds(agents, state) {
+  return agents
+    .filter((_, index) => state.selected[index])
+    .map(({ id }) => id);
+}
+
+export function formatAgentCheckboxSelection(agents, state) {
+  return [
+    '检测到多个可接入的 Agent：',
+    ...agents.map((agent, index) => {
+      const pointer = index === state.activeIndex ? '❯' : ' ';
+      const checkbox = state.selected[index] ? '[x]' : '[ ]';
+      const status = integrationStatusLabel(agent.integrationStatus);
+      return `${pointer} ${checkbox} ${agent.label}${status ? `  ${status}` : ''}`;
+    }),
+    '↑/↓ 移动 · 空格切换 · A 全选/清空 · 回车确认'
+  ].join('\n');
+}
+
+function integrationStatusLabel(status) {
+  if (status === 'connected') return '已接入';
+  if (status === 'update_available') return '需更新';
+  if (status === 'not_connected') return '未接入';
+  return '';
+}
+
+export async function promptAgentSelection(agents, {
+  input = process.stdin,
+  output = process.stdout
+} = {}) {
+  if (supportsCheckboxSelection(input, output)) {
+    return promptCheckboxAgentSelection(agents, { input, output });
+  }
+  return promptTextAgentSelection(agents, { input, output });
+}
+
+async function promptCheckboxAgentSelection(agents, { input, output }) {
+  let state = createAgentSelectionState(agents);
+  const lineCount = agents.length + 2;
+  const wasPaused = typeof input.isPaused === 'function' && input.isPaused();
+  const wasRaw = input.isRaw === true;
+  emitKeypressEvents(input);
+  if (!wasRaw) input.setRawMode(true);
+  input.resume();
+  output.write(HIDE_CURSOR);
+  output.write(formatAgentCheckboxSelection(agents, state));
+
+  return new Promise((resolve, reject) => {
+    const finish = (callback) => {
+      input.off('keypress', onKeypress);
+      if (!wasRaw) input.setRawMode(false);
+      if (wasPaused) input.pause();
+      output.write(`${SHOW_CURSOR}\n`);
+      callback();
+    };
+    const redraw = () => {
+      output.write(`\r\u001B[${lineCount - 1}A\u001B[J`);
+      output.write(formatAgentCheckboxSelection(agents, state));
+    };
+    const onKeypress = (character, key = {}) => {
+      const result = handleAgentSelectionKey(state, {
+        ...key,
+        name: key.name ?? character
+      });
+      if (result.action === 'submit') {
+        finish(() => resolve(selectedAgentIds(agents, state)));
+        return;
+      }
+      if (result.action === 'cancel') {
+        finish(() => reject(new Error('Setup 已取消')));
+        return;
+      }
+      if (result.action === 'update') {
+        state = result.state;
+        redraw();
+      }
+    };
+    input.on('keypress', onKeypress);
+  });
+}
+
+async function promptTextAgentSelection(agents, { input, output }) {
+  const terminal = createInterface({ input, output });
+  output.write('检测到多个可接入的 Agent：\n');
+  for (const [index, agent] of agents.entries()) {
+    output.write(`  ${index + 1}. ${agent.label}\n`);
+  }
+
+  try {
+    while (true) {
+      const answer = await terminal.question(
+        '选择要接入的 Agent（编号以逗号分隔，回车全选，0 跳过）[全部] '
+      );
+      try {
+        return parseAgentSelection(answer, agents);
+      } catch (error) {
+        output.write(`选择无效：${error.message}\n`);
+      }
+    }
+  } finally {
+    terminal.close();
+  }
+}
+
+function supportsCheckboxSelection(input, output) {
+  return Boolean(
+    input.isTTY &&
+    output.isTTY &&
+    typeof input.setRawMode === 'function'
+  );
+}
+
+function availableAgents(plan) {
+  return plan.agents.filter(({ available }) => available);
+}

package/src/cli/setup-command.js

@@ -0,0 +1,85 @@
+import { createInterface } from 'node:readline/promises';
+
+import {
+  applyAgentSelection,
+  promptAgentSelection,
+  shouldPromptForAgentSelection
+} from './setup-agent-selection.js';
+import { parseSetupOptions } from '../setup/options.js';
+import { applyLocalSetup, planLocalSetup } from '../setup/setup.js';
+
+export async function runSetupCommand(args, dependencies = {}) {
+  const options = parseSetupOptions(args);
+  const planSetup = dependencies.planSetup ?? planLocalSetup;
+  const applySetup = dependencies.applySetup ?? applyLocalSetup;
+  const confirm = dependencies.confirm ?? confirmInTerminal;
+  const selectAgents = dependencies.selectAgents ?? promptAgentSelection;
+  const write = dependencies.write ?? writeLine;
+  let plan = planSetup(options, dependencies);
+  if (shouldPromptForAgentSelection(plan, options)) {
+    const detected = plan.agents.filter(({ available }) => available);
+    plan = applyAgentSelection(plan, await selectAgents(detected));
+  }
+  write(formatSetupPreview(plan, options));
+
+  if (!options.yes && !await confirm()) {
+    write('已取消，没有修改任何内容。');
+    return { status: 'cancelled' };
+  }
+
+  const result = await applySetup(plan, options, {
+    ...dependencies,
+    onProgress: write
+  });
+  write(formatSetupResult(result, plan));
+  return result;
+}
+
+export function formatSetupPreview(plan, options) {
+  const available = plan.agents.filter(({ available }) => available);
+  const selected = available.filter(({ selected }) => selected !== false);
+  const agentSummary = options.skipAgents || (available.length > 0 && selected.length === 0)
+    ? '跳过接入'
+    : selected.map(({ label }) => label).join('、') || '未检测到';
+  return [
+    '准备设置复利',
+    options.personalOnly
+      ? '存储：仅个人：本机 Graphiti / Neo4j'
+      : '存储：本机 Graphiti / Neo4j + 团队共享项目 Provider',
+    '容器运行时：自动检测；已安装但未运行时会自动启动',
+    `公共服务：${options.personalOnly ? '暂不连接' : '连接本机开发 Provider'}`,
+    `个人空间：${options.personalSpaceName}`,
+    `本地控制台：${options.noStart ? '暂不启动' : `http://127.0.0.1:${options.port}`}`,
+    `Agent：${agentSummary}`
+  ].join('\n');
+}
+
+export function formatSetupResult(result, plan) {
+  const lines = [result.status === 'ready' ? '复利已准备好。' : '复利已启动，但有 Agent 未连接。'];
+  if (result.runtime.url) lines.push(`打开：${result.runtime.url}`);
+  lines.push('知识存储：Graphiti / Neo4j');
+  for (const agent of result.agents) {
+    if (agent.status !== 'connected') {
+      lines.push(`${agent.label}：连接失败，请稍后重试 setup`);
+      continue;
+    }
+    lines.push(agent.newTaskRequired
+      ? `${agent.label}：已连接；请新建或重新打开一个任务以加载新配置`
+      : `${agent.label}：已连接`);
+  }
+  return lines.join('\n');
+}
+
+async function confirmInTerminal() {
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await input.question('只会修改以上内容，继续？[Y/n] ')).trim().toLowerCase();
+    return answer === '' || answer === 'y' || answer === 'yes';
+  } finally {
+    input.close();
+  }
+}
+
+function writeLine(value) {
+  process.stdout.write(`${value}\n`);
+}

package/src/cli/uninstall-command.js

@@ -0,0 +1,67 @@
+import { createInterface } from 'node:readline/promises';
+
+import { FULI_PACKAGE_NAME } from '../package-metadata.js';
+import { parseUninstallOptions } from '../setup/options.js';
+import { applyLocalUninstall, planLocalUninstall } from '../setup/uninstall.js';
+
+export async function runUninstallCommand(args, dependencies = {}) {
+  const options = parseUninstallOptions(args);
+  const planUninstall = dependencies.planUninstall ?? planLocalUninstall;
+  const applyUninstall = dependencies.applyUninstall ?? applyLocalUninstall;
+  const confirm = dependencies.confirm ?? confirmInTerminal;
+  const write = dependencies.write ?? writeLine;
+  const plan = planUninstall(options, dependencies);
+  write(formatUninstallPreview(plan));
+
+  if (!options.yes && !await confirm()) {
+    write('已取消，没有修改任何内容。');
+    return { status: 'cancelled' };
+  }
+
+  const result = await applyUninstall(plan, dependencies);
+  write(formatUninstallResult(result));
+  return result;
+}
+
+export function formatUninstallPreview(plan) {
+  const labels = plan.agents.map(({ label }) => label).join('、') || '无';
+  return [
+    '准备清理复利的本机接入',
+    '本地服务：停止',
+    `Agent 接入：${labels}`,
+    'Skills：仅删除与当前安装包完全一致的副本；有本地修改的会保留',
+    `数据：保留 ${plan.paths.dataDir}`,
+    'Neo4j 数据卷：保留'
+  ].join('\n');
+}
+
+export function formatUninstallResult(result) {
+  const lines = [
+    result.status === 'ready' ? '复利本机接入已清理。' : '复利本机接入未完全清理。',
+    `数据已保留：${result.data.path}`,
+    `最后移除全局命令：npm uninstall --global ${FULI_PACKAGE_NAME}`
+  ];
+  if (result.runtime.status !== 'stopped') {
+    lines.push(`本地服务：${result.runtime.message ?? '未能安全确认已停止'}`);
+  }
+  for (const agent of result.agents) {
+    const modified = agent.skills.some(({ status }) => status === 'preserved_modified');
+    if (modified) lines.push(`${agent.label}：保留了有本地修改的 Skill`);
+    if (agent.errors?.length) lines.push(`${agent.label}：${agent.errors.join('；')}`);
+  }
+  return lines.join('\n');
+}
+
+async function confirmInTerminal() {
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await input.question('继续清理本机接入？[y/N] ')).trim().toLowerCase();
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    input.close();
+  }
+}
+
+function writeLine(value) {
+  process.stdout.write(`${value}\n`);
+}

package/src/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  dispatchCommand,
+  isLocalRuntimeCommand,
+  isRegisteredCommand,
+  printHelp
+} from './cli/command-registry.js';
+import { parseCliInvocation } from './cli/invocation.js';
+import { runLocalRuntimeCommand } from './cli/local-runtime-command.js';
+import { migrateLegacyJson } from './cli/migrate-command.js';
+import { runSetupCommand } from './cli/setup-command.js';
+import { runUninstallCommand } from './cli/uninstall-command.js';
+import { FULI_VERSION } from './package-metadata.js';
+import { assertSupportedNodeVersion } from './setup/node-runtime.js';
+import {
+  openLocalApplication,
+  resolveRuntimeOptions
+} from './runtime-options.js';
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const { runtimeArgs, command, args: commandArgs } = parseCliInvocation(argv);
+  if (!command || command === '--help' || command === '-h') {
+    if (runtimeArgs.length) resolveRuntimeOptions(runtimeArgs, {});
+    printHelp();
+    return;
+  }
+  if (command === '--version' || command === '-v') {
+    if (runtimeArgs.length) resolveRuntimeOptions(runtimeArgs, {});
+    console.log(FULI_VERSION);
+    return;
+  }
+  if (command === 'migrate') {
+    if (runtimeArgs.length) resolveRuntimeOptions(runtimeArgs, {});
+    console.log(JSON.stringify(migrateLegacyJson(commandArgs)));
+    return;
+  }
+  if (command === 'setup') {
+    if (runtimeArgs.length) {
+      throw new TypeError('Setup options must appear after the setup command');
+    }
+    assertSupportedNodeVersion();
+    await runSetupCommand(commandArgs, { env });
+    return;
+  }
+  if (command === 'uninstall') {
+    if (runtimeArgs.length) {
+      throw new TypeError('Uninstall options must appear after the uninstall command');
+    }
+    await runUninstallCommand(commandArgs, { env });
+    return;
+  }
+  if (isLocalRuntimeCommand(command)) {
+    if (runtimeArgs.length) {
+      throw new TypeError(`${command} options must appear after the command`);
+    }
+    return runLocalRuntimeCommand(command, commandArgs, { env });
+  }
+  if (!isRegisteredCommand(command)) throw new Error(`Unknown command: ${command}`);
+
+  const options = resolveRuntimeOptions(runtimeArgs, env);
+  const app = openLocalApplication(options);
+  try {
+    dispatchCommand(app, command, commandArgs);
+  } finally {
+    app.close();
+  }
+}
+
+if (isMainModule(import.meta.url, process.argv[1])) {
+  main()
+    .then((result) => {
+      if (Number.isInteger(result?.exitCode)) process.exitCode = result.exitCode;
+    })
+    .catch((error) => {
+      console.error(error.message);
+      process.exitCode = 1;
+    });
+}
+
+export function isMainModule(metaUrl, argvPath) {
+  if (!argvPath) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(argvPath);
+  } catch {
+    return fileURLToPath(metaUrl) === argvPath;
+  }
+}