devassist-agent 1.0.0

package/src/modules/dev-time/pre-deploy-guard.js

@@ -0,0 +1,284 @@
+/**
+ * PreDeployGuard - pre-deployment configuration checks.
+ *
+ * Defense target: "Deployment config errors" (27% of 88 failures).
+ *   #1  - port 8080 occupied by supervisord
+ *   #3  - deployment directory confusion (container vs host)
+ *   #10 - MIME type misconfigured for .js files
+ *   #11 - nginx route interception (static files blocked by proxy_pass)
+ *   #13 - deployment file omission (forgot to copy config)
+ *
+ * This module runs BEFORE deploy to catch all of these.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+const { Logger } = require('../../core/logger');
+const log = new Logger('PreDeployGuard');
+
+class PreDeployGuard {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * Check if a TCP port is available.
+   * Failure #1: supervisord occupied port 8080, app couldn't start.
+   */
+  async checkPort(port, host) {
+    host = host || '127.0.0.1';
+    return new Promise((resolve) => {
+      const tester = net.createServer()
+        .once('error', (err) => {
+          if (err.code === 'EADDRINUSE') {
+            resolve({
+              ruleId: 'pd-port-in-use',
+              severity: 'block',
+              category: 'pre-deploy',
+              message: `端口 ${port} 已被占用，应用将无法启动。`,
+              file: '(network)',
+              suggestion: `查找并终止占用端口 ${port} 的进程，或更换应用端口。执行：lsof -i :${port}（Linux/Mac）或 netstat -ano | findstr :${port}（Windows）`,
+              context: { port, host },
+            });
+          } else {
+            resolve({ ruleId: 'pd-port-check', severity: 'info', category: 'pre-deploy', message: `端口 ${port} 检查出错：${err.code}`, file: '(network)' });
+          }
+        })
+        .once('listening', () => {
+          tester.close();
+          resolve(null); // port is free
+        })
+        .listen(port, host);
+    });
+  }
+
+  /**
+   * Check nginx/routing config for common issues.
+   * Failure #11: nginx proxy_pass intercepted static file routes.
+   */
+  checkRouting(configPath) {
+    const findings = [];
+    const nginxConf = configPath || path.join(this.projectRoot, 'nginx.conf');
+    let content = '';
+    try { content = fs.readFileSync(nginxConf, 'utf-8'); } catch (_) { return findings; }
+
+    // Check: proxy_pass without excluding static files
+    if (/proxy_pass\s+http:\/\//.test(content) && !/location\s+.*\.(js|css|png|jpg|html)/.test(content)) {
+      findings.push({
+        ruleId: 'pd-nginx-static-intercept',
+        severity: 'block',
+        category: 'pre-deploy',
+        message: `nginx 配置了 proxy_pass 但没有显式的静态文件 location 块，静态文件可能被代理拦截。`,
+        file: nginxConf,
+        suggestion: `在 proxy_pass 之前添加静态文件的 location 块。示例：\n  location ~* \\.(js|css|png|jpg|jpeg|gif|ico|html)$ { root /your/static/path; }`,
+      });
+    }
+
+    // Check: try_files with fallback to index.html (SPA routing)
+    if (/try_files/.test(content) && !/index\.html/.test(content)) {
+      findings.push({
+        ruleId: 'pd-nginx-no-spa-fallback',
+        severity: 'warn',
+        category: 'pre-deploy',
+        message: `try_files 指令缺少 index.html 回退——SPA 路由刷新时会 404。`,
+        file: nginxConf,
+        suggestion: `在 location 块中添加 'try_files $uri $uri/ /index.html;'`,
+      });
+    }
+
+    return findings;
+  }
+
+  /**
+   * Check MIME type configuration.
+   * Failure #10: .js files served as text/plain, browser refused to execute.
+   */
+  checkMimeTypes(configPath) {
+    const findings = [];
+    const mimeFile = configPath || path.join(this.projectRoot, 'mime.types');
+
+    // Check nginx config for MIME types
+    const nginxConf = path.join(this.projectRoot, 'nginx.conf');
+    if (fs.existsSync(nginxConf)) {
+      const content = fs.readFileSync(nginxConf, 'utf-8');
+      if (!/include\s+.*mime\.types/.test(content) && !/types\s*\{/.test(content)) {
+        findings.push({
+          ruleId: 'pd-mime-missing',
+          severity: 'block',
+          category: 'pre-deploy',
+          message: `nginx.conf 中未找到 MIME 类型配置，.js 文件可能以 text/plain 提供。`,
+          file: nginxConf,
+          suggestion: `添加 'include mime.types;' 或定义 types 块：\n  types { text/javascript js; text/css css; ... }`,
+        });
+      }
+    }
+
+    // Check Express static config
+    const files = this._findFiles(this.projectRoot, /\.(js|ts)$/, ['node_modules', '.git']);
+    for (const file of files) {
+      let content = '';
+      try { content = fs.readFileSync(file, 'utf-8'); } catch (_) { continue; }
+      if (/express\.static/.test(content) && !/setHeaders|mime/.test(content)) {
+        // This is just an info — Express handles MIME by default, but worth noting
+        findings.push({
+          ruleId: 'pd-express-mime',
+          severity: 'info',
+          category: 'pre-deploy',
+          message: `express.static 未显式配置 MIME。默认行为通常没问题，但建议验证 .js 文件以 application/javascript 提供。`,
+          file: file,
+          suggestion: `如遇 MIME 问题，可配置：express.static(path, { setHeaders: (res, path) => { ... } })`,
+        });
+        break; // one is enough
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Check deployment file manifest.
+   * Failure #13: forgot to copy config file to deployment directory.
+   */
+  checkDeployManifest(manifestPath) {
+    const findings = [];
+    const manifestFile = manifestPath || path.join(this.projectRoot, '.devassist', 'deploy-manifest.json');
+
+    if (!fs.existsSync(manifestFile)) {
+      findings.push({
+        ruleId: 'pd-no-manifest',
+        severity: 'warn',
+        category: 'pre-deploy',
+        message: `未找到部署清单文件，部署时可能遗漏文件。`,
+        file: manifestFile,
+        suggestion: `创建 .devassist/deploy-manifest.json 列出所有必须部署的文件。执行：devassist init`,
+      });
+      return findings;
+    }
+
+    let manifest;
+    try { manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf-8')); } catch (err) {
+      findings.push({
+        ruleId: 'pd-manifest-invalid',
+        severity: 'block',
+        category: 'pre-deploy',
+        message: `部署清单 JSON 无效：${err.message}`,
+        file: manifestFile,
+      });
+      return findings;
+    }
+
+    // Verify every file in manifest exists
+    const files = manifest.files || [];
+    for (const entry of files) {
+      const fullPath = path.join(this.projectRoot, entry.path || entry);
+      if (!fs.existsSync(fullPath)) {
+        findings.push({
+          ruleId: 'pd-missing-file',
+          severity: 'block',
+          category: 'pre-deploy',
+          message: `部署清单引用了不存在的文件：${entry.path || entry}`,
+          file: fullPath,
+          suggestion: `创建该文件或从清单中移除。对应故障 #13：部署时遗漏文件。`,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Check for Cache-Busting configuration.
+   * Failure #15: users got old cached version after deployment.
+   */
+  checkCacheBusting() {
+    const findings = [];
+    const indexHtml = path.join(this.projectRoot, 'index.html');
+    if (!fs.existsSync(indexHtml)) return findings;
+
+    const content = fs.readFileSync(indexHtml, 'utf-8');
+
+    // Check if JS/CSS references have version query strings or hashes
+    const scriptTags = content.match(/<script[^>]+src=["'][^"']+["'][^>]*>/g) || [];
+    for (const tag of scriptTags) {
+      const srcMatch = tag.match(/src=["']([^"']+)["']/);
+      if (srcMatch && !/[?&]v=|[\?&]\w{8,}\./.test(srcMatch[1]) && !srcMatch[1].includes('cdn')) {
+        findings.push({
+          ruleId: 'pd-no-cache-bust',
+          severity: 'warn',
+          category: 'pre-deploy',
+          message: `脚本引用缺少缓存失效标记：${srcMatch[1]}`,
+          file: indexHtml,
+          suggestion: `添加版本查询参数（?v=时间戳）或内容哈希以防止旧缓存。对应故障 #15：部署后用户获取旧版本。`,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Run all pre-deploy checks.
+   */
+  async runAll(config) {
+    const allFindings = [];
+
+    // Port check
+    if (config && config.port) {
+      const portResult = await this.checkPort(config.port);
+      if (portResult) allFindings.push(portResult);
+    }
+
+    // Routing check
+    allFindings.push(...this.checkRouting());
+
+    // MIME check
+    allFindings.push(...this.checkMimeTypes());
+
+    // Manifest check
+    allFindings.push(...this.checkDeployManifest());
+
+    // Cache-busting check
+    allFindings.push(...this.checkCacheBusting());
+
+    log.info(`部署前检查完成：${allFindings.length} 个发现（${allFindings.filter(f => f.severity === 'block').length} 个阻断）`);
+    return allFindings;
+  }
+
+  _findDir(dir, maxDepth, currentDepth) {
+    const results = [];
+    if (currentDepth >= maxDepth) return results;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return results; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name === 'static' || entry.name === 'public') {
+          results.push(path.join(dir, entry.name));
+        }
+        if (!['node_modules', '.git', 'dist', 'build'].includes(entry.name)) {
+          results.push(...this._findDir(path.join(dir, entry.name), maxDepth, currentDepth + 1));
+        }
+      }
+    }
+    return results;
+  }
+
+  _findFiles(dir, extRegex, skipDirs) {
+    const results = [];
+    const walk = (d) => {
+      let entries;
+      try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { return; }
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (!skipDirs.includes(entry.name)) walk(path.join(d, entry.name));
+        } else if (extRegex.test(entry.name)) {
+          results.push(path.join(d, entry.name));
+        }
+      }
+    };
+    walk(dir);
+    return results;
+  }
+}
+
+module.exports = { PreDeployGuard };

package/src/modules/dev-time/schema-registry.js

@@ -0,0 +1,284 @@
+/**
+ * SchemaRegistry - DB schema + API contract registry.
+ *
+ * Defense target: "Codebase decay" (35/88 failures).
+ *   The worst pattern: data.list -> data.items -> data.records — three
+ *   variants of the same field appeared because there was no central registry.
+ *   Also: ChatSession fields added inside Docker container but not synced
+ *   to source code, causing schema drift.
+ *
+ * This module:
+ * 1. Tracks DB table structure versions
+ * 2. Detects schema drift (container vs source code)
+ * 3. Enforces API contract consistency (registered response shape vs actual)
+ * 4. Enforces "ADD-only, no DROP" discipline
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Logger } = require('../../core/logger');
+const log = new Logger('SchemaRegistry');
+
+class SchemaRegistry {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.configDir = path.join(projectRoot, '.devassist');
+    this.registryFile = path.join(this.configDir, 'schema-registry.json');
+    this.schemas = {};      // table -> { columns, version, history }
+    this.apiContracts = {}; // endpoint -> { responseShape, version }
+    this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this.registryFile)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(this.registryFile, 'utf-8'));
+        this.schemas = data.schemas || {};
+        this.apiContracts = data.apiContracts || {};
+        log.info(`已加载 ${Object.keys(this.schemas).length} 张表结构，${Object.keys(this.apiContracts).length} 个 API 契约`);
+      } catch (err) {
+        log.warn(`加载 Schema 注册中心失败：${err.message}`);
+      }
+    }
+  }
+
+  _save() {
+    if (!fs.existsSync(this.configDir)) fs.mkdirSync(this.configDir, { recursive: true });
+    fs.writeFileSync(this.registryFile, JSON.stringify({
+      schemas: this.schemas,
+      apiContracts: this.apiContracts,
+    }, null, 2), 'utf-8');
+  }
+
+  /**
+   * Register or update a DB table schema.
+   * @param {string} table - table name
+   * @param {object} schema - { columns: [{ name, type, nullable, default }], version }
+   */
+  registerTable(table, schema) {
+    const existing = this.schemas[table];
+    const newColumns = schema.columns || [];
+    const findings = [];
+
+    if (existing) {
+      // Detect removed columns (violation of ADD-only discipline)
+      const existingNames = existing.columns.map(c => c.name);
+      const newNames = newColumns.map(c => c.name);
+
+      const removed = existingNames.filter(n => !newNames.includes(n));
+      if (removed.length > 0) {
+        findings.push({
+          ruleId: 'sr-column-removed',
+          severity: 'block',
+          category: 'schema',
+          message: `表 '${table}' 删除了字段：${removed.join(', ')}。DROP COLUMN 需要显式批准。`,
+          file: '(database)',
+          suggestion: `恢复字段或获得对此 Schema 变更的显式批准。删除字段可能破坏引用它们的现有代码。`,
+          context: { table, removedColumns: removed },
+        });
+      }
+
+      // Detect new columns (allowed, but log for tracking)
+      const added = newNames.filter(n => !existingNames.includes(n));
+      if (added.length > 0) {
+        log.info(`表 '${table}' 新增字段：${added.join(', ')}（仅追加原则：通过）`);
+      }
+
+      // Detect type changes (dangerous)
+      for (const newCol of newColumns) {
+        const oldCol = existing.columns.find(c => c.name === newCol.name);
+        if (oldCol && oldCol.type !== newCol.type) {
+          findings.push({
+            ruleId: 'sr-type-changed',
+            severity: 'warn',
+            category: 'schema',
+            message: `字段 '${table}.${newCol.name}' 类型变更：${oldCol.type} -> ${newCol.type}`,
+            file: '(database)',
+            suggestion: `类型变更可能导致数据丢失。确保存在迁移脚本并用真实数据测试。`,
+            context: { table, column: newCol.name, oldType: oldCol.type, newType: newCol.type },
+          });
+        }
+      }
+
+      // Update with version bump
+      this.schemas[table] = {
+        ...schema,
+        version: (existing.version || 1) + 1,
+        history: [...(existing.history || []), { version: existing.version, columns: existing.columns, at: new Date().toISOString() }],
+      };
+    } else {
+      // New table
+      this.schemas[table] = { ...schema, version: 1, history: [] };
+      log.info(`注册新表：${table}`);
+    }
+
+    this._save();
+    return findings;
+  }
+
+  /**
+   * Register an API response contract.
+   * @param {string} endpoint - e.g. "GET /api/chat/list"
+   * @param {object} contract - { responseShape: { fields, dataKey } }
+   *
+   * dataKey is the key used for list responses — e.g. "data.list" means
+   * the API returns { code: 200, data: { list: [...] } }
+   */
+  registerAPI(endpoint, contract) {
+    const existing = this.apiContracts[endpoint];
+    this.apiContracts[endpoint] = { ...contract, version: existing ? existing.version + 1 : 1 };
+    this._save();
+    log.info(`注册 API 契约：${endpoint} (v${this.apiContracts[endpoint].version})`);
+  }
+
+  /**
+   * Check an API response against its registered contract.
+   * This catches the data.list -> data.items drift problem.
+   */
+  checkAPIResponse(endpoint, responseData) {
+    const contract = this.apiContracts[endpoint];
+    if (!contract) return null; // no contract registered, skip
+
+    const findings = [];
+    const expectedDataKey = contract.dataKey || 'data.list';
+
+    // Navigate to the expected data location
+    const keys = expectedDataKey.split('.');
+    let actual = responseData;
+    let found = true;
+    for (const key of keys) {
+      if (actual && typeof actual === 'object' && key in actual) {
+        actual = actual[key];
+      } else {
+        found = false;
+        break;
+      }
+    }
+
+    if (!found) {
+      // The registered data key doesn't exist — check if a variant is being used
+      const variants = this._findListVariants(responseData);
+      if (variants.length > 0) {
+        findings.push({
+          ruleId: 'sr-api-key-drift',
+          severity: 'block',
+          category: 'schema',
+          message: `API '${endpoint}' 返回 data.${variants[0]} 但契约期望 ${expectedDataKey}。这是"三变体"反模式。`,
+          file: endpoint,
+          suggestion: `修复 API 使其返回 ${expectedDataKey}，或在变更有意时更新契约。不要添加前端兼容补丁。`,
+          context: { endpoint, expected: expectedDataKey, actual: `data.${variants[0]}`, allVariants: variants },
+        });
+      } else {
+        findings.push({
+          ruleId: 'sr-api-missing-key',
+          severity: 'warn',
+          category: 'schema',
+          message: `API '${endpoint}' 响应缺少期望的键：${expectedDataKey}`,
+          file: endpoint,
+          suggestion: `检查 API 响应结构是否已变更。`,
+        });
+      }
+    }
+
+    // Check response shape fields
+    if (contract.responseShape && contract.responseShape.fields && found && Array.isArray(actual)) {
+      if (actual.length > 0) {
+        const firstItem = actual[0];
+        const expectedFields = contract.responseShape.fields;
+        const actualFields = Object.keys(firstItem);
+        const missingFields = expectedFields.filter(f => !actualFields.includes(f));
+        if (missingFields.length > 0) {
+          findings.push({
+            ruleId: 'sr-api-missing-fields',
+            severity: 'warn',
+            category: 'schema',
+            message: `API '${endpoint}' 响应条目缺少字段：${missingFields.join(', ')}`,
+            file: endpoint,
+            suggestion: `在 API 响应中添加缺失字段，或更新契约。`,
+          });
+        }
+      }
+    }
+
+    return findings.length > 0 ? findings : null;
+  }
+
+  /**
+   * Find list-like keys in a response object (detects data.list/items/records/rows variants).
+   */
+  _findListVariants(obj, prefix) {
+    const variants = [];
+    prefix = prefix || '';
+    if (!obj || typeof obj !== 'object') return variants;
+
+    const listLikeKeys = ['list', 'items', 'records', 'rows', 'data', 'results', 'array'];
+
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (Array.isArray(value) && listLikeKeys.includes(key)) {
+        variants.push(fullKey);
+      } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+        variants.push(...this._findListVariants(value, fullKey));
+      }
+    }
+    return variants;
+  }
+
+  /**
+   * Import schema from a SQL DDL file.
+   * Parses CREATE TABLE statements to extract column definitions.
+   */
+  importFromDDL(sqlContent) {
+    const findings = [];
+    const tableRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"]?(\w+)[`"]?\s*\(([^;]+)\)/gi;
+    let match;
+
+    while ((match = tableRegex.exec(sqlContent)) !== null) {
+      const tableName = match[1];
+      const body = match[2];
+
+      // Parse columns
+      const columns = [];
+      const lines = body.split(',').map(l => l.trim()).filter(l => l && !l.startsWith('--'));
+      for (const line of lines) {
+        // Skip constraints (PRIMARY KEY, FOREIGN KEY, etc.)
+        if (/^(PRIMARY|FOREIGN|UNIQUE|CONSTRAINT|INDEX|KEY)/i.test(line)) continue;
+
+        const colMatch = line.match(/[`"]?(\w+)[`"]?\s+(\w+)(?:\s*\([^)]+\))?(.*)/);
+        if (colMatch) {
+          columns.push({
+            name: colMatch[1],
+            type: colMatch[2].toUpperCase(),
+            nullable: !/NOT\s+NULL/i.test(colMatch[3] || ''),
+            default: (colMatch[3] || '').match(/DEFAULT\s+([\w'"]+)/i)?.[1] || null,
+          });
+        }
+      }
+
+      if (columns.length > 0) {
+        const tableFindings = this.registerTable(tableName, { columns });
+        findings.push(...tableFindings);
+      }
+    }
+
+    log.info(`从 DDL 导入 ${Object.keys(this.schemas).length} 张表`);
+    return findings;
+  }
+
+  getStats() {
+    return {
+      tables: Object.keys(this.schemas).length,
+      apiContracts: Object.keys(this.apiContracts).length,
+      totalColumns: Object.values(this.schemas).reduce((sum, t) => sum + (t.columns?.length || 0), 0),
+    };
+  }
+
+  exportSnapshot() {
+    return {
+      schemas: this.schemas,
+      apiContracts: this.apiContracts,
+    };
+  }
+}
+
+module.exports = { SchemaRegistry };