@claudelaw/taichu 0.6.0

package/packages/server/src/plugin-installer.js

@@ -0,0 +1,139 @@
+/**
+ * Plugin Installer — 插件安装/卸载/更新
+ *
+ * 从 GitHub repository 或 npm 下载安装插件。
+ * 插件保存在项目 `plugins/` 目录下。
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createLogger } from './logger.js';
+
+const log = createLogger('plugin-installer');
+
+const DEFAULT_PLUGINS_DIR = join(process.cwd(), 'plugins');
+const PLUGINS_DIR = process.env.TAICHU_PLUGINS_DIR || DEFAULT_PLUGINS_DIR;
+
+/**
+ * Install a plugin from a GitHub repository.
+ * @param {string} repo — full GitHub repo, e.g. "taichu/plugin-seo"
+ * @param {object} [opts]
+ * @param {string} [opts.version] — specific version/tag
+ * @returns {Promise<{success: boolean, name?: string, version?: string, error?: string}>}
+ */
+export async function installPlugin(repo, opts = {}) {
+  const pluginName = repo.split('/').pop();
+
+  if (!existsSync(PLUGINS_DIR)) {
+    mkdirSync(PLUGINS_DIR, { recursive: true });
+  }
+
+  const targetDir = join(PLUGINS_DIR, pluginName);
+  if (existsSync(targetDir)) {
+    return { success: false, error: `Plugin "${pluginName}" already installed at ${targetDir}` };
+  }
+
+  const url = `https://github.com/${repo}.git`;
+  log.info(`Installing plugin: ${url}`);
+
+  try {
+    const args = ['clone', '--depth', '1'];
+    if (opts.version) {
+      args.push('--branch', opts.version);
+    }
+    args.push(url, targetDir);
+
+    execSync(`git ${args.join(' ')}`, { stdio: 'pipe', timeout: 30000 });
+
+    // Verify manifest
+    const manifestPath = join(targetDir, 'taichu.plugin.json');
+    if (!existsSync(manifestPath)) {
+      rmSync(targetDir, { recursive: true, force: true });
+      return { success: false, error: `No taichu.plugin.json found in "${repo}"` };
+    }
+
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    log.info(`Plugin installed: ${manifest.name} v${manifest.version}`);
+
+    return { success: true, name: manifest.name, version: manifest.version };
+  } catch (err) {
+    // Cleanup on failure
+    if (existsSync(targetDir)) {
+      rmSync(targetDir, { recursive: true, force: true });
+    }
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Uninstall a plugin.
+ * @param {string} name — plugin name or directory name
+ */
+export async function uninstallPlugin(name) {
+  const targetDir = join(PLUGINS_DIR, name);
+  if (!existsSync(targetDir)) {
+    // Try searching by manifest name
+    const entries = existsSync(PLUGINS_DIR) ? readdirSync(PLUGINS_DIR, { withFileTypes: true }) : [];
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const mp = join(PLUGINS_DIR, entry.name, 'taichu.plugin.json');
+        if (existsSync(mp)) {
+          const manifest = JSON.parse(readFileSync(mp, 'utf-8'));
+          if (manifest.name === name) {
+            rmSync(join(PLUGINS_DIR, entry.name), { recursive: true, force: true });
+            log.info(`Plugin uninstalled: ${name}`);
+            return { success: true };
+          }
+        }
+      }
+    }
+    return { success: false, error: `Plugin "${name}" not found` };
+  }
+
+  rmSync(targetDir, { recursive: true, force: true });
+  log.info(`Plugin uninstalled: ${name}`);
+  return { success: true };
+}
+
+/**
+ * List installed plugins with manifest info.
+ */
+export function listInstalled() {
+  if (!existsSync(PLUGINS_DIR)) return [];
+
+  const entries = readdirSync(PLUGINS_DIR, { withFileTypes: true });
+  const plugins = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const mp = join(PLUGINS_DIR, entry.name, 'taichu.plugin.json');
+      if (existsSync(mp)) {
+        try {
+          const manifest = JSON.parse(readFileSync(mp, 'utf-8'));
+          plugins.push({
+            ...manifest,
+            installedPath: join(PLUGINS_DIR, entry.name),
+            directory: entry.name
+          });
+        } catch (_) {}
+      }
+    }
+  }
+
+  return plugins;
+}
+
+/**
+ * Check if a plugin is installed.
+ */
+export function isInstalled(name) {
+  return listInstalled().some(p => p.name === name);
+}
+
+/**
+ * Get plugins directory path.
+ */
+export function getPluginsDir() {
+  return PLUGINS_DIR;
+}

package/packages/server/src/plugin-manager.js

@@ -0,0 +1,165 @@
+/**
+ * Plugin System — 扩展协议与沙箱
+ *
+ * Taichu 插件基于标准 npm 包 + manifest.json 声明。
+ *
+ * 插件清单 (taichu.plugin.json):
+ * {
+ *   "name": "@taichu/plugin-seo",
+ *   "version": "1.0.0",
+ *   "description": "SEO optimization plugin for Taichu",
+ *   "hooks": ["afterCreate", "afterUpdate"],
+ *   "routes": false,
+ *   "adminPanel": false,
+ *   "permissions": ["content:read", "content:write"]
+ * }
+ *
+ * 插件代码 (index.js):
+ * export default function(api) {
+ *   api.hook('afterCreate', async (doc) => {
+ *     await api.logger.info('SEO: optimizing', { id: doc.id });
+ *   });
+ * }
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createLogger } from './logger.js';
+
+const log = createLogger('plugin');
+
+/**
+ * @typedef {object} PluginManifest
+ * @property {string} name
+ * @property {string} version
+ * @property {string} description
+ * @property {string[]} hooks
+ * @property {boolean} routes
+ * @property {boolean} adminPanel
+ * @property {string[]} permissions
+ */
+
+/**
+ * @typedef {object} PluginAPI
+ * @property {object} store       — Taichu Store instance
+ * @property {object} hooks       — Hook system
+ * @property {object} logger      — Plugin-specific logger
+ * @property {object} config      — App config
+ */
+
+class PluginManager {
+  constructor() {
+    /** @type {Map<string, { manifest: PluginManifest, module: any, api: PluginAPI }>} */
+    this.plugins = new Map();
+  }
+
+  /**
+   * Load a plugin from a directory.
+   * @param {string} pluginPath — path to plugin directory (must contain taichu.plugin.json)
+   * @param {PluginAPI} api
+   */
+  async load(pluginPath, api) {
+    const manifestPath = join(pluginPath, 'taichu.plugin.json');
+    if (!existsSync(manifestPath)) {
+      throw new Error(`Plugin manifest not found: ${manifestPath}`);
+    }
+
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (!manifest.name || !manifest.version) {
+      throw new Error('Plugin manifest must have "name" and "version"');
+    }
+
+    if (this.plugins.has(manifest.name)) {
+      log.warn(`Plugin "${manifest.name}" already loaded, skipping`);
+      return;
+    }
+
+    log.info(`Loading plugin: ${manifest.name} v${manifest.version}`);
+
+    // Import plugin module
+    const modulePath = join(pluginPath, 'index.js');
+    if (!existsSync(modulePath)) {
+      throw new Error(`Plugin entry point not found: ${modulePath}`);
+    }
+
+    const url = pathToFileURL(modulePath).href;
+    const mod = await import(url);
+    const pluginFn = mod.default || mod;
+
+    if (typeof pluginFn !== 'function') {
+      throw new Error(`Plugin "${manifest.name}" must export a default function`);
+    }
+
+    // Build plugin API
+    const pluginApi = {
+      store: api.store,
+      hooks: api.hooks,
+      logger: createLogger(`plugin:${manifest.name}`),
+      config: api.config,
+      /** Register a hook handler */
+      hook(name, fn, priority) {
+        api.hooks.on(name, fn, priority);
+      },
+      /** Register a custom REST route handler */
+      route(method, path, handler) {
+        api.hooks.route(method, path, handler);
+      }
+    };
+
+    // Execute plugin
+    await pluginFn(pluginApi);
+
+    this.plugins.set(manifest.name, { manifest, module: mod, api: pluginApi });
+    log.info(`Plugin loaded: ${manifest.name}`);
+  }
+
+  /**
+   * Load all plugins from a directory.
+   */
+  async loadAll(pluginsDir, api) {
+    if (!existsSync(pluginsDir)) return;
+
+    const { readdirSync } = await import('node:fs');
+    const entries = readdirSync(pluginsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const pluginPath = join(pluginsDir, entry.name);
+        const manifestPath = join(pluginPath, 'taichu.plugin.json');
+        if (existsSync(manifestPath)) {
+          try {
+            await this.load(pluginPath, api);
+          } catch (err) {
+            log.error(`Failed to load plugin "${entry.name}": ${err.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  /** List loaded plugins */
+  list() {
+    return Array.from(this.plugins.values()).map(p => ({
+      name: p.manifest.name,
+      version: p.manifest.version,
+      description: p.manifest.description,
+      hooks: p.manifest.hooks,
+      permissions: p.manifest.permissions
+    }));
+  }
+
+  /** Get plugin count */
+  get count() {
+    return this.plugins.size;
+  }
+}
+
+// ── Singleton ──────────────────────────────────────────────
+
+let _pm = null;
+
+export function getPluginManager() {
+  if (!_pm) _pm = new PluginManager();
+  return _pm;
+}

package/packages/server/src/relationships.js

@@ -0,0 +1,217 @@
+/**
+ * Content Relationships — 内容关系图谱
+ *
+ * 管理文档间的引用关系，支持：
+ *   - related_to / parent_of / child_of / references / translated_from
+ *   - 双向索引（反向查找）
+ *   - 子图遍历（BFS，可配深度）
+ *
+ * 关系存储在文档 data._relationships 数组中。
+ */
+
+import { createLogger } from './logger.js';
+
+const log = createLogger('relationships');
+
+const VALID_TYPES = [
+  'related_to',      // 通用关联
+  'parent_of',       // 父子层级
+  'child_of',        // 反向父子（自动维护）
+  'references',      // 引用
+  'translated_from'  // 翻译源
+];
+
+/**
+ * @typedef {object} Relationship
+ * @property {string} type     — 关系类型
+ * @property {string} targetId — 目标文档 ID
+ * @property {object} [meta]   — 附加元数据
+ * @property {string} createdAt — ISO 8601
+ */
+
+/**
+ * Add a relationship between two documents.
+ * @param {object} store        — content store
+ * @param {string} sourceId     — 源文档 ID
+ * @param {string} targetId     — 目标文档 ID
+ * @param {string} type         — 关系类型
+ * @param {object} [meta]       — 元数据
+ */
+export async function addRelationship(store, sourceId, targetId, type, meta = {}) {
+  if (!VALID_TYPES.includes(type)) {
+    throw new Error(`Invalid relationship type: ${type}. Must be one of: ${VALID_TYPES.join(', ')}`);
+  }
+
+  const sourceDoc = await store.get(sourceId);
+  const targetDoc = await store.get(targetId);
+  if (!sourceDoc) throw new Error(`Source document not found: ${sourceId}`);
+  if (!targetDoc) throw new Error(`Target document not found: ${targetId}`);
+  if (sourceId === targetId) throw new Error('Cannot create self-referencing relationship');
+
+  // Check for duplicate
+  const existing = sourceDoc.data._relationships || [];
+  if (existing.some(r => r.targetId === targetId && r.type === type)) {
+    return { alreadyExists: true };
+  }
+
+  const rel = { type, targetId, meta, createdAt: new Date().toISOString() };
+  existing.push(rel);
+
+  await store.update(sourceId, {
+    data: { _relationships: existing }
+  });
+
+  // Auto-maintain reverse relationship for parent_of
+  if (type === 'parent_of') {
+    const targetRels = targetDoc.data._relationships || [];
+    if (!targetRels.some(r => r.targetId === sourceId && r.type === 'child_of')) {
+      targetRels.push({ type: 'child_of', targetId: sourceId, autoCreated: true, createdAt: new Date().toISOString() });
+      await store.update(targetId, { data: { _relationships: targetRels } });
+    }
+  }
+
+  log.debug(`Relationship created: ${sourceId} --[${type}]--> ${targetId}`);
+  return { created: true, relationship: rel };
+}
+
+/**
+ * Remove a relationship.
+ */
+export async function removeRelationship(store, sourceId, targetId, type) {
+  const sourceDoc = await store.get(sourceId);
+  if (!sourceDoc) throw new Error(`Document not found: ${sourceId}`);
+
+  const rels = (sourceDoc.data._relationships || []).filter(
+    r => !(r.targetId === targetId && (!type || r.type === type))
+  );
+
+  if (rels.length === (sourceDoc.data._relationships || []).length) {
+    return { notFound: true };
+  }
+
+  await store.update(sourceId, {
+    data: { _relationships: rels.length ? rels : undefined }
+  });
+
+  // Clean up reverse child_of if parent_of was removed
+  if (type === 'parent_of' || !type) {
+    try {
+      const targetDoc = await store.get(targetId);
+      if (targetDoc) {
+        const targetRels = (targetDoc.data._relationships || []).filter(
+          r => !(r.type === 'child_of' && r.targetId === sourceId && r.autoCreated)
+        );
+        if (targetRels.length !== (targetDoc.data._relationships || []).length) {
+          await store.update(targetId, { data: { _relationships: targetRels.length ? targetRels : undefined } });
+        }
+      }
+    } catch (_) {}
+  }
+
+  log.debug(`Relationship removed: ${sourceId} --[${type}]--> ${targetId}`);
+  return { removed: true };
+}
+
+/**
+ * Get all relationships for a document (outgoing).
+ * @returns {Promise<Relationship[]>}
+ */
+export async function getRelationships(store, sourceId) {
+  const doc = await store.get(sourceId);
+  if (!doc) return [];
+  return (doc.data._relationships || []).map(r => ({
+    ...r,
+    sourceId,
+    sourceType: doc.type,
+    sourceTitle: doc.data?.title || doc.data?.name || ''
+  }));
+}
+
+/**
+ * Find documents that reference a target (incoming relationships).
+ */
+export async function getBacklinks(store, targetId) {
+  // Scan all documents — for larger datasets, this should use a dedicated index
+  const allDocs = await store.list({ limit: 10000 });
+  const backlinks = [];
+  for (const doc of allDocs) {
+    const rels = doc.data._relationships || [];
+    for (const r of rels) {
+      if (r.targetId === targetId) {
+        backlinks.push({
+          ...r,
+          sourceId: doc.id,
+          sourceType: doc.type,
+          sourceTitle: doc.data?.title || doc.data?.name || ''
+        });
+      }
+    }
+  }
+  return backlinks;
+}
+
+/**
+ * Get full relationship context (outgoing + incoming).
+ */
+export async function getAllRelationships(store, docId) {
+  const [outgoing, incoming] = await Promise.all([
+    getRelationships(store, docId),
+    getBacklinks(store, docId)
+  ]);
+  return { outgoing, incoming, total: outgoing.length + incoming.length };
+}
+
+/**
+ * Traverse relationship subgraph via BFS.
+ * @param {object} store
+ * @param {string} startId
+ * @param {object} opts
+ * @param {number} [opts.depth=2]       — max traversal depth
+ * @param {string[]} [opts.types]       — filter to specific relationship types
+ * @returns {Promise<{nodes: object[], edges: object[]}>}
+ */
+export async function traverseGraph(store, startId, opts = {}) {
+  const depth = opts.depth || 2;
+  const typeFilter = opts.types || null;
+
+  const visited = new Set();
+  const nodes = [];
+  const edges = [];
+  const queue = [{ id: startId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth: currentDepth } = queue.shift();
+    if (visited.has(id)) continue;
+    visited.add(id);
+
+    const doc = await store.get(id);
+    if (!doc) continue;
+
+    nodes.push({
+      id: doc.id,
+      type: doc.type,
+      title: doc.data?.title || doc.data?.name || '',
+      status: doc.status,
+      depth: currentDepth
+    });
+
+    if (currentDepth >= depth) continue;
+
+    const rels = doc.data._relationships || [];
+    for (const r of rels) {
+      if (typeFilter && !typeFilter.includes(r.type)) continue;
+      if (visited.has(r.targetId)) continue;
+
+      edges.push({
+        from: doc.id,
+        to: r.targetId,
+        type: r.type,
+        meta: r.meta || {}
+      });
+
+      queue.push({ id: r.targetId, depth: currentDepth + 1 });
+    }
+  }
+
+  return { nodes, edges };
+}

package/packages/server/src/revisions.js

@@ -0,0 +1,114 @@
+/**
+ * Version History — 内容版本管理与 Diff
+ *
+ * 每次 create/update 自动创建版本快照。
+ * API: GET /api/content/:type/:id/revisions
+ */
+
+import { getStore } from './context.js';
+import { createLogger } from './logger.js';
+import { randomUUID } from 'node:crypto';
+
+const log = createLogger('revision');
+const MAX_REVISIONS = parseInt(process.env.TAICHU_MAX_REVISIONS) || 100;
+
+/**
+ * Snapshot a document revision.
+ * Called after create or update.
+ */
+export async function snapshotRevision(doc, actor = {}) {
+  try {
+    const store = getStore();
+
+    // Get current revision count for this document
+    const existing = await store.list({ type: 'revision', limit: MAX_REVISIONS });
+    const docRevisions = existing.filter(r => r.data.docId === doc.id);
+
+    // Delete oldest if over limit
+    if (docRevisions.length >= MAX_REVISIONS) {
+      const oldest = docRevisions.sort((a, b) => new Date(a.createdAt) - new Date(b.createdAt))[0];
+      if (oldest) await store.delete(oldest.id);
+    }
+
+    await store.create({
+      type: 'revision',
+      data: {
+        docId: doc.id,
+        docType: doc.type,
+        data: doc.data,
+        status: doc.status,
+        meta: doc.meta || {},
+        author: actor.id || 'system',
+        authorType: actor.type || 'system',
+        timestamp: doc.updatedAt || new Date().toISOString()
+      },
+      status: 'active'
+    });
+  } catch (err) {
+    log.error(`Failed to snapshot revision for ${doc.id}: ${err.message}`);
+  }
+}
+
+/**
+ * Get revision history for a document.
+ */
+export async function getRevisions(docId, limit = 20) {
+  const store = getStore();
+  const docs = await store.list({ type: 'revision', limit: 200 });
+  return docs
+    .filter(r => r.data.docId === docId)
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit)
+    .map(r => ({
+      id: r.id,
+      timestamp: r.data.timestamp || r.createdAt,
+      status: r.data.status,
+      author: r.data.author,
+      authorType: r.data.authorType,
+      docType: r.data.docType,
+      data: r.data.data,
+      meta: r.data.meta
+    }));
+}
+
+/**
+ * Restore a document to a specific revision.
+ */
+export async function restoreRevision(docId, revisionId) {
+  const store = getStore();
+  const revisions = await getRevisions(docId, 200);
+  const rev = await store.get(revisionId);
+
+  if (!rev || rev.type !== 'revision') return null;
+
+  const doc = await store.get(docId);
+  if (!doc) return null;
+
+  return store.update(docId, {
+    data: rev.data.data,
+    status: rev.data.status,
+    meta: rev.data.meta
+  });
+}
+
+/**
+ * Simple field-level diff between two objects.
+ */
+export function diffObjects(oldData, newData) {
+  const changes = [];
+  const allKeys = new Set([...Object.keys(oldData || {}), ...Object.keys(newData || {})]);
+
+  for (const key of allKeys) {
+    const oldVal = JSON.stringify(oldData?.[key]);
+    const newVal = JSON.stringify(newData?.[key]);
+    if (oldVal !== newVal) {
+      changes.push({
+        field: key,
+        from: oldData?.[key],
+        to: newData?.[key]
+      });
+    }
+  }
+
+  return changes;
+}