@claudelaw/taichu 0.6.0

package/packages/core/src/content-type.js

@@ -0,0 +1,244 @@
+/**
+ * Content Type — 内容类型的 Schema 定义
+ *
+ * 类比 WordPress 的 post_type，但：
+ *   - 字段是强类型的（string / number / boolean / relation / media / json）
+ *   - 内置 semantic layer（schema.org 映射）
+ *   - 支持字段验证规则
+ *   - Agent 可遍历的元数据
+ *
+ * 使用示例：
+ *   const Article = createContentType('article', {
+ *     label: '文章',
+ *     description: '博客文章内容类型',
+ *     schemaOrg: 'Article',
+ *     fields: {
+ *       title:       { type: 'string', required: true, maxLength: 200 },
+ *       slug:        { type: 'string', required: true, pattern: /^[a-z0-9-]+$/ },
+ *       body:        { type: 'json', required: true },
+ *       excerpt:     { type: 'string', maxLength: 500 },
+ *       featuredImage: { type: 'media' },
+ *       tags:        { type: 'array', items: { type: 'string' } },
+ *       category:    { type: 'relation', target: 'category' },
+ *       status:      { type: 'enum', values: ['draft', 'published', 'archived'] },
+ *       publishedAt: { type: 'datetime' }
+ *     }
+ *   });
+ */
+
+import { ValidationError } from './errors.js';
+
+const VALID_FIELD_TYPES = [
+  'string', 'number', 'boolean',
+  'json', 'array', 'enum',
+  'datetime', 'media', 'relation'
+];
+
+/**
+ * @param {string} name — 内容类型标识符，如 'article', 'category', 'page'
+ * @param {object} definition
+ * @param {string} definition.label — 人类可读名称
+ * @param {string} [definition.description]
+ * @param {string} [definition.schemaOrg] — schema.org 类型映射，如 'Article', 'Product'
+ * @param {Record<string, FieldDef>} definition.fields
+ * @returns {ContentType}
+ */
+export function createContentType(name, definition) {
+  if (!name || typeof name !== 'string') {
+    throw new ValidationError('Content type name is required and must be a string');
+  }
+  if (!/^[a-z][a-z0-9_]*$/.test(name)) {
+    throw new ValidationError(`Invalid content type name: "${name}". Must be lowercase, start with a letter, and contain only letters, numbers, and underscores.`);
+  }
+  if (!definition || !definition.fields) {
+    throw new ValidationError(`Content type "${name}" must define at least one field`);
+  }
+
+  const fields = {};
+  const requiredFields = [];
+
+  for (const [fieldName, fieldDef] of Object.entries(definition.fields)) {
+    const def = normalizeFieldDef(fieldName, fieldDef);
+    fields[fieldName] = def;
+    if (def.required) requiredFields.push(fieldName);
+  }
+
+  const ct = {
+    name,
+    label: definition.label || name,
+    description: definition.description || '',
+    schemaOrg: definition.schemaOrg || null,
+    fields,
+    requiredFields,
+    features: definition.features || {},
+
+    /**
+     * Validate a document against this content type's schema.
+     * Returns { valid: true } or { valid: false, errors: [...] }
+     */
+    validate(doc) {
+      const errors = [];
+      if (!doc || typeof doc !== 'object') {
+        return { valid: false, errors: ['Document must be an object'] };
+      }
+
+      for (const fieldName of requiredFields) {
+        if (doc[fieldName] === undefined || doc[fieldName] === null || doc[fieldName] === '') {
+          errors.push(`Field "${fieldName}" is required`);
+        }
+      }
+
+      for (const [fieldName, value] of Object.entries(doc)) {
+        const fieldDef = fields[fieldName];
+        if (!fieldDef) {
+          // Unknown fields are silently accepted (extensibility)
+          continue;
+        }
+        const fieldErrors = validateField(fieldName, value, fieldDef);
+        errors.push(...fieldErrors);
+      }
+
+      return errors.length === 0
+        ? { valid: true }
+        : { valid: false, errors };
+    },
+
+    /**
+     * Return a JSON Schema representation of this content type.
+     * Useful for API documentation and OpenAPI generation.
+     */
+    toJSONSchema() {
+      const properties = {};
+      const required = [...requiredFields];
+
+      for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        properties[fieldName] = fieldToJSONSchema(fieldDef);
+      }
+
+      return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: this.label,
+        description: this.description,
+        type: 'object',
+        properties,
+        required: required.length > 0 ? required : undefined
+      };
+    }
+  };
+
+  // Freeze to prevent runtime mutations
+  return Object.freeze(ct);
+}
+
+function normalizeFieldDef(name, raw) {
+  if (typeof raw === 'string') {
+    return { type: raw, required: false, label: name };
+  }
+
+  const type = raw.type || 'string';
+  if (!VALID_FIELD_TYPES.includes(type)) {
+    throw new ValidationError(
+      `Field "${name}": invalid type "${type}". Valid types: ${VALID_FIELD_TYPES.join(', ')}`
+    );
+  }
+
+  return {
+    type,
+    required: raw.required || false,
+    label: raw.label || name,
+    description: raw.description || '',
+    default: raw.default,
+    maxLength: raw.maxLength,
+    pattern: raw.pattern ? raw.pattern.source : undefined,
+    values: raw.values,          // for enum
+    items: raw.items || null,    // for array
+    target: raw.target || null,  // for relation
+    indexed: raw.indexed !== false, // default indexed
+    semantic: raw.semantic || null  // schema.org property mapping
+  };
+}
+
+function validateField(fieldName, value, fieldDef) {
+  const errors = [];
+
+  if (value === undefined || value === null) {
+    if (fieldDef.required) {
+      errors.push(`Field "${fieldName}" is required`);
+    }
+    return errors;
+  }
+
+  switch (fieldDef.type) {
+    case 'string':
+      if (typeof value !== 'string') errors.push(`Field "${fieldName}" must be a string`);
+      else if (fieldDef.maxLength && value.length > fieldDef.maxLength) {
+        errors.push(`Field "${fieldName}" exceeds max length of ${fieldDef.maxLength}`);
+      }
+      break;
+    case 'number':
+      if (typeof value !== 'number') errors.push(`Field "${fieldName}" must be a number`);
+      break;
+    case 'boolean':
+      if (typeof value !== 'boolean') errors.push(`Field "${fieldName}" must be a boolean`);
+      break;
+    case 'enum':
+      if (!fieldDef.values.includes(value)) {
+        errors.push(`Field "${fieldName}" must be one of: ${fieldDef.values.join(', ')}`);
+      }
+      break;
+    case 'array':
+      if (!Array.isArray(value)) errors.push(`Field "${fieldName}" must be an array`);
+      break;
+    case 'json':
+      // Accept any valid JSON-serializable value
+      break;
+    case 'datetime':
+      if (typeof value !== 'string' || isNaN(Date.parse(value))) {
+        errors.push(`Field "${fieldName}" must be a valid datetime string`);
+      }
+      break;
+    case 'date':
+      if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        errors.push(`Field "${fieldName}" must be a valid date string (YYYY-MM-DD)`);
+      }
+      break;
+    case 'reference':
+      if (typeof value !== 'string' || !value) {
+        errors.push(`Field "${fieldName}" must be a valid reference ID`);
+      }
+      break;
+    case 'media':
+      // Media can be a string (id) or object (with url, alt, etc.)
+      if (typeof value !== 'string' && typeof value !== 'object') {
+        errors.push(`Field "${fieldName}" must be a media reference`);
+      }
+      break;
+    case 'relation':
+      // Relation can be a string (id) or array of strings
+      if (typeof value !== 'string' && !Array.isArray(value)) {
+        errors.push(`Field "${fieldName}" must be a relation reference`);
+      }
+      break;
+  }
+
+  return errors;
+}
+
+function fieldToJSONSchema(fieldDef) {
+  const base = { title: fieldDef.label, description: fieldDef.description };
+
+  switch (fieldDef.type) {
+    case 'string':   return { ...base, type: 'string', maxLength: fieldDef.maxLength };
+    case 'number':   return { ...base, type: 'number' };
+    case 'boolean':  return { ...base, type: 'boolean' };
+    case 'enum':     return { ...base, type: 'string', enum: fieldDef.values };
+    case 'date':     return { ...base, type: 'string', format: 'date' };
+    case 'datetime': return { ...base, type: 'string', format: 'date-time' };
+    case 'reference': return { ...base, type: 'string', description: `Reference to ${fieldDef.refType || 'document'}` };
+    case 'array':    return { ...base, type: 'array', items: fieldDef.items || { type: 'string' } };
+    case 'json':     return { ...base };  // free-form
+    case 'media':    return { ...base, oneOf: [{ type: 'string' }, { type: 'object' }] };
+    case 'relation': return { ...base, oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] };
+    default:         return base;
+  }
+}

package/packages/core/src/core.test.js

@@ -0,0 +1,406 @@
+/**
+ * @taichu/core — 核心模块测试
+ *
+ * 运行: node --test packages/core/src/core.test.js
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { createContentType } from './content-type.js';
+import { createMemoryStore } from './store.js';
+import { createHookSystem } from './hooks.js';
+import { hashPassword, verifyPassword, signJWT, verifyJWT, generateAPIKey, verifyAPIKey } from './auth.js';
+import { TaichuError, ValidationError, NotFoundError, UnauthorizedError, ForbiddenError, ConflictError } from './errors.js';
+import { createHmac } from 'node:crypto';
+
+// ════════════════════════════════════════════════════════════
+// Content Type
+// ════════════════════════════════════════════════════════════
+
+describe('ContentType', () => {
+  it('should create a content type with fields', () => {
+    const Article = createContentType('article', {
+      label: '文章',
+      fields: {
+        title: { type: 'string', required: true, maxLength: 200 },
+        slug:  { type: 'string', required: true },
+        tags:  { type: 'array', items: { type: 'string' } }
+      }
+    });
+
+    assert.equal(Article.name, 'article');
+    assert.equal(Article.label, '文章');
+    assert.equal(Object.keys(Article.fields).length, 3);
+  });
+
+  it('should validate a valid document', () => {
+    const Article = createContentType('article', {
+      fields: {
+        title: { type: 'string', required: true },
+        body:  { type: 'json' }
+      }
+    });
+
+    const result = Article.validate({ title: 'Hello', body: {} });
+    assert.equal(result.valid, true);
+  });
+
+  it('should reject missing required fields', () => {
+    const Article = createContentType('article', {
+      fields: { title: { type: 'string', required: true } }
+    });
+
+    const result = Article.validate({});
+    assert.equal(result.valid, false);
+    assert.equal(result.errors.length, 1);
+  });
+
+  it('should validate string maxLength', () => {
+    const Article = createContentType('article', {
+      fields: { title: { type: 'string', maxLength: 10 } }
+    });
+
+    const result = Article.validate({ title: 'this is way too long' });
+    assert.equal(result.valid, false);
+  });
+
+  it('should validate enum values', () => {
+    const Article = createContentType('article', {
+      fields: { status: { type: 'enum', values: ['draft', 'published'] } }
+    });
+
+    assert.equal(Article.validate({ status: 'draft' }).valid, true);
+    assert.equal(Article.validate({ status: 'deleted' }).valid, false);
+  });
+
+  it('should export JSON Schema', () => {
+    const Article = createContentType('article', {
+      label: '文章',
+      schemaOrg: 'Article',
+      fields: {
+        title: { type: 'string', required: true },
+        tags:  { type: 'array', items: { type: 'string' } }
+      }
+    });
+
+    const schema = Article.toJSONSchema();
+    assert.equal(schema.title, '文章');
+    assert.equal(schema.type, 'object');
+    assert.ok(schema.required.includes('title'));
+  });
+});
+
+// ════════════════════════════════════════════════════════════
+// Store (Memory)
+// ════════════════════════════════════════════════════════════
+
+describe('MemoryStore', () => {
+  it('should create and retrieve a document', async () => {
+    const store = createMemoryStore();
+    const doc = await store.create({ type: 'article', data: { title: 'Test' } });
+
+    assert.ok(doc.id);
+    assert.equal(doc.type, 'article');
+    assert.equal(doc.data.title, 'Test');
+    assert.equal(doc.status, 'draft');
+
+    const got = await store.get(doc.id);
+    assert.equal(got.data.title, 'Test');
+  });
+
+  it('should list documents by type', async () => {
+    const store = createMemoryStore();
+    await store.create({ type: 'article', data: { title: 'A' } });
+    await store.create({ type: 'article', data: { title: 'B' } });
+    await store.create({ type: 'page',    data: { title: 'C' } });
+
+    const articles = await store.list({ type: 'article' });
+    assert.equal(articles.length, 2);
+
+    const pages = await store.list({ type: 'page' });
+    assert.equal(pages.length, 1);
+  });
+
+  it('should filter by status', async () => {
+    const store = createMemoryStore();
+    await store.create({ type: 'article', data: { title: 'A' }, status: 'draft' });
+    await store.create({ type: 'article', data: { title: 'B' }, status: 'published' });
+
+    const drafts = await store.list({ type: 'article', status: 'draft' });
+    assert.equal(drafts.length, 1);
+  });
+
+  it('should update a document', async () => {
+    const store = createMemoryStore();
+    const doc = await store.create({ type: 'article', data: { title: 'Old' } });
+
+    const updated = await store.update(doc.id, { data: { title: 'New' } });
+    assert.equal(updated.data.title, 'New');
+  });
+
+  it('should delete a document', async () => {
+    const store = createMemoryStore();
+    const doc = await store.create({ type: 'article', data: {} });
+
+    const deleted = await store.delete(doc.id);
+    assert.equal(deleted, true);
+
+    const got = await store.get(doc.id);
+    assert.equal(got, null);
+  });
+
+  it('should count documents', async () => {
+    const store = createMemoryStore();
+    await store.create({ type: 'article', data: {} });
+    await store.create({ type: 'article', data: {} });
+    await store.create({ type: 'page',    data: {} });
+
+    const count = await store.count({ type: 'article' });
+    assert.equal(count, 2);
+  });
+});
+
+// ════════════════════════════════════════════════════════════
+// Hook System
+// ════════════════════════════════════════════════════════════
+
+describe('HookSystem', () => {
+  it('should run registered hooks', async () => {
+    const hooks = createHookSystem();
+    const calls = [];
+
+    hooks.on('test', async (payload) => {
+      calls.push(payload);
+    });
+
+    await hooks.run('test', 'hello');
+    assert.deepEqual(calls, ['hello']);
+  });
+
+  it('should run hooks in priority order', async () => {
+    const hooks = createHookSystem();
+    const order = [];
+
+    hooks.on('test', () => { order.push('low'); }, 20);
+    hooks.on('test', () => { order.push('high'); }, 5);
+
+    await hooks.run('test', null);
+    assert.deepEqual(order, ['high', 'low']);
+  });
+
+  it('should pass payload through hooks', async () => {
+    const hooks = createHookSystem();
+
+    hooks.on('transform', async (payload) => (typeof payload === 'string' ? payload.toUpperCase() : null));
+
+    const result = await hooks.run('transform', 'hello');
+    assert.equal(result, 'HELLO');
+  });
+
+  it('should stop chain when handler returns null', async () => {
+    const hooks = createHookSystem();
+    const calls = [];
+
+    hooks.on('test', () => { calls.push(1); return null; });
+    hooks.on('test', () => { calls.push(2); });
+
+    await hooks.run('test', null);
+    assert.deepEqual(calls, [1]);
+  });
+
+  it('should deregister hooks', async () => {
+    const hooks = createHookSystem();
+    const calls = [];
+
+    const dereg = hooks.on('test', () => { calls.push(1); });
+    dereg();
+    await hooks.run('test', null);
+
+    assert.deepEqual(calls, []);
+  });
+});
+
+// ════════════════════════════════════════════════════════════
+// Auth
+// ════════════════════════════════════════════════════════════
+
+describe('Password Hashing', () => {
+  it('should hash and verify a password', () => {
+    const hashed = hashPassword('taichu2026');
+    assert.ok(hashed.startsWith('pbkdf2_sha256$'));
+
+    assert.equal(verifyPassword('taichu2026', hashed), true);
+  });
+
+  it('should reject wrong password', () => {
+    const hashed = hashPassword('correct');
+    assert.equal(verifyPassword('wrong', hashed), false);
+  });
+
+  it('should produce different hashes for same password', () => {
+    const h1 = hashPassword('test');
+    const h2 = hashPassword('test');
+    assert.notEqual(h1, h2, 'Salt should produce different hashes');
+    assert.equal(verifyPassword('test', h1), true);
+    assert.equal(verifyPassword('test', h2), true);
+  });
+
+  it('should handle malformed hash gracefully', () => {
+    assert.equal(verifyPassword('test', 'bad_hash'), false);
+  });
+});
+
+describe('JWT', () => {
+  const secret = 'test-secret-key-32-chars-long!!';
+
+  it('should sign and verify a JWT', () => {
+    const token = signJWT({ sub: 'user-1', role: 'admin' }, secret, { expiresIn: '1h' });
+    assert.ok(typeof token === 'string');
+
+    const result = verifyJWT(token, secret);
+    assert.equal(result.valid, true);
+    assert.equal(result.payload.sub, 'user-1');
+    assert.equal(result.payload.role, 'admin');
+  });
+
+  it('should reject tokens with exp in the past', () => {
+    const expiredPayload = { sub: 'user-1', iat: Math.floor(Date.now() / 1000) - 7200, exp: Math.floor(Date.now() / 1000) - 3600 };
+    const header = JSON.stringify({ alg: 'HS256', typ: 'JWT' });
+    const headerB64 = Buffer.from(header).toString('base64url');
+    const payloadB64 = Buffer.from(JSON.stringify(expiredPayload)).toString('base64url');
+    const sig = createHmac('sha256', secret).update(`${headerB64}.${payloadB64}`).digest('base64url');
+    const token = `${headerB64}.${payloadB64}.${sig}`;
+
+    const result = verifyJWT(token, secret);
+    assert.equal(result.valid, false);
+    assert.equal(result.error, 'Token expired');
+  });
+
+  it('should reject tokens with wrong secret', () => {
+    const token = signJWT({ sub: 'user-1' }, secret);
+    const result = verifyJWT(token, 'wrong-secret');
+    assert.equal(result.valid, false);
+  });
+});
+
+describe('API Key', () => {
+  it('should generate a valid API key', () => {
+    const key = generateAPIKey('Test Agent');
+    assert.ok(key.key.startsWith('taichu_'));
+    assert.ok(key.prefix.startsWith('taichu_'));
+    assert.equal(key.label, 'Test Agent');
+    assert.equal(key.key.length, 71); // taichu_ + 64 hex chars
+  });
+
+  it('should verify a valid API key', () => {
+    const key = generateAPIKey('Test');
+    assert.equal(verifyAPIKey(key.key, key.hash), true);
+  });
+
+  it('should reject invalid API key', () => {
+    const key = generateAPIKey('Test');
+    assert.equal(verifyAPIKey('taichu_fake', key.hash), false);
+  });
+
+  it('should produce different keys each time', () => {
+    const k1 = generateAPIKey();
+    const k2 = generateAPIKey();
+    assert.notEqual(k1.key, k2.key);
+    assert.notEqual(k1.hash, k2.hash);
+  });
+});
+
+// ════════════════════════════════════════════════════════════
+// Errors
+// ════════════════════════════════════════════════════════════
+
+describe('TaichuError', () => {
+  it('should create a base error', () => {
+    const err = new TaichuError('test');
+    assert.equal(err.message, 'test');
+    assert.equal(err.status, 500);
+    assert.equal(err.code, 'TAICHU_ERROR');
+  });
+
+  it('should create typed errors with correct status codes', () => {
+    assert.equal(new ValidationError('bad').status, 400);
+    assert.equal(new NotFoundError('missing').status, 404);
+    assert.equal(new UnauthorizedError('nope').status, 401);
+    assert.equal(new ForbiddenError('no').status, 403);
+    assert.equal(new ConflictError('dup').status, 409);
+  });
+
+  it('should serialize to JSON', () => {
+    const err = new ValidationError('Invalid title');
+    const json = err.toJSON();
+    assert.equal(json.error, 'VALIDATION_ERROR');
+    assert.equal(json.message, 'Invalid title');
+    assert.equal(json.status, 400);
+  });
+
+  it('should report type conflicts', () => {
+    try {
+      new ConflictError('duplicate');
+      assert.ok(true);
+    } catch {
+      assert.fail('Should not throw');
+    }
+  });
+});
+
+// ════════════════════════════════════════════════════════════
+// Tokenizer
+// ════════════════════════════════════════════════════════════
+
+describe('Tokenizer', () => {
+  it('should tokenize Chinese text (n-gram fallback)', async () => {
+    const { tokenize } = await import('./tokenizer.js');
+    const tokens = tokenize('人工智能正在改变内容管理');
+    assert.ok(tokens.length > 0);
+    // Should find 2-grams like 人工, 工智, 智能 etc.
+    assert.ok(tokens.includes('智能'));
+  });
+
+  it('should tokenize English text', async () => {
+    const { tokenize } = await import('./tokenizer.js');
+    const tokens = tokenize('AI is changing content management');
+    assert.ok(tokens.includes('changing'));
+    assert.ok(tokens.includes('content'));
+  });
+
+  it('should filter stopwords', async () => {
+    const { tokenize } = await import('./tokenizer.js');
+    const tokens = tokenize('这是一个测试内容');
+    assert.ok(!tokens.includes('了'));
+    assert.ok(!tokens.includes('的'));
+  });
+});
+
+// ════════════════════════════════════════════════════════════
+// Vector Index
+// ════════════════════════════════════════════════════════════
+
+describe('VectorIndex', () => {
+  it('should index and search documents', async () => {
+    const { TFIDFIndex } = await import('./vector-index.js');
+    const idx = new TFIDFIndex();
+    idx.add('1', 'artificial intelligence content management');
+    idx.add('2', 'machine learning deep learning neural networks');
+    idx.add('3', 'content management system headless cms');
+
+    const results = idx.search('content management system');
+    assert.ok(results.length > 0);
+    // '3' has "content management system headless cms" — most relevant
+    assert.equal(results[0].docId, '3');
+  });
+
+  it('should return empty for no match', async () => {
+    const { TFIDFIndex } = await import('./vector-index.js');
+    const idx = new TFIDFIndex();
+    idx.add('1', 'hello world');
+
+    const results = idx.search('zzz');
+    assert.equal(results.length, 0);
+  });
+});