@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/storydb/client.js

@@ -0,0 +1,351 @@
+/**
+ * Project story-graph connection.
+ *
+ * One workspace owns one SurrealDB server. Each project owns one database
+ * (`proj_<uuid>`) and one database-scoped VIEWER user with data-table
+ * permissions. The plugin's admin session (root) runs DDL; the writer session
+ * (project user) reads and writes data but cannot DEFINE/REMOVE schema.
+ *
+ * There is intentionally no embedded/legacy mode: an old `.fancy-storydb`
+ * directory is not opened. Use `memory: true` only in tests.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { Surreal, createRemoteEngines } from 'surrealdb';
+import { createNodeEngines } from '@surrealdb/node';
+import { DDL, SEARCH_INDEX_DDL } from './compile.js';
+import { ENTITIES, EDGES } from './definitions.js';
+import {
+  PROJECT_CONFIG_FILE,
+  readProjectConfig,
+  resolveProject,
+} from '../../../lib/projects.js';
+import {
+  readSecrets,
+  readWorkspace,
+} from '../../../lib/workspace.js';
+import { rpcUrl, startServer } from '../../../lib/surreal-server.js';
+
+export const NAMESPACE = 'fancy';
+export const REGISTRY_DATABASE = 'fancy_registry';
+export const STORY_RECORD = 'story:main';
+
+const WRITER_TABLES = [
+  ...Object.values(ENTITIES).map((def) => def.table),
+  ...Object.values(EDGES).map((def) => def.table),
+  'knowledge_event',
+  'knowledge_state',
+  'chapter_metric',
+];
+
+// A VIEWER system user with table-level CRUD can write records but cannot
+// DEFINE/REMOVE tables, functions or events.
+const WRITER_PERMISSIONS = WRITER_TABLES.map(
+  (table) => `ALTER TABLE ${table} PERMISSIONS FOR select, create, update, delete FULL;`,
+);
+
+export class StoryDbError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'StoryDbError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+export function flattenError(err) {
+  if (!err) return 'unknown error';
+  if (typeof err === 'string') return err;
+  const parts = [];
+  if (err.message) parts.push(err.message);
+  if (err.cause && err.cause.message && err.cause.message !== err.message) parts.push(err.cause.message);
+  if (Array.isArray(err.errors)) for (const e of err.errors) parts.push(flattenError(e));
+  return parts.filter(Boolean).join(' | ') || String(err);
+}
+
+export function dbPath(projectDir) {
+  return projectDir;
+}
+
+function isProjectDir(dir) {
+  try {
+    return fs.existsSync(path.join(dir, PROJECT_CONFIG_FILE));
+  } catch {
+    return false;
+  }
+}
+
+async function resolveTarget(projectRoot, opts) {
+  if (opts.project && typeof opts.project === 'object') {
+    const dir = opts.project.dir || projectRoot;
+    const config = opts.project.config || readProjectConfig(dir);
+    return {
+      ...opts.project,
+      dir,
+      config,
+      workspace: opts.project.workspace || (config && config.workspace),
+      db_name: opts.project.db_name || (config && config.database),
+    };
+  }
+  const root = path.resolve(projectRoot || opts.cwd || process.cwd());
+  if (isProjectDir(root)) {
+    const config = readProjectConfig(root);
+    return {
+      project_id: config.project_id,
+      dir: root,
+      db_name: config.database,
+      db_user: config.db_user,
+      workspace: config.workspace,
+      config,
+    };
+  }
+  // A bare path that is neither a project directory nor inside a workspace is
+  // not a project. Do not silently fall back to the global workspace pointer:
+  // an explicit --db/--project path must be honored or rejected.
+  const workspace = resolveWorkspace({
+    cwd: root,
+    explicit: opts.workspace,
+    required: false,
+  });
+  const ws = workspace ? path.resolve(workspace) : null;
+  const insideWorkspace = Boolean(ws && (root === ws || root.startsWith(ws + path.sep)));
+  if (!workspace || !insideWorkspace) {
+    throw new StoryDbError(
+      'PROJECT_NOT_FOUND',
+      '不是 fancy-webnovel 项目目录：' + root + '（缺少 .fancy-project.json，也不在工作区内）',
+    );
+  }
+  return resolveProject({
+    workspace,
+    cwd: root,
+    project: opts.project,
+    explicitWorkspace: workspace,
+  });
+}
+
+async function ensureSearchIndex(db) {
+  for (const sql of [SEARCH_INDEX_DDL.modern, SEARCH_INDEX_DDL.legacy]) {
+    try {
+      await db.query(sql);
+      return true;
+    } catch { /* try the next server syntax */ }
+  }
+  return false;
+}
+
+async function connect(endpoint) {
+  const db = new Surreal({
+    engines: { ...createRemoteEngines(), ...createNodeEngines() },
+  });
+  await db.connect(endpoint);
+  return db;
+}
+
+async function connectProject(sdb, project, opts) {
+  const workspaceRoot = project.workspace || project.config?.workspace;
+  if (!workspaceRoot) {
+    throw new StoryDbError('STORYDB_WORKSPACE', '项目缺少工作区信息：' + (project.dir || project.project_id || ''));
+  }
+  await startServer(workspaceRoot);
+  const workspace = readWorkspace(workspaceRoot);
+  const secrets = readSecrets(workspaceRoot);
+  const service = secrets;
+  const admin = await connect(rpcUrl(workspace));
+  await admin.signin({
+    username: service.surreal?.username || 'root',
+    password: service.surreal?.password,
+  });
+  const namespace = project.config?.namespace || workspace.surreal?.namespace || NAMESPACE;
+  const database = project.db_name || project.config?.database;
+  await admin.use({ namespace, database });
+
+  const credentials = secrets.projects?.[project.project_id];
+  if (!credentials) {
+    throw new StoryDbError('STORYDB_USER_MISSING', '项目缺少数据库用户凭据：' + project.project_id);
+  }
+
+  // The admin session owns schema. Existing databases get permissions
+  // refreshed so data tables remain writable by the project user. Long-lived
+  // MCP sessions can skip this after the first successful init.
+  if (!opts.skipSchema) {
+    for (const statement of DDL) await admin.query(statement);
+    await ensureSearchIndex(admin);
+    for (const statement of WRITER_PERMISSIONS) await admin.query(statement);
+    await admin.query(
+      `DEFINE USER IF NOT EXISTS ${credentials.username} ON DATABASE PASSWORD '${credentials.password}' ROLES VIEWER;`,
+    );
+  }
+
+  let conn = admin;
+  if (!opts.admin) {
+    conn = await connect(rpcUrl(workspace));
+    await conn.signin({
+      username: credentials.username,
+      password: credentials.password,
+      namespace,
+      database,
+    });
+    await conn.use({ namespace, database });
+  }
+  return { admin, conn, workspace, namespace, database };
+}
+
+export async function openStoryGraph(projectRoot, opts = {}) {
+  const memory = Boolean(opts.memory);
+  if (memory) {
+    const db = new Surreal({
+      engines: { ...createRemoteEngines(), ...createNodeEngines() },
+    });
+    await db.connect('mem://');
+    await db.use({ namespace: NAMESPACE, database: 'story' });
+    for (const statement of DDL) await db.query(statement);
+    await ensureSearchIndex(db);
+    return makeApi(db, db, { memory: true, dir: projectRoot || ':memory:' });
+  }
+
+  const project = await resolveTarget(projectRoot, opts);
+  const { admin, conn, workspace, namespace, database } = await connectProject(projectRoot, project, opts);
+  return makeApi(admin, conn, {
+    memory: false,
+    dir: project.dir,
+    project,
+    workspace,
+    namespace,
+    database,
+  });
+}
+
+function makeApi(db, conn, meta) {
+  let batch = null;
+  let closed = false;
+
+  const api = {
+    db,
+    conn,
+    dir: meta.dir,
+    memory: Boolean(meta.memory),
+    project: meta.project || null,
+    workspace: meta.workspace || null,
+    namespace: meta.namespace || NAMESPACE,
+    database: meta.database || 'story',
+    isOpen() { return !closed; },
+    async close() {
+      if (closed) return;
+      closed = true;
+      try { if (conn && conn !== db) await conn.close(); } catch { /* ignore */ }
+      try { await db.close(); } catch { /* ignore */ }
+    },
+    beginBatch() {
+      batch = [];
+    },
+    cancelBatch() {
+      batch = null;
+    },
+    async commitBatch() {
+      if (!batch) return [];
+      const items = batch;
+      batch = null;
+      const vars = {};
+      const parts = [];
+      for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        const prefix = 'q' + index + '_';
+        const sql = String(item.sql).replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) => '$' + prefix + name);
+        for (const [key, value] of Object.entries(item.vars || {})) vars[prefix + key] = value;
+        parts.push(sql.trim().replace(/;+$/, '') + ';');
+      }
+      try {
+        // One explicit transaction on the writer session. BEGIN/COMMIT are
+        // part of the same query, so a failure rolls the whole batch back.
+        const out = await conn.query('BEGIN TRANSACTION;\n' + parts.join('\n') + '\nCOMMIT TRANSACTION;', vars);
+        return Array.isArray(out) ? out : [];
+      } catch (err) {
+        throw new StoryDbError('STORYDB_TX', flattenError(err), { queries: items.length });
+      }
+    },
+    async query(sql, vars) {
+      if (batch) {
+        batch.push({ sql, vars });
+        return [[]];
+      }
+      try {
+        return await conn.query(sql, vars);
+      } catch (err) {
+        throw new StoryDbError('STORYDB_QUERY', flattenError(err), { sql });
+      }
+    },
+    async rows(sql, vars) {
+      const out = await conn.query(sql, vars);
+      return Array.isArray(out) && Array.isArray(out[0]) ? out[0] : [];
+    },
+    async one(sql, vars) {
+      const rows = await api.rows(sql, vars);
+      return rows[0] || null;
+    },
+    async tx(fn) {
+      api.beginBatch();
+      try {
+        const result = await fn();
+        await api.commitBatch();
+        return result;
+      } catch (err) {
+        api.cancelBatch();
+        throw err;
+      }
+    },
+  };
+  return api;
+}
+
+function topicInfoFrom(project, info) {
+  const topic = (project && project.topic) || info.topic || {};
+  return {
+    title: info.title || topic.book_name || topic.title || (project && project.name),
+    genre: info.genre || topic.genre,
+    platform: info.platform || topic.platform,
+    target_chapters: info.target_chapters || topic.target_chapters,
+    target_words: info.target_words || topic.target_words,
+    avg_words_per_chapter: info.avg_words_per_chapter || topic.avg_words_per_chapter,
+    topic: Object.keys(topic).length ? topic : undefined,
+  };
+}
+
+export async function ensureRootStory(sdb, info = {}) {
+  const existing = await sdb.one('SELECT * FROM story:main;');
+  const source = topicInfoFrom(sdb.project, info);
+  const base = {
+    payload: {
+      ...((existing && existing.payload) || {}),
+      ...(source.topic ? { topic: source.topic } : {}),
+    },
+    title: existing
+      ? (info.title || existing.title || source.title || '未命名故事')
+      : (source.title || '未命名故事'),
+    genre: source.genre || (existing && existing.genre) || undefined,
+    platform: source.platform || (existing && existing.platform) || undefined,
+    target_chapters: Number(source.target_chapters) || (existing && existing.target_chapters) || 0,
+    target_words: Number(source.target_words) || (existing && existing.target_words) || 0,
+    avg_words_per_chapter: Number(source.avg_words_per_chapter)
+      || (existing && existing.avg_words_per_chapter)
+      || (source.target_chapters ? Math.round(Number(source.target_words || 0) / Number(source.target_chapters)) : 0),
+  };
+  if (existing) {
+    const sets = Object.keys(base).filter((k) => base[k] !== undefined).map((k) => k + ' = $' + k).join(', ');
+    await sdb.query(`UPDATE story:main SET ${sets}, updated_at = time::now();`, base);
+  } else {
+    const sets = Object.keys(base).filter((k) => base[k] !== undefined).map((k) => k + ' = $' + k).join(', ');
+    await sdb.query(`CREATE story:main SET ${sets};`, base);
+  }
+  return sdb.one('SELECT * FROM story:main;');
+}
+
+export async function projectTopic(project) {
+  const sdb = await openStoryGraph(project.dir, { project });
+  try {
+    const story = await sdb.one('SELECT * FROM story:main;');
+    return (story && story.payload && story.payload.topic) || project.topic || {};
+  } finally {
+    await sdb.close();
+  }
+}