@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/lib/material-db.js

@@ -0,0 +1,149 @@
+/**
+ * Shared material library database.
+ *
+ * The material library is workspace-level: one database per workspace
+ * (`material_library`), shared by every project. It lives on the same
+ * SurrealDB server as the registry and project databases.
+ *
+ * The schema is kept in `docs/material-library/schema.surql` so the standalone
+ * docs/import tooling and the plugin initialize exactly the same tables.
+ */
+
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { Surreal, createRemoteEngines } from 'surrealdb';
+import { MATERIAL_KINDS } from '../plugins/fancy-material/kinds.js';
+import { readSecrets, readWorkspace } from './workspace.js';
+import { rpcUrl, startServer } from './surreal-server.js';
+
+export const MATERIAL_DATABASE = 'material_library';
+export const MATERIAL_SCHEMA_VERSION = 6;
+
+const SCHEMA_FILE = fileURLToPath(new URL('../docs/material-library/schema.surql', import.meta.url));
+
+export function materialDatabaseName(workspace) {
+  return (workspace && workspace.surreal && workspace.surreal.material_database) || MATERIAL_DATABASE;
+}
+
+export function materialSchemaText() {
+  return fs.readFileSync(SCHEMA_FILE, 'utf8');
+}
+
+/**
+ * Connect as the workspace root user to the material database.
+ *
+ * `startServer` verifies the workspace credentials and may move the workspace
+ * to a free port when another SurrealDB is squatting on the configured one.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{db: Surreal, workspace: object, secrets: object, namespace: string, database: string}>}
+ */
+export async function connectMaterial(root) {
+  await startServer(root);
+  const workspace = readWorkspace(root);
+  const secrets = readSecrets(root);
+  const db = new Surreal({ engines: { ...createRemoteEngines() } });
+  await db.connect(rpcUrl(workspace));
+  await db.signin({
+    username: secrets.surreal?.username || 'root',
+    password: secrets.surreal?.password,
+  });
+  const namespace = workspace.surreal?.namespace || 'fancy';
+  const database = materialDatabaseName(workspace);
+  await db.use({ namespace, database });
+  return { db, workspace, secrets, namespace, database };
+}
+
+/**
+ * Ensure the material database and its schema exist. Idempotent.
+ *
+ * Schema v6 adds `source` (builtin/other) and narrows builtin kinds to the current 54-kind catalog. Before applying the
+ * new ASSERT, rows belonging to retired kinds are removed; otherwise SurrealDB
+ * refuses to overwrite the field because existing records no longer conform.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{ok: boolean, namespace: string, database: string, schema_version: number, fields: number, indexes: string[], pruned: number}>}
+ */
+export async function ensureMaterialDatabase(root) {
+  const { db, namespace, database } = await connectMaterial(root);
+  try {
+    let pruned = 0;
+    const info = await db.query('INFO FOR DB;');
+    const dbInfo = Array.isArray(info) && info[0] ? info[0] : info;
+    const tables = (dbInfo && dbInfo.tables) || {};
+    if (tables.material) {
+      // Old databases may have rows created before these fields existed.
+      // SCHEMAFULL tables reject writes to undefined fields, so add them
+      // before backfilling.
+      await db.query('DEFINE FIELD IF NOT EXISTS created_at ON material TYPE datetime DEFAULT time::now();');
+      await db.query('DEFINE FIELD IF NOT EXISTS updated_at ON material TYPE datetime VALUE time::now();');
+      await db.query("DEFINE FIELD IF NOT EXISTS source ON material TYPE string DEFAULT 'builtin';");
+      await db.query('UPDATE material SET created_at = time::now() WHERE created_at = NONE;');
+      await db.query('UPDATE material SET updated_at = time::now() WHERE updated_at = NONE;');
+      await db.query("UPDATE material SET source = 'builtin' WHERE source = NONE OR source NOT IN ['builtin', 'other'];");
+      // Builtin rows cannot use retired kinds, so remove them before the
+      // DEFINE FIELD OVERWRITE. Rows with source='other' may use any kind and
+      // are deliberately kept.
+      const invalid = await db.query(
+        "SELECT count() AS n FROM material WHERE source = 'builtin' AND kind NOT IN $kinds GROUP ALL;",
+        { kinds: MATERIAL_KINDS },
+      );
+      const invalidRow = Array.isArray(invalid) && Array.isArray(invalid[0]) ? invalid[0][0] : null;
+      pruned = invalidRow ? Number(invalidRow.n) || 0 : 0;
+      if (pruned > 0) {
+        await db.query("DELETE material WHERE source = 'builtin' AND kind NOT IN $kinds;", { kinds: MATERIAL_KINDS });
+      }
+    }
+    await db.query(materialSchemaText());
+    const tableInfo = await db.query('INFO FOR TABLE material;');
+    const table = Array.isArray(tableInfo) && tableInfo[0] ? tableInfo[0] : {};
+    if (!table.fields || !table.fields.source || !table.fields.kind || !table.fields.name || !table.fields.tags) {
+      throw new Error('素材库 schema 初始化后仍未找到 material.kind/name/tags 字段。');
+    }
+    return {
+      ok: true,
+      namespace,
+      database,
+      schema_version: MATERIAL_SCHEMA_VERSION,
+      fields: Object.keys(table.fields || {}).length,
+      indexes: Object.keys(table.indexes || {}),
+      pruned,
+    };
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Remove the workspace material database.
+ *
+ * Connect through the registry database (never through the target database)
+ * and issue `REMOVE DATABASE IF EXISTS`.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{removed: boolean, database: string}>}
+ */
+export async function removeMaterialDatabase(root) {
+  await startServer(root);
+  const workspace = readWorkspace(root);
+  const secrets = readSecrets(root);
+  const namespace = workspace.surreal?.namespace || 'fancy';
+  const database = materialDatabaseName(workspace);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(database)) {
+    throw new Error('素材库数据库名不合法：' + database);
+  }
+  const registry = workspace.surreal?.registry_database || 'fancy_registry';
+  const db = new Surreal({ engines: { ...createRemoteEngines() } });
+  try {
+    await db.connect(rpcUrl(workspace));
+    await db.signin({
+      username: secrets.surreal?.username || 'root',
+      password: secrets.surreal?.password,
+    });
+    await db.use({ namespace, database: registry });
+    await db.query('REMOVE DATABASE IF EXISTS ' + database + ';');
+    return { removed: true, database };
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}

package/lib/path-guard.js

@@ -0,0 +1,150 @@
+/**
+ * path-guard.js — 项目路径校验（bootstrap / scan / topic 共用一套）
+ *
+ * ## 为什么改成白名单（2026-10-29）
+ *
+ * 之前用的是黑名单：禁掉 `< > : " ' | ? *` 和控制字符，其余放行。
+ * 但项目路径会被**原样拼进提示词里的 shell 命令**：
+ *
+ *   cat >> "${topicFile}" <<'FANCY_SCAN_EOF'
+ *
+ * 双引号**挡不住**命令替换 —— `$()` 和反引号在双引号里照样展开。
+ * 于是 `/tmp/$(sh${IFS}/tmp/pwn.sh)` 这种目录名能通过校验：
+ * 它不含空格、不含 `..`、不含任何被禁字符。
+ *
+ * 黑名单永远列不全（要挡 `$(`、`` ` ``、`;`、`&`、`|`…），
+ * 所以改成白名单：**只放行确实需要的字符**。
+ *
+ * ## 为什么放行空格和括号
+ *
+ * 路径在提示词里是**单引号赋值 + 双引号引用**：
+ *
+ *   TOPIC_FILE='/path/带 空格/项目(测试)'
+ *   cat >> "$TOPIC_FILE" <<'FANCY_SCAN_EOF'
+ *
+ * 单引号内不做任何展开，`$TOPIC_FILE` 展开成字面路径后**不再二次展开**，
+ * 所以空格、括号、花括号在引号内都是安全的 —— 没必要为此把用户挡在门外。
+ *
+ * 真正危险的是 `$`、`` ` ``、`;`、`&`、`|`、`<`、`>` 和两种引号本身 ——
+ * 它们能让路径跳出引号，或者让 shell 在路径里执行命令。这些一律拒绝。
+ */
+
+/**
+ * 敏感系统路径前缀（黑名单）。
+ *
+ * **只是额外一层提示，不是安全边界** —— 安全边界是上面的白名单。
+ * 攻击者可以自己造一个不在名单里的敏感路径（/home/x/.ssh 等）。
+ */
+import os from 'os';
+
+export const SENSITIVE_PATH_PREFIXES = [
+  '/etc', '/proc', '/sys', '/dev', '/root', '/boot',
+  '/usr', '/bin', '/sbin', '/lib', '/lib64', '/opt', '/var', '/run', '/snap',
+  '/System', '/Library', '/private',
+  'C:/Windows', 'C:/Program Files', 'C:/Program Files (x86)',
+];
+
+/** Home-relative directories that must never become a workspace. */
+const HOME_SENSITIVE_DIRS = [
+  '.ssh', '.gnupg', '.aws', '.config', '.local', '.cache', '.kube',
+  '.docker', '.npm', '.cargo', '.rustup', '.password-store',
+  '.netrc', '.git-credentials', '.mozilla', '.thunderbird',
+];
+
+/**
+ * 明确拒绝的字符。
+ *
+ * `$` `` ` `` → 命令替换
+ * `;` `&` `|` → 命令分隔
+ * `<` `>`       → 重定向
+ * `"` `'`       → 提前闭合引号
+ * `!` `#` `?` `*` `%` `^` → 交互式历史展开 / 注释 / 通配 / 其它 shell 语义
+ * 控制字符 → 不可见、会被各种工具截断
+ */
+const FORBIDDEN_CHARS = /[$\u0060;&|<>"'!?#*%^]/;
+
+function normalizePathForGuard(p) {
+  return String(p || '').replace(/\\/g, '/');
+}
+
+/**
+ * Return the sensitive prefix that matches, or null. Prefixes are normalized
+ * so Windows-style input and the home-directory exclusions use one rule.
+ */
+function sensitivePrefixOf(p) {
+  if (!p || typeof p !== 'string') return null;
+  const normalized = normalizePathForGuard(p);
+  if (normalized === '/') return '/';
+  const home = normalizePathForGuard(os.homedir()).replace(/\/+$/, '');
+  for (const name of HOME_SENSITIVE_DIRS) {
+    const prefix = home + '/' + name;
+    if (normalized === prefix || normalized.startsWith(prefix + '/')) return prefix;
+  }
+  for (const prefix of SENSITIVE_PATH_PREFIXES) {
+    const normalizedPrefix = normalizePathForGuard(prefix);
+    if (normalized === normalizedPrefix || normalized.startsWith(normalizedPrefix + '/')) return normalizedPrefix;
+  }
+  return null;
+}
+
+/**
+ * 路径是否可用作项目根。
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isValidProjectPath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (p.includes('..')) return false;
+  if (FORBIDDEN_CHARS.test(p)) return false;
+  // 控制字符（含换行 / 制表符）
+  if (/[\x00-\x1f\x7f]/.test(p)) return false;
+  // 敏感系统路径
+  if (sensitivePrefixOf(p)) return false;
+  return true;
+}
+
+/**
+ * 路径是不是敏感系统目录（单独拎出来，因为错误码不一样）。
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isSensitiveProjectPath(p) {
+  return sensitivePrefixOf(p) !== null;
+}
+
+/**
+ * 路径不可用时，给用户看的原因（人话）。
+ *
+ * @param {string} p
+ * @returns {string|null} null 表示路径可用
+ */
+export function projectPathProblem(p) {
+  if (!p || typeof p !== 'string') return '路径不能为空。';
+  if (p.includes('..')) return '路径中不能包含 ".."。';
+  if (FORBIDDEN_CHARS.test(p)) {
+    return '路径中不能包含以下字符：$ ` ; & | < > " \' ! # ? * % ^'
+      + '（它们在 shell 命令里会有特殊含义，路径必须能被安全引用）';
+  }
+  if (/[\x00-\x1f\x7f]/.test(p)) return '路径中不能包含控制字符。';
+  const sensitive = sensitivePrefixOf(p);
+  if (sensitive) {
+    if (sensitive === '/') return '不能将根目录作为工作区目录。';
+    return `不能将系统受保护目录（${sensitive}）作为工作区目录。`;
+  }
+  return null;
+}
+
+/**
+ * 把路径安全地写进 shell 的单引号字符串。
+ *
+ * 单引号内不做任何展开；路径里的单引号用 `'\''` 断开再接上。
+ * 本插件的路径校验本来就禁止单引号，这里是双保险。
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function shellSingleQuote(p) {
+  return "'" + String(p == null ? '' : p).split("'").join("'\\''") + "'";
+}