@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/lib/workspace.js

@@ -0,0 +1,501 @@
+/**
+ * Workspace resolution and lifecycle.
+ *
+ * A workspace is one directory the user chooses on first initialization. It
+ * owns the shared scan/analyze artifacts, the SurrealDB data directory, and all
+ * project directories. Project directories live at:
+ *
+ *   <workspace>/projects/<uuid>/
+ *
+ * Workspace-level state is deliberately small:
+ *
+ *   <workspace>/.fancy/workspace.json   non-secret pointers and server config
+ *   <workspace>/.fancy/secrets.json     root + per-project DB credentials (0600)
+ *   <workspace>/.fancy-deployed         scan/topic phase used by the shared tools
+ *   <workspace>/扫榜结果/                 shared scan output
+ *   <workspace>/对标/                    shared reference-novel analysis
+ *   <workspace>/references/             shared writing references
+ *   <workspace>/projects/<uuid>/        one project
+ *
+ * The global pointer at ~/.config/fancy-webnovel/workspace.json lets commands
+ * and the MCP server find the workspace when the caller's cwd is elsewhere.
+ * FANCY_HOME always wins.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+export const WORKSPACE_SCHEMA_VERSION = 1;
+export const WORKSPACE_DIR = '.fancy';
+export const WORKSPACE_FILE = 'workspace.json';
+export const SECRETS_FILE = 'secrets.json';
+export const PROJECTS_DIR = 'projects';
+export const SCAN_DIR = '扫榜结果';
+export const ANALYZE_DIR = '对标';
+export const REFERENCES_DIR = 'references';
+export const REFERENCE_SOURCES_DIR = '参考资料';
+export const GLOBAL_REGISTRY_FILE = 'workspaces.json';
+
+export class WorkspaceError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'WorkspaceError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+export function expandHome(value) {
+  const text = String(value || '');
+  if (text === '~') return os.homedir();
+  if (text.startsWith('~/') || text.startsWith('~\\')) {
+    return path.join(os.homedir(), text.slice(2));
+  }
+  return text;
+}
+
+export function resolvePath(value, base) {
+  const expanded = expandHome(value);
+  if (!expanded) return expanded;
+  if (path.isAbsolute(expanded)) return path.resolve(expanded);
+  return path.resolve(base || process.cwd(), expanded);
+}
+
+function pad(value, width = 2) {
+  return String(value).padStart(width, '0');
+}
+
+/**
+ * ISO-8601 in the machine's local timezone, including its offset.
+ * Example (UTC+8): 2026-11-11T17:16:08.219+08:00
+ */
+export function localIsoString(date = new Date()) {
+  const d = date instanceof Date ? date : new Date(date);
+  if (Number.isNaN(d.getTime())) return '';
+  const offsetMinutes = -d.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const abs = Math.abs(offsetMinutes);
+  return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate())
+    + 'T' + pad(d.getHours()) + ':' + pad(d.getMinutes()) + ':' + pad(d.getSeconds())
+    + '.' + pad(d.getMilliseconds(), 3)
+    + sign + pad(Math.floor(abs / 60)) + ':' + pad(abs % 60);
+}
+
+export function formatLocalTime(value) {
+  if (value === undefined || value === null || value === '') return '';
+  const d = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(d.getTime()) ? String(value) : localIsoString(d);
+}
+
+export function workspaceMetaPath(root) {
+  return path.join(root, WORKSPACE_DIR, WORKSPACE_FILE);
+}
+
+export function workspaceSecretsPath(root) {
+  return path.join(root, WORKSPACE_DIR, SECRETS_FILE);
+}
+
+export function deployedPath(root) {
+  return path.join(root, '.fancy-deployed');
+}
+
+export function globalPointerPath() {
+  const configHome = process.env.XDG_CONFIG_HOME
+    ? path.resolve(process.env.XDG_CONFIG_HOME)
+    : path.join(os.homedir(), '.config');
+  return path.join(configHome, 'fancy-webnovel', 'workspace.json');
+}
+
+export function globalRegistryPath() {
+  const configHome = process.env.XDG_CONFIG_HOME
+    ? path.resolve(process.env.XDG_CONFIG_HOME)
+    : path.join(os.homedir(), '.config');
+  return path.join(configHome, 'fancy-webnovel', GLOBAL_REGISTRY_FILE);
+}
+
+export function workspacePaths(root) {
+  const base = path.resolve(root);
+  return {
+    root: base,
+    fancy: path.join(base, WORKSPACE_DIR),
+    projects: path.join(base, PROJECTS_DIR),
+    scan: path.join(base, SCAN_DIR),
+    analyze: path.join(base, ANALYZE_DIR),
+    references: path.join(base, REFERENCES_DIR),
+    referenceSources: path.join(base, REFERENCE_SOURCES_DIR),
+    tmp: path.join(base, '.tmp'),
+    surreal: path.join(base, WORKSPACE_DIR, 'surreal'),
+    surrealData: path.join(base, WORKSPACE_DIR, 'surreal', 'data'),
+    surrealLog: path.join(base, WORKSPACE_DIR, 'surreal', 'server.log'),
+    surrealPid: path.join(base, WORKSPACE_DIR, 'surreal', 'server.pid'),
+    project: (id) => path.join(base, PROJECTS_DIR, String(id)),
+  };
+}
+
+export function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function atomicWriteJson(file, value, opts = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+  const body = JSON.stringify(value, null, 2) + '\n';
+  fs.writeFileSync(tmp, body, { encoding: 'utf8', mode: opts.mode ?? 0o600 });
+  fs.renameSync(tmp, file);
+  try { fs.chmodSync(file, opts.mode ?? 0o600); } catch { /* best effort */ }
+  return file;
+}
+
+export function isWorkspace(root) {
+  if (!root) return false;
+  // Full workspaces have .fancy/workspace.json. A directory that only has
+  // .fancy-deployed is still a valid workspace for the shared scan/topic/
+  // analyze tools (and for lightweight/legacy workspaces created before the
+  // registry existed). Project management tools that need secrets/server
+  // config will report a clear error if the full config is absent.
+  return fs.existsSync(workspaceMetaPath(root)) || fs.existsSync(deployedPath(root));
+}
+
+export function readWorkspace(root) {
+  const file = workspaceMetaPath(root);
+  const data = readJsonFile(file);
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new WorkspaceError('WORKSPACE_UNREADABLE', '无法读取工作区状态文件：' + file);
+  }
+  if (data.schema_version !== undefined && Number(data.schema_version) > WORKSPACE_SCHEMA_VERSION) {
+    throw new WorkspaceError('WORKSPACE_VERSION', '工作区数据版本高于当前插件支持版本：' + data.schema_version + '。请升级 fancy-webnovel 后重试。');
+  }
+  return data;
+}
+
+/**
+ * Walk up from a directory looking for a workspace marker. This handles the
+ * common case where the DSH session cwd is a project directory
+ * (`A/projects/<uuid>`) or a subdirectory of it.
+ */
+export function findWorkspace(start) {
+  if (!start) return null;
+  let current = path.resolve(start);
+  try {
+    if (fs.existsSync(current) && !fs.statSync(current).isDirectory()) current = path.dirname(current);
+  } catch { /* fall through */ }
+  for (;;) {
+    if (isWorkspace(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function normalizeRegistryEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const workspace = typeof entry.workspace === 'string' ? path.resolve(expandHome(entry.workspace)) : '';
+  if (!workspace) return null;
+  return {
+    workspace,
+    workspace_id: typeof entry.workspace_id === 'string' ? entry.workspace_id : '',
+    name: typeof entry.name === 'string' && entry.name ? entry.name : path.basename(workspace),
+    created_at: typeof entry.created_at === 'string' ? entry.created_at : '',
+    updated_at: typeof entry.updated_at === 'string' ? entry.updated_at : '',
+    last_used: typeof entry.last_used === 'string' ? entry.last_used : (entry.updated_at || ''),
+  };
+}
+
+/**
+ * Read the machine-level workspace registry. The registry is append/update:
+ * every initialized workspace has one entry. A legacy single-pointer file
+ * (`workspace.json`) is still read so existing installs are not lost.
+ */
+export function readGlobalRegistry() {
+  const file = globalRegistryPath();
+  const raw = readJsonFile(file);
+  const entries = [];
+  if (raw && Array.isArray(raw.workspaces)) {
+    for (const entry of raw.workspaces) {
+      const normalized = normalizeRegistryEntry(entry);
+      if (normalized) entries.push(normalized);
+    }
+  }
+  // Merge the legacy single pointer if it is not already in the registry.
+  const legacy = readJsonFile(globalPointerPath());
+  if (legacy && typeof legacy.workspace === 'string') {
+    const normalized = normalizeRegistryEntry({ workspace: legacy.workspace, updated_at: legacy.updated_at, last_used: legacy.updated_at });
+    if (normalized && !entries.some((item) => item.workspace === normalized.workspace)) {
+      // Fill identity from the workspace itself when possible.
+      try {
+        const meta = readWorkspace(normalized.workspace);
+        normalized.workspace_id = meta.workspace_id || '';
+        normalized.name = meta.name || normalized.name;
+        normalized.created_at = meta.created_at || '';
+      } catch { /* lightweight or missing */ }
+      entries.push(normalized);
+    }
+  }
+  const deduped = new Map();
+  for (const entry of entries) deduped.set(entry.workspace, entry);
+  return {
+    schema_version: WORKSPACE_SCHEMA_VERSION,
+    updated_at: raw && typeof raw.updated_at === 'string' ? raw.updated_at : '',
+    workspaces: [...deduped.values()],
+  };
+}
+
+export function writeGlobalRegistry(registry) {
+  const value = {
+    schema_version: WORKSPACE_SCHEMA_VERSION,
+    updated_at: localIsoString(),
+    workspaces: (registry && Array.isArray(registry.workspaces) ? registry.workspaces : [])
+      .map(normalizeRegistryEntry)
+      .filter(Boolean),
+  };
+  atomicWriteJson(globalRegistryPath(), value, { mode: 0o600 });
+  return value;
+}
+
+export function registerGlobalWorkspace(root, opts = {}) {
+  const workspacePath = path.resolve(root);
+  const registry = readGlobalRegistry();
+  const now = localIsoString();
+  const index = registry.workspaces.findIndex((entry) => entry.workspace === workspacePath);
+  let meta = null;
+  try { meta = readWorkspace(workspacePath); } catch { /* lightweight */ }
+  const previous = index >= 0 ? registry.workspaces[index] : null;
+  const entry = {
+    workspace: workspacePath,
+    workspace_id: opts.workspace_id || (meta && meta.workspace_id) || (previous && previous.workspace_id) || '',
+    name: opts.name || (meta && meta.name) || (previous && previous.name) || path.basename(workspacePath),
+    created_at: (meta && meta.created_at) || (previous && previous.created_at) || now,
+    updated_at: now,
+    last_used: opts.touch === false ? ((previous && previous.last_used) || now) : now,
+  };
+  if (index >= 0) registry.workspaces[index] = entry;
+  else registry.workspaces.push(entry);
+  writeGlobalRegistry(registry);
+  // Keep the legacy pointer in sync for older plugin versions.
+  atomicWriteJson(globalPointerPath(), {
+    schema_version: WORKSPACE_SCHEMA_VERSION,
+    workspace: workspacePath,
+    updated_at: now,
+  }, { mode: 0o600 });
+  return entry;
+}
+
+export function listGlobalWorkspaces() {
+  return readGlobalRegistry().workspaces
+    .map((entry) => ({ ...entry, exists: isWorkspace(entry.workspace) }))
+    .sort((a, b) => (Date.parse(b.last_used) || 0) - (Date.parse(a.last_used) || 0));
+}
+
+export function readGlobalPointer() {
+  // Prefer the legacy last-used pointer; fall back to the newest existing
+  // registry entry when an old install predates the registry file.
+  const legacy = readJsonFile(globalPointerPath());
+  if (legacy && typeof legacy.workspace === 'string') return legacy;
+  const existing = listGlobalWorkspaces().find((entry) => entry.exists);
+  return existing ? { workspace: existing.workspace, updated_at: existing.last_used } : null;
+}
+
+export function writeGlobalPointer(root) {
+  const entry = registerGlobalWorkspace(root);
+  return { file: globalRegistryPath(), entry };
+}
+
+/**
+ * Resolve the workspace from, in order:
+ *   1. an explicit path (CLI/MCP argument)
+ *   2. FANCY_HOME
+ *   3. an ancestor of cwd containing .fancy/workspace.json
+ *   4. the global pointer written by init
+ */
+export function resolveWorkspace(opts = {}) {
+  const explicit = opts.explicit || opts.workspace || process.env.FANCY_HOME;
+  if (explicit) {
+    const root = resolvePath(explicit, opts.cwd || process.cwd());
+    if (!isWorkspace(root)) {
+      throw new WorkspaceError(
+        'WORKSPACE_NOT_INITIALIZED',
+        '指定目录不是 fancy-webnovel 工作区：' + root + '（缺少 .fancy/workspace.json）。请先运行 /fancy-bootstrap 初始化工作区。',
+      );
+    }
+    return root;
+  }
+
+  const found = findWorkspace(opts.cwd || process.cwd());
+  if (found) return found;
+
+  // The machine-level registry is a convenience for long-lived MCP sessions
+  // and explicit "use the last workspace" flows. Slash commands should not
+  // silently target the last workspace when the user runs them from an
+  // unrelated directory; require cwd/FANCY_HOME unless the caller opts in.
+  if (opts.allowGlobal) {
+    const existingWorkspaces = listGlobalWorkspaces().filter((entry) => entry.exists);
+    if (existingWorkspaces.length) return existingWorkspaces[0].workspace;
+
+    const pointer = readGlobalPointer();
+    if (pointer && pointer.workspace) {
+      const root = path.resolve(expandHome(pointer.workspace));
+      if (isWorkspace(root)) return root;
+    }
+  }
+
+  const required = opts.required !== false;
+  if (!required) return null;
+  throw new WorkspaceError(
+    'WORKSPACE_NOT_INITIALIZED',
+    '当前目录不是 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。',
+  );
+}
+
+function randomPassword(bytes = 24) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+export function defaultSurrealConfig(root) {
+  return {
+    url: 'http://127.0.0.1:8000/rpc',
+    bind: '127.0.0.1:8000',
+    namespace: 'fancy',
+    registry_database: 'fancy_registry',
+    material_database: 'material_library',
+    data_dir: workspacePaths(root).surrealData,
+    pid_file: workspacePaths(root).surrealPid,
+    log_file: workspacePaths(root).surrealLog,
+  };
+}
+
+export function readSecrets(root) {
+  const file = workspaceSecretsPath(root);
+  const data = readJsonFile(file);
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new WorkspaceError('SECRETS_UNREADABLE', '无法读取工作区密钥文件：' + file);
+  }
+  return data;
+}
+
+export function writeSecrets(root, secrets) {
+  return atomicWriteJson(workspaceSecretsPath(root), secrets, { mode: 0o600 });
+}
+
+export function ensureSecrets(root) {
+  const file = workspaceSecretsPath(root);
+  if (fs.existsSync(file)) return readSecrets(root);
+  const secrets = {
+    schema_version: WORKSPACE_SCHEMA_VERSION,
+    surreal: { username: 'root', password: randomPassword(24) },
+    projects: {},
+  };
+  writeSecrets(root, secrets);
+  return secrets;
+}
+
+export function ensureDeployed(root, phase = 'initialized') {
+  const file = deployedPath(root);
+  if (fs.existsSync(file)) return readJsonFile(file);
+  const data = {
+    deployed_at: localIsoString(),
+    project_root_abs: path.resolve(root),
+    workspace: true,
+    phase,
+  };
+  atomicWriteJson(file, data, { mode: 0o600 });
+  return data;
+}
+
+export function workspaceTopicPath(root) {
+  return path.join(root, '_novel_topic.json');
+}
+
+export function workspaceSuggestionPath(root) {
+  return path.join(root, '_novel_topic_suggestion.json');
+}
+
+/**
+ * Create the workspace directory tree and its non-secret config. This is
+ * idempotent: calling it on an existing workspace returns the existing config
+ * without overwriting secrets or the active project.
+ */
+export function initWorkspace(rootRaw, opts = {}) {
+  const root = resolvePath(rootRaw, opts.cwd || process.cwd());
+  if (!root) throw new WorkspaceError('WORKSPACE_PATH_REQUIRED', '请提供工作区目录。');
+  if (fs.existsSync(root) && !fs.statSync(root).isDirectory()) {
+    throw new WorkspaceError('WORKSPACE_NOT_DIRECTORY', '工作区路径不是目录：' + root);
+  }
+  fs.mkdirSync(root, { recursive: true });
+  const paths = workspacePaths(root);
+  for (const dir of [paths.fancy, paths.projects, paths.scan, paths.analyze, paths.references, paths.referenceSources, paths.tmp, paths.surrealData]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const existing = fs.existsSync(workspaceMetaPath(root)) ? readWorkspace(root) : null;
+  if (existing) {
+    ensureSecrets(root);
+    ensureDeployed(root, existing.phase || 'initialized');
+    writeGlobalPointer(root);
+    return { root, created: false, workspace: existing, paths };
+  }
+
+  const workspace = {
+    schema_version: WORKSPACE_SCHEMA_VERSION,
+    workspace_id: crypto.randomUUID(),
+    name: opts.name || path.basename(root),
+    created_at: localIsoString(),
+    updated_at: localIsoString(),
+    active_project: null,
+    surreal: defaultSurrealConfig(root),
+  };
+  atomicWriteJson(workspaceMetaPath(root), workspace, { mode: 0o600 });
+  ensureSecrets(root);
+  ensureDeployed(root, 'initialized');
+  writeGlobalPointer(root);
+  return { root, created: true, workspace, paths };
+}
+
+export function updateWorkspace(root, patch) {
+  const current = readWorkspace(root);
+  const next = {
+    ...current,
+    ...patch,
+    surreal: { ...(current.surreal || {}), ...(patch && patch.surreal ? patch.surreal : {}) },
+    updated_at: localIsoString(),
+  };
+  atomicWriteJson(workspaceMetaPath(root), next, { mode: 0o600 });
+  return next;
+}
+
+export function setActiveProject(root, projectId) {
+  return updateWorkspace(root, { active_project: projectId || null });
+}
+
+export function getActiveProject(root) {
+  try {
+    return readWorkspace(root).active_project || null;
+  } catch {
+    return null;
+  }
+}
+
+export function workspaceSummary(root) {
+  const workspace = readWorkspace(root);
+  const paths = workspacePaths(root);
+  return {
+    root: paths.root,
+    workspace_id: workspace.workspace_id,
+    name: workspace.name,
+    active_project: workspace.active_project || null,
+    surreal: workspace.surreal,
+    paths: {
+      projects: paths.projects,
+      scan: paths.scan,
+      analyze: paths.analyze,
+      references: paths.references,
+      referenceSources: paths.referenceSources,
+      exports: null,
+    },
+  };
+}

package/package.json

@@ -1,23 +1,80 @@
 {
   "name": "@cloud411716/fancy-webnovel",
-  "version": "1.0.46",
+  "version": "3.0.0",
   "type": "module",
   "main": "index.js",
   "exports": {
-    ".": "./index.js"
+    ".": "./index.js",
+    "./client": "./client.js"
+  },
+  "imports": {
+    "#infra": "./lib/infra.js",
+    "#scraper-utils": "./lib/scraper-utils.js",
+    "#error-codes": "./lib/error-codes.js",
+    "#atomic-write": "./lib/atomic-write.js",
+    "#topic-schema": "./lib/topic-schema.js",
+    "#topic-fields": "./lib/topic-fields.js",
+    "#llm-wiki": "./lib/llm-wiki.js",
+    "#deployed-state": "./lib/deployed-state.js",
+    "#chinese-num": "./lib/chinese-num.js",
+    "#topic-decision": "./lib/topic-decision.js",
+    "#path-guard": "./lib/path-guard.js",
+    "#direction-labels": "./lib/direction-labels.js",
+    "#story-builder/*": "./plugins/fancy-story-builder/*",
+    "#chapter-order": "./lib/chapter-order.js",
+    "#workspace": "./lib/workspace.js",
+    "#projects": "./lib/projects.js",
+    "#db-init": "./lib/db-init.js",
+    "#surreal-server": "./lib/surreal-server.js",
+    "#material-db": "./lib/material-db.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node tests/run.js",
+    "sync:profile": "bash scripts/sync-profile.sh"
   },
   "files": [
     "index.js",
-    "infra.js",
+    "lib/",
+    "templates.js",
     "cordis.patch.yml",
-    "commands/"
+    "README.md",
+    "docs/",
+    "plugins/",
+    "client.js"
   ],
   "dependencies": {
-    "playwright-core": "1.48.0"
+    "@surrealdb/node": "3.2.0",
+    "@surrealdb/node-native": "4.0.1",
+    "graphology": "^0.26.0",
+    "playwright-core": "^1.48.0",
+    "surrealdb": "2.2.2",
+    "tesseract.js": "^7.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
   },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
     }
+  },
+  "bin": {
+    "storydb": "./plugins/fancy-story-builder/storydb/cli.js",
+    "fancy-mcp": "./plugins/fancy-story-builder/storydb/mcp.js"
   }
 }