@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/check.ts

@@ -0,0 +1,441 @@
+/**
+ * harness check 命令
+ * 
+ * 检查约束是否满足（三层：Iron Laws / Guidelines / Tips）
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { exec, execSync } from 'child_process';
+import { execAsync } from '../../utils/exec';
+import { constraintChecker } from '../../core/constraints/checker';
+import { getAllConstraints, IRON_LAWS, GUIDELINES, TIPS } from '../../core/constraints/definitions';
+import { ProjectConfigLoader } from '../../core/project-config-loader';
+import { detectSourceRoots } from '../../utils/detect-source-roots';
+import type { ConstraintTrigger, ConstraintContext, ConstraintResult } from '../../types/constraint';
+
+export interface CheckOptions {
+  /** 预设名称 */
+  preset: string;
+  /** 是否只检查暂存文件 */
+  staged: boolean;
+  /** 触发条件 */
+  trigger?: ConstraintTrigger;
+  /** 项目路径 */
+  projectPath?: string;
+}
+
+/**
+ * 从 git diff 获取变更的文件
+ */
+async function getChangedFiles(staged: boolean): Promise<string[]> {
+  try {
+    const command = staged ? 'git diff --cached --name-only' : 'git diff --name-only';
+    const { stdout } = await execAsync(command);
+    return stdout.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 检查文件所在目录是否在 git HEAD 中不存在（即新目录）
+ */
+function isNewDirectory(projectPath: string, filePath: string): boolean {
+  const dir = path.dirname(filePath);
+  try {
+    const output = execSync(`git ls-tree HEAD -- "${dir}"`, { cwd: projectPath, stdio: 'pipe', encoding: 'utf-8' });
+    return String(output).trim().length === 0; // empty output = directory doesn't exist in HEAD
+  } catch {
+    return true; // command failed = assume new
+  }
+}
+
+/**
+ * 检测触发条件
+ */
+function detectTrigger(changedFiles: string[], options: CheckOptions): ConstraintTrigger {
+  if (options.trigger) return options.trigger;
+
+  // 根据变更文件推断触发条件
+  // 注意：不自动推断 code_implementation——那是 caller 的语义判断。
+  // pre-commit 无法区分"模板编辑"和"逻辑实现"，保守使用 file_modification。
+  const hasTestChange = changedFiles.some(f =>
+    f.includes('.test.') || f.includes('.spec.') || f.includes('__tests__')
+  );
+  const sourceRoots = detectSourceRoots(options.projectPath || process.cwd());
+  const hasModuleChange = changedFiles.some(f =>
+    sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) && !f.includes('__tests__')
+  );
+  const projectPath = options.projectPath || process.cwd();
+  const hasModuleCreation = changedFiles.some(f =>
+    sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) &&
+    isNewDirectory(projectPath, f)
+  );
+
+  if (hasTestChange && !hasModuleChange) return 'test_creation';
+  if (hasModuleCreation) return 'module_creation';
+  if (hasModuleChange) return 'module_modification';
+
+  return 'file_modification';
+}
+
+/**
+ * 执行约束检查
+ */
+export async function check(options: CheckOptions): Promise<void> {
+  console.log(chalk.blue('🔍 检查约束...'));
+  console.log(chalk.gray(`预设: ${options.preset}`));
+
+  try {
+    // 加载项目级自定义约束
+    const projectPath = options.projectPath || process.cwd();
+    const configLoader = new ProjectConfigLoader(projectPath);
+    configLoader.load();
+
+    if (configLoader.hasCustomConfig()) {
+      const merged = configLoader.mergeConstraints();
+      constraintChecker.setCustomConfig(merged);
+      console.log(chalk.gray(`自定义约束: ${merged.custom.length} 条`));
+      if (merged.disabled.length > 0) {
+        console.log(chalk.gray(`已禁用约束: ${merged.disabled.join(', ')}`));
+      }
+    }
+
+    // 获取变更文件
+    const changedFiles = await getChangedFiles(options.staged);
+    if (changedFiles.length > 0) {
+      console.log(chalk.gray(`变更文件: ${changedFiles.length} 个`));
+    }
+
+    // 检测触发条件
+    const trigger = detectTrigger(changedFiles, options);
+    console.log(chalk.gray(`触发条件: ${trigger}`));
+
+    // 构建上下文
+    const context: ConstraintContext = {
+      operation: trigger,
+      projectPath: options.projectPath || process.cwd(),
+      changedFiles,
+      hasTest: changedFiles.some(f => f.includes('.test.') || f.includes('.spec.')),
+      hasFailingTest: await detectFailingTest(projectPath),
+      hasRootCauseInvestigation: detectRootCauseInvestigation(projectPath),
+      hasVerificationEvidence: await detectVerificationEvidence(projectPath),
+      hasReuseCheck: detectReuseCheck(projectPath),
+      hasRequirement: detectRequirement(projectPath),
+      hasWorktree: detectWorktree(projectPath),
+    };
+
+    // 执行三层检查
+    const result = await constraintChecker.checkConstraints(context);
+
+    // 输出结果
+    console.log();
+
+    // Iron Laws
+    const ironLawViolations = result.ironLaws.filter(r => !r.satisfied);
+    if (ironLawViolations.length === 0 && result.ironLaws.length > 0) {
+      console.log(chalk.green(`✅ 铁律: 全部通过 (${result.ironLaws.length} 条)`));
+    } else if (ironLawViolations.length > 0) {
+      console.log(chalk.red(`❌ 铁律违规: ${ironLawViolations.length} 条`));
+      ironLawViolations.forEach(r => {
+        if (r.constraint) {
+          console.log(chalk.red(`   - ${r.constraint.id}: ${r.constraint.message}`));
+          console.log(chalk.red(`     ${r.constraint.rule}`));
+        }
+      });
+      console.log();
+      console.log(chalk.red('🛑 铁律检查失败，请修复后再提交'));
+      process.exit(1);
+    }
+
+    // Guidelines
+    if (result.warningCount > 0) {
+      console.log(chalk.yellow(`⚠️  指导原则警告: ${result.warningCount} 条`));
+      result.guidelines.filter(r => !r.satisfied).forEach(r => {
+        if (r.constraint) {
+          console.log(chalk.yellow(`   - ${r.constraint.id}: ${r.constraint.message}`));
+        }
+      });
+    } else if (result.guidelines.length > 0) {
+      const passedGuidelines = result.guidelines.filter(r => r.satisfied).length;
+      console.log(chalk.green(`✅ 指导原则: ${passedGuidelines}/${result.guidelines.length} 通过`));
+    }
+
+    // Tips
+    if (result.tipCount > 0) {
+      console.log(chalk.blue(`💡 提示: ${result.tipCount} 条`));
+      result.tips.filter(r => !r.satisfied).forEach(r => {
+        if (r.constraint) {
+          console.log(chalk.blue(`   - ${r.constraint.id}: ${r.constraint.message}`));
+        }
+      });
+    }
+
+    console.log();
+    console.log(chalk.green('✅ 约束检查通过'));
+
+    // 智能提示
+    const hint = await getSmartHint(projectPath);
+    if (hint) {
+      console.log();
+      console.log(chalk.gray('────────────────────────────────────'));
+      console.log(hint);
+      console.log(chalk.gray('────────────────────────────────────'));
+    }
+  } catch (error) {
+    console.log();
+    console.log(chalk.red(`❌ 约束检查异常: ${error instanceof Error ? error.message : String(error)}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * 检测是否有失败的测试记录
+ * 扫描 .harness/traces/ 中最近的 trace 记录
+ */
+async function detectFailingTest(projectPath: string): Promise<boolean> {
+  try {
+    const tracesDir = path.join(projectPath, '.harness', 'traces');
+    if (!fs.existsSync(tracesDir)) return false;
+
+    const traceFile = path.join(tracesDir, 'execution.log');
+    if (!fs.existsSync(traceFile)) return false;
+
+    const content = fs.readFileSync(traceFile, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return false;
+
+    // 检查最近 20 条记录是否有 fail
+    const recent = lines.slice(-20);
+    return recent.some(line => {
+      try {
+        const trace = JSON.parse(line);
+        return trace.result === 'fail';
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 检测是否有根因分析文档
+ * 检查 ROOT_CAUSE.md、.harness/diagnoses/、或 git commit 消息
+ */
+function detectRootCauseInvestigation(projectPath: string): boolean {
+  // 检查 ROOT_CAUSE.md
+  if (fs.existsSync(path.join(projectPath, 'ROOT_CAUSE.md'))) return true;
+
+  // 检查 .harness/diagnoses/ 目录
+  const diagnosesDir = path.join(projectPath, '.harness', 'diagnoses');
+  if (fs.existsSync(diagnosesDir)) {
+    try {
+      const files = fs.readdirSync(diagnosesDir);
+      if (files.length > 0) return true;
+    } catch {
+      // ignore
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 检测是否有验证证据
+ * 检查 .harness/traces/ 中最近的成功验证记录
+ */
+async function detectVerificationEvidence(projectPath: string): Promise<boolean> {
+  try {
+    const tracesDir = path.join(projectPath, '.harness', 'traces');
+    if (!fs.existsSync(tracesDir)) return false;
+
+    const traceFile = path.join(tracesDir, 'execution.log');
+    if (!fs.existsSync(traceFile)) return false;
+
+    const content = fs.readFileSync(traceFile, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return false;
+
+    // 检查最近 10 条记录是否有 pass
+    const recent = lines.slice(-10);
+    return recent.some(line => {
+      try {
+        const trace = JSON.parse(line);
+        return trace.result === 'pass';
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 检测是否有复用检查
+ * 检查 .harness/reuse/ 目录或相关文档
+ */
+/**
+ * 检测是否有需求来源
+ * 检查 CLAUDE.md、README.md、specs/、docs/specs/ 等
+ */
+function detectRequirement(projectPath: string): boolean {
+  // Check for CLAUDE.md with HARNESS_CONSTRAINTS section
+  const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    try {
+      const content = fs.readFileSync(claudeMdPath, 'utf-8');
+      if (content.includes('HARNESS_CONSTRAINTS')) {
+        return true;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  const indicators = [
+    'README.md',
+    'specs',
+    'docs/specs',
+    '.specs',
+  ];
+  return indicators.some(f => fs.existsSync(path.join(projectPath, f)));
+}
+
+/**
+ * 检测是否在 git worktree 中
+ */
+function detectWorktree(projectPath: string): boolean {
+  try {
+    const gitDir = path.join(projectPath, '.git');
+    if (fs.existsSync(gitDir)) {
+      const content = fs.readFileSync(gitDir, 'utf-8');
+      // 实际 worktree 的 .git 是文件（指向主 repo），不是目录
+      return content.startsWith('gitdir:');
+    }
+  } catch { /* ignore */ }
+  return false;
+}
+
+function detectReuseCheck(projectPath: string): boolean {
+  const reuseDir = path.join(projectPath, '.harness', 'reuse');
+  if (fs.existsSync(reuseDir)) {
+    try {
+      const files = fs.readdirSync(reuseDir);
+      if (files.length > 0) return true;
+    } catch {
+      // ignore
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 智能提示：检查是否需要提示用户下一步操作
+ */
+async function getSmartHint(projectPath: string): Promise<string | null> {
+  const tracesPath = path.join(projectPath, '.harness', 'traces', 'execution.log');
+  const statePath = path.join(projectPath, '.harness', '.state.json');
+  
+  // 检查 trace 文件是否存在
+  if (!fs.existsSync(tracesPath)) {
+    return null;
+  }
+  
+  // 读取 trace 记录数
+  const tracesContent = fs.readFileSync(tracesPath, 'utf-8');
+  const lines = tracesContent.trim().split('\n').filter(Boolean);
+  const traceCount = lines.length;
+  
+  // 读取状态
+  let state: { 
+    shownHints?: string[];
+    lastStatusRun?: string;
+    lastDiagnoseRun?: string;
+  } = {};
+  if (fs.existsSync(statePath)) {
+    state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+  }
+  state.shownHints = state.shownHints || [];
+  
+  const hints: string[] = [];
+  
+  // 条件 1: 记录数首次达到 50
+  if (traceCount >= 50 && !state.shownHints.includes('trace_50')) {
+    hints.push('📊 记录已足够，运行 harness status 查看统计');
+    state.shownHints.push('trace_50');
+  }
+  
+  // 条件 2: 记录数达到 100 且从未运行过诊断
+  if (traceCount >= 100 && !state.lastDiagnoseRun && !state.shownHints.includes('flow_suggest')) {
+    hints.push('💡 数据充足，建议运行 harness flow 查看诊断');
+    state.shownHints.push('flow_suggest');
+  }
+  
+  // 条件 3: 检查异常趋势（简单检查绕过率）
+  const bypassCount = lines.filter(line => {
+    try {
+      const trace = JSON.parse(line);
+      return trace.result === 'bypassed';
+    } catch {
+      return false;
+    }
+  }).length;
+  
+  const bypassRate = traceCount > 10 ? bypassCount / traceCount : 0;
+  if (bypassRate > 0.3 && !state.shownHints.includes('high_bypass')) {
+    hints.push('⚠️ 发现异常趋势，建议运行 harness status 查看详情');
+    state.shownHints.push('high_bypass');
+  }
+  
+  // 保存状态
+  if (hints.length > 0) {
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    return hints.join('\n');
+  }
+  
+  return null;
+}
+
+/**
+ * 列出所有约束
+ */
+export function listLaws(): void {
+  console.log(chalk.blue('\n📜 所有约束:\n'));
+
+  // Iron Laws
+  console.log(chalk.red('🔴 铁律 (Iron Laws) - 绝对禁止，无例外:\n'));
+  Object.values(IRON_LAWS).forEach(constraint => {
+    console.log(chalk.red(`  ${constraint.id}`));
+    console.log(chalk.gray(`    ${constraint.rule}`));
+    console.log(chalk.gray(`    ${constraint.message}`));
+    console.log();
+  });
+
+  // Guidelines
+  console.log(chalk.yellow('🟡 指导原则 (Guidelines) - 优先建议，有例外:\n'));
+  Object.values(GUIDELINES).forEach(constraint => {
+    console.log(chalk.yellow(`  ${constraint.id}`));
+    console.log(chalk.gray(`    ${constraint.rule}`));
+    console.log(chalk.gray(`    ${constraint.message}`));
+    if (constraint.exceptions && constraint.exceptions.length > 0) {
+      console.log(chalk.gray(`    例外: ${constraint.exceptions.join(', ')}`));
+    }
+    console.log();
+  });
+
+  // Tips
+  console.log(chalk.blue('🔵 提示 (Tips) - 信息性，可忽略:\n'));
+  Object.values(TIPS).forEach(constraint => {
+    console.log(chalk.blue(`  ${constraint.id}`));
+    console.log(chalk.gray(`    ${constraint.rule}`));
+    console.log(chalk.gray(`    ${constraint.message}`));
+    console.log();
+  });
+}

package/src/cli/commands/command.ts

@@ -0,0 +1,90 @@
+/**
+ * 命令黑名单检查
+ *
+ * 用法：
+ *   harness command "rm -rf /"
+ *   harness command --level "DROP TABLE users"
+ *   harness command --list
+ */
+
+import { createCommandGate, getCommandRiskLevel, DEFAULT_COMMAND_BLACKLIST, type CommandBlacklistRule } from '../../gates';
+
+export interface CommandCheckOptions {
+  level?: boolean;
+  list?: boolean;
+  json?: boolean;
+  strict?: boolean;
+}
+
+/**
+ * 执行命令黑名单检查（供 bin/harness.js 调用）
+ */
+export async function executeCommand(cmd: string | undefined, options: CommandCheckOptions): Promise<void> {
+  if (options.list) {
+    if (options.json) {
+      console.log(JSON.stringify(DEFAULT_COMMAND_BLACKLIST.map((r: CommandBlacklistRule) => ({
+        id: r.id,
+        level: r.level,
+        message: r.message,
+        category: r.category,
+      })), null, 2));
+    } else {
+      console.log('\n命令黑名单规则：\n');
+
+      const byCategory = DEFAULT_COMMAND_BLACKLIST.reduce((acc: Record<string, CommandBlacklistRule[]>, rule: CommandBlacklistRule) => {
+        if (!acc[rule.category]) acc[rule.category] = [];
+        acc[rule.category].push(rule);
+        return acc;
+      }, {});
+
+      for (const [category, rules] of Object.entries(byCategory)) {
+        console.log(`[${category}]`);
+        for (const rule of rules as CommandBlacklistRule[]) {
+          const levelIcon = rule.level === 'block' ? '🚫' : rule.level === 'warn' ? '⚠️' : '📋';
+          console.log(`  ${levelIcon} ${rule.id}: ${rule.message} (${rule.level})`);
+        }
+        console.log();
+      }
+
+      console.log(`共 ${DEFAULT_COMMAND_BLACKLIST.length} 条规则`);
+    }
+    return;
+  }
+
+  if (!cmd) {
+    console.error('错误：请提供要检查的命令');
+    console.error('用法：harness command "your command"');
+    process.exit(1);
+  }
+
+  const gate = createCommandGate({ strict: options.strict });
+  const result = await gate.check(cmd);
+
+  if (options.level) {
+    const level = getCommandRiskLevel(cmd);
+    if (options.json) {
+      console.log(JSON.stringify({ level, command: cmd }));
+    } else {
+      const levelColors: Record<string, string> = {
+        high: '\x1b[31m',
+        medium: '\x1b[33m',
+        low: '\x1b[32m',
+      };
+      console.log(`${levelColors[level]}${level}\x1b[0m ${cmd}`);
+    }
+    process.exit(level === 'high' ? 1 : 0);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      command: cmd,
+      passed: result.passed,
+      message: result.message,
+      details: result.details,
+    }, null, 2));
+  } else {
+    console.log(result.passed ? `\x1b[32m✓\x1b[0m ${result.message}` : `\x1b[31m✗\x1b[0m ${result.message}`);
+  }
+
+  process.exit(result.passed ? 0 : 1);
+}

package/src/cli/commands/constraints.ts

@@ -0,0 +1,86 @@
+/**
+ * harness constraints -- 约束集合元数据导出
+ *
+ * 纯数据导出，不调用 LLM，不访问文件系统（除 definitions.ts）。
+ * 供 Studio 等消费者获取约束的 hash、计数、文本大小等元数据。
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { getAllConstraints } from '../../core/constraints/definitions';
+
+export interface ConstraintsMeta {
+  version: string;
+  hash: string;
+  counts: { ironLaws: number; guidelines: number; tips: number };
+  textSize: { total: number; perConstraint: number };
+}
+
+function getPackageVersion(): string {
+  // Try several common locations
+  const candidates = [
+    join(__dirname, '..', '..', '..', 'package.json'),
+    join(process.cwd(), 'package.json'),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, 'utf-8')).version;
+      } catch {
+        // continue to next candidate
+      }
+    }
+  }
+  return 'unknown';
+}
+
+export function getConstraintsMeta(): ConstraintsMeta {
+  const constraints = getAllConstraints();
+
+  const ironLaws = constraints.filter(c => c.level === 'iron_law');
+  const guidelines = constraints.filter(c => c.level === 'guideline');
+  const tips = constraints.filter(c => c.level === 'tip');
+
+  // 计算总 promptInjection 文本长度（字符数，可估算 token）
+  const totalTextSize = constraints
+    .map(c => (c.promptInjection || '').length)
+    .reduce((sum, len) => sum + len, 0);
+
+  // 稳定 JSON 序列化后取 hash
+  const hashInput = JSON.stringify({
+    ironLaws: ironLaws.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
+    guidelines: guidelines.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
+    tips: tips.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
+  });
+  const hash = createHash('sha256').update(hashInput).digest('hex');
+
+  return {
+    version: getPackageVersion(),
+    hash,
+    counts: {
+      ironLaws: ironLaws.length,
+      guidelines: guidelines.length,
+      tips: tips.length,
+    },
+    textSize: {
+      total: totalTextSize,
+      perConstraint: constraints.length > 0 ? Math.round(totalTextSize / constraints.length) : 0,
+    },
+  };
+}
+
+/**
+ * CLI handler: output --json
+ */
+export async function constraints(options: { json?: boolean }): Promise<void> {
+  const meta = getConstraintsMeta();
+  if (options.json) {
+    console.log(JSON.stringify(meta, null, 2));
+  } else {
+    console.log(`version: ${meta.version}`);
+    console.log(`hash: ${meta.hash}`);
+    console.log(`ironLaws: ${meta.counts.ironLaws}, guidelines: ${meta.counts.guidelines}, tips: ${meta.counts.tips}`);
+    console.log(`textSize: ${meta.textSize.total} chars total, ~${meta.textSize.perConstraint} chars/constraint`);
+  }
+}