@dommaker/harness 0.16.0 → 0.16.1

package/src/cli/commands/release.ts

@@ -4,6 +4,17 @@
  * 完整 npm 发布流水线：tsc → dist 验证 → npm version → git push → npm publish → gh release。
  * 与 studio MCP tool `publishPackage` 共享同一逻辑，但此 CLI 命令不依赖 Studio API 运行。
  * 当 studio API 因 harness 包损坏而无法启动时，此 CLI 命令仍可用。
+ *
+ * 流程：
+ *   1. Verify package
+ *   2. Check branch (must be master/main) + remote sync + clean tree
+ *   3. tsc build
+ *   4. Verify dist files
+ *   5. Bump version (npm version → commit + tag)
+ *   6. Push (protected branch → create release PR instead)
+ *   7. Check private flag
+ *   8. npm publish (or skip if PR flow)
+ *   9. GitHub Release
  */
 
 import { execSync } from 'child_process';
@@ -114,8 +125,7 @@ export async function release(options: ReleaseOptions): Promise<void> {
     process.exit(0);
   }
 
-  // ── 5. Bump version (npm version creates git commit + tag atomically,
-  //     including package-lock.json — no desync possible) ──
+  // ── 5. Bump version (npm version creates git commit + tag atomically) ──
   console.log(chalk.cyan('🔢 Bumping version...'));
   const [major, minor, patch] = oldVersion.split('.').map(Number);
   let expectedNew: string;
@@ -138,9 +148,40 @@ export async function release(options: ReleaseOptions): Promise<void> {
   const tag = `v${newVersion}`;
   console.log(chalk.green(`✅ version: ${oldVersion} → ${newVersion} (committed + tagged)`));
 
-  // ── 6. Push ──
+  // ── 6. Push (handle protected branch via PR) ──
   console.log(chalk.cyan('⬆️  Pushing...'));
   const push = await run(`git push origin ${currentBranch}`, pkgPath, 30_000);
+  const isProtected = push.stderr.includes('GH006') || push.stderr.includes('protected branch');
+
+  if (isProtected) {
+    // Protected branch: create release branch + PR
+    const releaseBranch = `release/v${newVersion}`;
+    console.log(chalk.yellow(`⚠️  ${currentBranch} is protected. Creating PR via ${releaseBranch}...`));
+
+    await run(`git checkout -b ${releaseBranch}`, pkgPath);
+    await run(`git push origin ${releaseBranch}`, pkgPath, 30_000);
+
+    // Create PR
+    const prBody = `## Release ${pkgName}@${newVersion}\n\n- Bump version: ${oldVersion} → ${newVersion}\n- Changelog updated\n\nAfter merge, push tag to trigger npm publish:\n\`\`\`\ngit push origin ${tag}\n\`\`\``;
+    const pr = await run(`gh pr create --title "release: ${pkgName}@${newVersion}" --body "${prBody}" --base ${currentBranch}`, pkgPath, 30_000);
+    if (pr.stdout) {
+      console.log(chalk.green(`✅ PR created: ${pr.stdout.trim()}`));
+    } else {
+      console.error(chalk.red('❌ PR creation failed:'), pr.stderr.slice(0, 500));
+      process.exit(1);
+    }
+
+    // Switch back to original branch
+    await run(`git checkout ${currentBranch}`, pkgPath);
+
+    console.log(chalk.cyan('\n📋 Next steps:'));
+    console.log(chalk.gray(`   1. Merge the PR: ${pr.stdout.trim()}`));
+    console.log(chalk.gray(`   2. After merge, push tag to trigger npm publish:`));
+    console.log(chalk.gray(`      git push origin ${tag}`));
+    console.log(chalk.gray(`   3. Or run: gh release create ${tag} --generate-notes`));
+    return;
+  }
+
   if (push.stderr && push.stderr.includes('error')) {
     console.error(chalk.red('❌ git push failed:'), push.stderr.slice(0, 500));
     process.exit(1);
@@ -148,7 +189,7 @@ export async function release(options: ReleaseOptions): Promise<void> {
   await run(`git push origin ${tag}`, pkgPath, 30_000);
   console.log(chalk.green('✅ git: pushed'));
 
-  // ── 8. Check private flag ──
+  // ── 7. Check private flag ──
   if (pkgJson.private) {
     console.error(chalk.red('❌ package.json has "private": true. Remove it before publishing.'));
     console.error(chalk.gray('   The release tool will NOT auto-remove private flag.'));
@@ -156,25 +197,21 @@ export async function release(options: ReleaseOptions): Promise<void> {
   }
   console.log(chalk.green('✅ package: not private'));
 
-  // ── 7. npm publish ──
-  // Switch to npmjs.org for publishing (npmmirror is read-only mirror)
+  // ── 8. npm publish ──
   const origRegistry = await run('npm config get registry', pkgPath);
   await run('npm config set registry https://registry.npmjs.org/', pkgPath);
   console.log(chalk.cyan('📤 Publishing to npm...'));
-  // npm publish to npmjs.org (the write registry — npmmirror is read-only)
   const pub = await run('npm publish --registry https://registry.npmjs.org/', pkgPath, 180_000);
-  // Restore original registry
   await run(`npm config set registry ${origRegistry.stdout}`, pkgPath);
-  // Don't string-match npm output — verify by querying the registry
   const verify = await run(`npm view ${pkgName} version --registry https://registry.npmjs.org/`, pkgPath);
   if (verify.stdout.trim() === newVersion) {
     console.log(chalk.green(`✅ npm: published ${pkgName}@${newVersion}`));
   } else {
-    console.log(chalk.red(`❌ npm publish verification failed. Expected ${newVersion}, registry has ${verify.stdout.trim() || '???'}`));
+    console.error(chalk.red(`❌ npm publish verification failed. Expected ${newVersion}, registry has ${verify.stdout.trim() || '???'}`));
     process.exit(1);
   }
 
-  // ── 8. GitHub Release ──
+  // ── 9. GitHub Release ──
   console.log(chalk.cyan('🐙 Creating GitHub Release...'));
   const gh = await run(`gh release create ${tag} --generate-notes`, pkgPath, 30_000);
   if (gh.stderr && gh.stderr.includes('already exists')) {
@@ -182,7 +219,6 @@ export async function release(options: ReleaseOptions): Promise<void> {
   } else if (gh.stderr) {
     console.log(chalk.yellow(`⚠️  gh: release may have failed (non-fatal): ${gh.stderr.slice(0, 200)}`));
   } else {
-    // Derive repo URL from git remote
     let repoUrl = '';
     try {
       const remoteUrl = execSync('git remote get-url origin', { cwd: pkgPath, encoding: 'utf-8', stdio: 'pipe', timeout: 5_000 }).trim();

package/src/cli/commands/sdd.ts

@@ -0,0 +1,44 @@
+// SDD CLI commands
+import * as fs from 'fs';
+import * as path from 'path';
+import { SDDIndexGenerator } from '../../sdd/index-generator';
+
+export interface SDDOptions {
+  projectPath?: string;
+  json?: boolean;
+}
+
+function getSDDDir(projectPath?: string): string {
+  // Default: projectPath/docs or cwd/docs
+  const base = projectPath || process.cwd();
+  return base;
+}
+
+export function sddIndex(options: SDDOptions & { dir?: string }): void {
+  const baseDir = options.dir || getSDDDir(options.projectPath);
+  const gen = new SDDIndexGenerator(baseDir);
+
+  const sddDir = path.join(baseDir, 'docs', 'sdd');
+  const indexPath = path.join(sddDir, '_index.md');
+  const beforeSize = fs.existsSync(indexPath) ? fs.statSync(indexPath).size : 0;
+
+  const result = gen.regenerate();
+
+  const afterSize = Buffer.byteLength(
+    result.entries.map(e => `${e.slug}|${e.pmoNumber}|${e.status}|${e.title}|${e.tags}`).join('\n'),
+    'utf-8',
+  );
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      path: indexPath,
+      entries: result.count,
+      size: afterSize,
+      previousSize: beforeSize,
+    }));
+  } else {
+    console.log(`SDD Index regenerated: ${indexPath}`);
+    console.log(`  Entries: ${result.count}`);
+    console.log(`  Size: ${beforeSize} → ${afterSize} bytes`);
+  }
+}

package/src/cli/commands/spec-baseline-check.ts

@@ -0,0 +1,384 @@
+/**
+ * harness spec-baseline-check 命令
+ *
+ * 验证 spec 文件的前置条件（Baseline / 前置条件）是否满足。
+ * 纯代码操作，零 LLM 调用。
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface SpecBaselineCheckOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 输出 JSON 格式 */
+  json?: boolean;
+}
+
+/** 前置条件验证结果 */
+export interface PrerequisiteResult {
+  /** 前置条件描述 */
+  prerequisite: string;
+  /** 是否满足 */
+  satisfied: boolean;
+  /** 证据 */
+  evidence: string;
+}
+
+// ============================================
+// 解析器
+// ============================================
+
+/**
+ * 从 spec 内容中提取 Baseline/前置条件 section
+ */
+export function extractBaselineSection(content: string): string[] {
+  const lines = content.split('\n');
+  const prerequisites: string[] = [];
+
+  // 查找 ## Baseline 或 ## 前置条件 section
+  let inSection = false;
+  let sectionLevel = 0;
+
+  for (const line of lines) {
+    const headerMatch = line.match(/^(#{1,6})\s+(.+)/);
+
+    if (headerMatch) {
+      const level = headerMatch[1].length;
+      const title = headerMatch[2].trim();
+
+      // 检查是否是目标 section
+      if (/^(Baseline|前置条件|Prerequisites|Prereqs)$/i.test(title)) {
+        inSection = true;
+        sectionLevel = level;
+        continue;
+      }
+
+      // 同级或更高级的标题结束 section
+      if (inSection && level <= sectionLevel) {
+        inSection = false;
+        continue;
+      }
+    }
+
+    // 在 section 中提取列表项
+    if (inSection) {
+      const listMatch = line.match(/^\s*[-*+]\s+(.+)/);
+      if (listMatch) {
+        prerequisites.push(listMatch[1].trim());
+      }
+      // 也支持编号列表
+      const numberedMatch = line.match(/^\s*\d+\.\s+(.+)/);
+      if (numberedMatch) {
+        prerequisites.push(numberedMatch[1].trim());
+      }
+    }
+  }
+
+  return prerequisites;
+}
+
+// ============================================
+// 验证器
+// ============================================
+
+/**
+ * 检查文件/目录是否存在
+ */
+function checkFileExists(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+  // 提取路径引用（反引号中的路径、引号中的路径、或直接的路径模式）
+  const pathPatterns = [
+    /`([^`]+\.[a-z]+)`/g,           // `src/foo.ts`
+    /["']([^"']+\.[a-z]+)["']/g,    // "src/foo.ts"
+    /`([^`]+\/)`/g,                  // `src/foo/`
+    /(\S+\/\S+\.[a-z]+)/g,          // src/foo.ts
+  ];
+
+  const paths: string[] = [];
+  for (const p of pathPatterns) {
+    p.lastIndex = 0;
+    let m;
+    while ((m = p.exec(pattern)) !== null) {
+      paths.push(m[1]);
+    }
+  }
+
+  if (paths.length === 0) {
+    return { exists: false, evidence: '无法从描述中提取路径' };
+  }
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  for (const p of paths) {
+    const fullPath = path.resolve(projectPath, p);
+    if (fs.existsSync(fullPath)) {
+      found.push(p);
+    } else {
+      missing.push(p);
+    }
+  }
+
+  if (missing.length === 0 && found.length > 0) {
+    return { exists: true, evidence: `文件存在: ${found.join(', ')}` };
+  }
+  if (found.length > 0) {
+    return { exists: false, evidence: `部分存在: ${found.join(', ')}; 缺失: ${missing.join(', ')}` };
+  }
+  return { exists: false, evidence: `文件不存在: ${missing.join(', ')}` };
+}
+
+/**
+ * 检查代码中是否存在特定模式
+ */
+function checkCodePattern(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+  // 从描述中提取关键词
+  const keywords: string[] = [];
+
+  // 提取反引号中的代码
+  const codePatterns = pattern.match(/`([^`]+)`/g);
+  if (codePatterns) {
+    for (const cp of codePatterns) {
+      const inner = cp.slice(1, -1);
+      if (inner.length >= 2) {
+        keywords.push(inner);
+      }
+    }
+  }
+
+  // 提取 "implemented" / "exists" / "已实现" 等关键词后的内容
+  const implMatch = pattern.match(/(?:implemented|exists|已实现|已完成|已存在)[\s:：]+(.+)/i);
+  if (implMatch) {
+    keywords.push(implMatch[1].trim());
+  }
+
+  if (keywords.length === 0) {
+    return { exists: false, evidence: '无法从描述中提取搜索关键词' };
+  }
+
+  const found: string[] = [];
+  const notFound: string[] = [];
+
+  for (const kw of keywords) {
+    let count = 0;
+    function walkDir(dir: string) {
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(fullPath);
+        } else if (entry.isFile() && (fullPath.endsWith('.ts') || fullPath.endsWith('.js'))) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            if (content.includes(kw)) count++;
+          } catch { /* skip */ }
+        }
+      }
+    }
+    walkDir(projectPath);
+    if (count > 0) {
+      found.push(`${kw} (${count} files)`);
+    } else {
+      notFound.push(kw);
+    }
+  }
+
+  if (notFound.length === 0 && found.length > 0) {
+    return { exists: true, evidence: `代码中找到: ${found.join(', ')}` };
+  }
+  if (found.length > 0) {
+    return { exists: false, evidence: `找到: ${found.join(', ')}; 未找到: ${notFound.join(', ')}` };
+  }
+  return { exists: false, evidence: `代码中未找到: ${notFound.join(', ')}` };
+}
+
+/**
+ * 检查包依赖是否安装
+ */
+function checkDependency(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+  // 提取包名
+  const pkgPatterns = [
+    /`(@?[\w-]+\/[\w-]+)`/g,      // `@scope/pkg` or `pkg-name`
+    /`([\w-]+)`/g,                  // `pkg`
+    /install(?:ed)?\s+(\S+)/gi,    // installed pkg-name
+  ];
+
+  const packages: string[] = [];
+  for (const p of pkgPatterns) {
+    p.lastIndex = 0;
+    let m;
+    while ((m = p.exec(pattern)) !== null) {
+      const pkg = m[1];
+      if (pkg.length >= 2 && !pkg.includes('/') && !pkg.includes('.')) {
+        packages.push(pkg);
+      }
+    }
+  }
+
+  if (packages.length === 0) {
+    return { exists: false, evidence: '无法从描述中提取包名' };
+  }
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  const pkgJsonPath = path.join(projectPath, 'package.json');
+  let deps: Record<string, string> = {};
+
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+  } catch {
+    return { exists: false, evidence: '无法读取 package.json' };
+  }
+
+  for (const pkg of packages) {
+    if (deps[pkg] || deps[`@types/${pkg}`]) {
+      found.push(pkg);
+    } else {
+      // 检查 node_modules
+      const nmPath = path.join(projectPath, 'node_modules', pkg);
+      if (fs.existsSync(nmPath)) {
+        found.push(pkg);
+      } else {
+        missing.push(pkg);
+      }
+    }
+  }
+
+  if (missing.length === 0 && found.length > 0) {
+    return { exists: true, evidence: `依赖已安装: ${found.join(', ')}` };
+  }
+  if (found.length > 0) {
+    return { exists: false, evidence: `已安装: ${found.join(', ')}; 缺失: ${missing.join(', ')}` };
+  }
+  return { exists: false, evidence: `依赖缺失: ${missing.join(', ')}` };
+}
+
+/**
+ * 综合验证一条前置条件
+ */
+function verifyPrerequisite(prereq: string, projectPath: string): PrerequisiteResult {
+  const lower = prereq.toLowerCase();
+
+  // 路径/文件存在性检查
+  if (lower.includes('文件') || lower.includes('file') || lower.includes('目录') || lower.includes('directory')
+    || /`[^`]+\.[a-z]+`/.test(prereq) || /\//.test(prereq)) {
+    const { exists, evidence } = checkFileExists(prereq, projectPath);
+    if (exists || evidence.includes('文件不存在')) {
+      return { prerequisite: prereq, satisfied: exists, evidence };
+    }
+  }
+
+  // 依赖检查
+  if (lower.includes('依赖') || lower.includes('install') || lower.includes('package') || lower.includes('npm')) {
+    const { exists, evidence } = checkDependency(prereq, projectPath);
+    return { prerequisite: prereq, satisfied: exists, evidence };
+  }
+
+  // 代码模式检查
+  if (lower.includes('实现') || lower.includes('implement') || lower.includes('exist')
+    || lower.includes('已') || lower.includes('必须')
+    || /`[^`]+`/.test(prereq)) {
+    const { exists, evidence } = checkCodePattern(prereq, projectPath);
+    return { prerequisite: prereq, satisfied: exists, evidence };
+  }
+
+  // 默认：无法自动验证
+  return {
+    prerequisite: prereq,
+    satisfied: true,
+    evidence: '无法自动验证（需人工确认）',
+  };
+}
+
+// ============================================
+// 输出格式化
+// ============================================
+
+function formatTable(results: PrerequisiteResult[]): string {
+  if (results.length === 0) return chalk.yellow('未找到 Baseline / 前置条件 section');
+
+  const lines: string[] = [];
+  lines.push(chalk.blue(`前置条件检查 (${results.length} 条)\n`));
+
+  const satisfied = results.filter(r => r.satisfied).length;
+  const failed = results.filter(r => !r.satisfied);
+
+  lines.push(chalk.bold(`  满足: ${satisfied}/${results.length}`));
+  if (failed.length > 0) {
+    lines.push(chalk.red(`  未满足: ${failed.length}\n`));
+  } else {
+    lines.push(chalk.green('  全部满足\n'));
+  }
+
+  for (const r of results) {
+    const icon = r.satisfied ? chalk.green('✓') : chalk.red('✗');
+    lines.push(`  ${icon} ${r.prerequisite}`);
+    if (!r.satisfied) {
+      lines.push(`    ${chalk.yellow(r.evidence)}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================
+// 主入口
+// ============================================
+
+/**
+ * spec-baseline-check CLI 命令
+ */
+export async function specBaselineCheck(
+  specPath: string,
+  options: SpecBaselineCheckOptions = {},
+): Promise<void> {
+  // 验证文件存在
+  const resolvedPath = path.resolve(specPath);
+  if (!fs.existsSync(resolvedPath)) {
+    console.error(chalk.red(`文件不存在: ${resolvedPath}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectPath = options.projectPath || path.dirname(resolvedPath);
+
+  // 读取 spec
+  const content = fs.readFileSync(resolvedPath, 'utf-8');
+
+  // 提取前置条件
+  const prerequisites = extractBaselineSection(content);
+
+  if (prerequisites.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ prerequisites: [], message: '未找到 Baseline / 前置条件 section' }, null, 2));
+    } else {
+      console.log(chalk.yellow('未找到 ## Baseline 或 ## 前置条件 section'));
+    }
+    return;
+  }
+
+  // 验证每条前置条件
+  const results = prerequisites.map(p => verifyPrerequisite(p, projectPath));
+
+  // 输出
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(formatTable(results));
+  }
+
+  // 有未满足的前置条件时 exit 1
+  const failed = results.filter(r => !r.satisfied);
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}

package/src/knowledge/__tests__/audit.test.ts

@@ -558,6 +558,62 @@ describe('auto-fix', () => {
   });
 });
 
+// ── D2b: deprecated-domain ──────────────────────────────
+
+describe('D2b: deprecated-domain', () => {
+  it('flags entry with "pipeline" tag', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ tags: ['pipeline', 'deployment'] });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(1);
+    expect(dd[0].action).toBe('archive');
+    expect(dd[0].severity).toBe('high');
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('flags entry with "pipeline" in title', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'Pipeline 工作单元不可见导致协作效率低' });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(1);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('flags entry with "管线" in title', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'B51 管线端到端验证常量与测试' });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(1);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('does not flag entry without deprecated domain references', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'Agent Network 核心概念', tags: ['agent', 'architecture'] });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(0);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('skips already archived entries', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'Pipeline legacy entry', maturity: 'archived', tags: ['pipeline'] });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(0);
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
 // ── run() report structure ─────────────────────────────
 
 describe('run() report', () => {