@dommaker/harness 0.14.0 → 0.16.1

package/src/cli/commands/knowledge.ts

@@ -8,12 +8,13 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { KnowledgeStore } from '../../knowledge/store';
+import { FileKnowledgeStore as KnowledgeStore } from '../../knowledge/store';
 import { KnowledgeQuery } from '../../knowledge/query';
 import { KnowledgeLifecycle } from '../../knowledge/lifecycle';
 import { ColdStartImporter } from '../../knowledge/import';
 import { KnowledgeAudit } from '../../knowledge/audit';
 import { migrateKnowledgeEntries } from '../../knowledge/migration';
+import { KnowledgeIndexGenerator } from '../../knowledge/index-generator';
 import type { KnowledgeType, MaturityLevel, QueryFilter } from '../../knowledge/types';
 
 export interface KnowledgeOptions {
@@ -413,6 +414,106 @@ export async function knowledgeSyncStatus(options: KnowledgeOptions): Promise<vo
   }
 }
 
+/**
+ * 飞轮健康检查 — 零 token 检测知识飞轮数据流状态
+ */
+export async function knowledgeHealth(options: KnowledgeOptions & { dir?: string }): Promise<void> {
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+  const store = new KnowledgeStore({ baseDir });
+  const entries = store.list({ excludeArchived: true });
+
+  const issues: Array<{ severity: 'error' | 'warn' | 'info'; entry: string; detail: string }> = [];
+
+  // D1: 引用密度检查（低引用 = 可能孤立）
+  let lowRefEntries = 0;
+  for (const entry of entries) {
+    if (entry.referencedBy.length === 0 && entry.maturity === 'verified') {
+      lowRefEntries++;
+      issues.push({ severity: 'info', entry: entry.id, detail: `verified 条目零引用（可能孤立）` });
+    }
+  }
+
+  // D2: 新鲜度检查
+  const now = Date.now();
+  const staleThreshold = 90 * 24 * 60 * 60 * 1000; // 90 days
+  let staleEntries = 0;
+  for (const entry of entries) {
+    const created = new Date(entry.created).getTime();
+    if (now - created > staleThreshold && entry.maturity === 'draft') {
+      staleEntries++;
+      issues.push({ severity: 'warn', entry: entry.id, detail: `draft 超过 90 天未推进` });
+    }
+  }
+
+  // D3: 消费数据检查
+  let consumptionData = false;
+  const statsPath = path.join(baseDir, '.consumption-stats.json');
+  if (fs.existsSync(statsPath)) {
+    consumptionData = true;
+  } else {
+    issues.push({ severity: 'info', entry: '-', detail: `消费追踪数据不存在（${statsPath}）` });
+  }
+
+  // D4: 飞轮指标
+  const withRefs = entries.filter(e => e.referencedBy.length > 0).length;
+  const refCoverage = entries.length > 0 ? Math.round(withRefs / entries.length * 100) : 0;
+  const avgRefs = entries.length > 0
+    ? Math.round(entries.reduce((sum, e) => sum + e.referencedBy.length, 0) / entries.length * 10) / 10
+    : 0;
+
+  // 健康分计算
+  const totalIssues = issues.filter(i => i.severity === 'error').length * 3
+    + issues.filter(i => i.severity === 'warn').length * 1;
+  const healthScore = Math.max(0, 100 - totalIssues);
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      healthScore,
+      summary: {
+        total: entries.length,
+        lowRefEntries,
+        staleEntries,
+        consumptionData,
+        refCoverage,
+        avgRefs,
+      },
+      issues: issues.slice(0, 50),
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue('🏥 飞轮健康检查\n'));
+  console.log(chalk.bold(`  健康分: ${healthScore >= 80 ? chalk.green(healthScore) : healthScore >= 60 ? chalk.yellow(healthScore) : chalk.red(healthScore)}/100`));
+  console.log(chalk.bold(`  活跃条目: ${entries.length}`));
+  console.log();
+
+  console.log(chalk.bold('  数据流状态:'));
+  console.log(`    引用密度: ${lowRefEntries === 0 ? chalk.green('✓') : chalk.yellow(`⚠ ${lowRefEntries} 个零引用 verified`)}`);
+  console.log(`    新鲜度: ${staleEntries === 0 ? chalk.green('✓') : chalk.yellow(`⚠ ${staleEntries} 个过期 draft`)}`);
+  console.log(`    消费追踪: ${consumptionData ? chalk.green('✓') : chalk.gray('○ 未启用')}`);
+  console.log();
+
+  console.log(chalk.bold('  飞轮指标:'));
+  console.log(`    引用覆盖: ${refCoverage}%`);
+  console.log(`    平均引用: ${avgRefs}`);
+  console.log();
+
+  if (issues.length > 0) {
+    console.log(chalk.bold(`  问题 (前 20):`));
+    for (const issue of issues.slice(0, 20)) {
+      const sevColor = issue.severity === 'error' ? chalk.red
+        : issue.severity === 'warn' ? chalk.yellow
+        : chalk.gray;
+      console.log(`    ${sevColor(`[${issue.severity}]`)} ${issue.entry}: ${issue.detail}`);
+    }
+    if (issues.length > 20) {
+      console.log(chalk.gray(`    ... 还有 ${issues.length - 20} 条`));
+    }
+  } else {
+    console.log(chalk.green('  ✓ 无问题'));
+  }
+}
+
 function getKnowledgeDir(projectPath?: string): string {
   if (projectPath) return `${projectPath}/.harness/knowledge`;
   if (process.env.KNOWLEDGE_BASE_DIR) return process.env.KNOWLEDGE_BASE_DIR;
@@ -482,6 +583,7 @@ export async function knowledgeAudit(options: KnowledgeOptions & {
     'maturity-inflation': '成熟度虚高',
     'title-duplicate': '标题重复',
     'source-refs-bloat': 'sourceReferences 膨胀',
+    'fragment-cluster': '碎片集群',
     'promotion-blocked': 'promotion 受阻',
     'orphan-draft': '孤儿 draft',
     'stale-entry': '过期条目',
@@ -511,6 +613,14 @@ export async function knowledgeAudit(options: KnowledgeOptions & {
   if (!options.fix && report.issues.length > 0) {
     console.log(chalk.yellow(`\n  使用 --fix 自动修复`));
   }
+
+  // Auto-rebuild index after audit (files may have changed)
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+  const idxGen = new KnowledgeIndexGenerator(baseDir);
+  idxGen.regenerate();
+  if (!options.json) {
+    console.log(chalk.gray(`  📇 索引已重建`));
+  }
 }
 
 /**
@@ -560,3 +670,43 @@ export function knowledgeMigrate(options: KnowledgeOptions & { dir?: string }):
     console.log(chalk.green(`\n✅ 迁移完成`));
   }
 }
+
+/**
+ * 知识库索引重建 — 生成 _index.md 供 Agent grep 使用，同时同步 index.json
+ */
+export function knowledgeIndex(options: KnowledgeOptions & { dir?: string }): void {
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+  const gen = new KnowledgeIndexGenerator(baseDir);
+
+  const beforeSize = (() => {
+    const indexPath = path.join(baseDir, '_index.md');
+    return fs.existsSync(indexPath) ? fs.statSync(indexPath).size : 0;
+  })();
+
+  const output = gen.regenerate();
+
+  // Sync index.json from disk files (removes ghost entries from manual mv/rm)
+  const store = new KnowledgeStore({ baseDir });
+  store.rebuildIndex();
+
+  const afterSize = Buffer.byteLength(output, 'utf-8');
+  const lineCount = output.split('\n').filter(l => !l.startsWith('#')).length;
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      path: path.join(baseDir, '_index.md'),
+      entries: lineCount,
+      size: afterSize,
+      previousSize: beforeSize,
+    }));
+    return;
+  }
+
+  console.log(chalk.blue(`📇 索引已重建`));
+  console.log(chalk.gray(`  路径: ${path.join(baseDir, '_index.md')}`));
+  console.log(chalk.green(`  条目: ${lineCount}`));
+  console.log(chalk.green(`  大小: ${(afterSize / 1024).toFixed(1)} KB`));
+  if (beforeSize > 0) {
+    console.log(chalk.gray(`  旧大小: ${(beforeSize / 1024).toFixed(1)} KB`));
+  }
+}

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';
@@ -44,7 +55,26 @@ export async function release(options: ReleaseOptions): Promise<void> {
   console.log(chalk.cyan(`📦 ${pkgName}@${oldVersion}`));
   console.log(chalk.cyan(`   bump: ${bumpType}${dryRun ? ' (dry-run)' : ''}`));
 
-  // ── 2. Check clean working tree ──
+  // ── 2. Check branch (must be on master/main) ──
+  const branchResult = await run('git rev-parse --abbrev-ref HEAD', pkgPath);
+  const currentBranch = branchResult.stdout.trim();
+  if (currentBranch !== 'master' && currentBranch !== 'main') {
+    console.error(chalk.red(`❌ Must be on master or main branch to release. Currently on: ${currentBranch}`));
+    console.error(chalk.gray('   Run: git checkout master && git merge ' + currentBranch));
+    process.exit(1);
+  }
+  console.log(chalk.green(`✅ git: on ${currentBranch}`));
+
+  // ── 2b. Check remote sync ──
+  await run('git fetch origin', pkgPath, 15_000);
+  const behind = await run(`git rev-list --count HEAD..origin/${currentBranch}`, pkgPath);
+  if (behind.stdout.trim() !== '0') {
+    console.error(chalk.red(`❌ Local ${currentBranch} is ${behind.stdout.trim()} commits behind origin/${currentBranch}. Pull first.`));
+    process.exit(1);
+  }
+  console.log(chalk.green('✅ git: synced with remote'));
+
+  // ── 2c. Check clean working tree ──
   const stat = await run('git status --porcelain -uno', pkgPath);
   if (stat.stdout.length > 0) {
     console.error(chalk.red('❌ Uncommitted changes. Commit or stash before releasing.'));
@@ -95,9 +125,20 @@ 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;
+  if (bumpType === 'major') expectedNew = `${major + 1}.0.0`;
+  else if (bumpType === 'minor') expectedNew = `${major}.${minor + 1}.0`;
+  else expectedNew = `${major}.${minor}.${patch + 1}`;
+  const expectedTag = `v${expectedNew}`;
+  const tagExists = await run(`git tag -l "${expectedTag}"`, pkgPath);
+  if (tagExists.stdout.trim() === expectedTag) {
+    console.error(chalk.red(`❌ Tag ${expectedTag} already exists. Version may have been released already.`));
+    process.exit(1);
+  }
+
   const bump = await run(`npm version ${bumpType} -m "release: %s"`, pkgPath);
   if (bump.stderr && !bump.stdout) {
     console.error(chalk.red('❌ npm version failed:'), bump.stderr);
@@ -107,10 +148,40 @@ export async function release(options: ReleaseOptions): Promise<void> {
   const tag = `v${newVersion}`;
   console.log(chalk.green(`✅ version: ${oldVersion} → ${newVersion} (committed + tagged)`));
 
-  // ── 7. Push ──
+  // ── 6. Push (handle protected branch via PR) ──
   console.log(chalk.cyan('⬆️  Pushing...'));
-  const branch = await run('git rev-parse --abbrev-ref HEAD', pkgPath);
-  const push = await run(`git push origin ${branch.stdout}`, pkgPath, 30_000);
+  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);
@@ -118,21 +189,25 @@ export async function release(options: ReleaseOptions): Promise<void> {
   await run(`git push origin ${tag}`, pkgPath, 30_000);
   console.log(chalk.green('✅ git: pushed'));
 
+  // ── 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.'));
+    process.exit(1);
+  }
+  console.log(chalk.green('✅ package: not private'));
+
   // ── 8. npm publish ──
-  // Switch to npmjs.org for publishing (npmmirror is read-only mirror)
   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);
   }
 
@@ -144,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`);
+  }
+}