@dianzhong/create-harness-app 0.1.0

package/templates/harness/full/scripts/harness-hooks.test.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * harness hooks 的最小行为测试
+ *
+ * 覆盖：
+ * 1. guard-tool 阻断敏感路径
+ * 2. guard-tool 阻断危险命令
+ * 3. guard-tool 放行普通命令
+ * 4. quality-gate 在 dry-run Stop 模式可完成质量门禁流程
+ */
+
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const guardTool = path.join(repoRoot, '.claude', 'hooks', 'guard-tool.cjs')
+const qualityGate = path.join(repoRoot, '.claude', 'hooks', 'quality-gate.cjs')
+const notifyHook = path.join(repoRoot, '.claude', 'hooks', 'notify.cjs')
+
+function runHook(script, args, payload) {
+  return spawnSync(process.execPath, [script, ...args], {
+    cwd: repoRoot,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+  })
+}
+
+function parseStdout(result) {
+  assert.equal(result.status, 0, result.stderr)
+  return JSON.parse(result.stdout)
+}
+
+const sensitiveRead = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Read',
+    tool_input: { file_path: '.env.production' },
+  }),
+)
+assert.equal(sensitiveRead.continue, false)
+assert.equal(sensitiveRead.permissionDecision, 'deny')
+
+const sensitiveShellRedirect = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'cat<.env.production' },
+  }),
+)
+assert.equal(sensitiveShellRedirect.continue, false)
+assert.match(sensitiveShellRedirect.stopReason, /sensitive path/)
+
+const sensitiveInlineScript = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: `node -e "require('fs').readFileSync('.env.production','utf8')"` },
+  }),
+)
+assert.equal(sensitiveInlineScript.continue, false)
+assert.match(sensitiveInlineScript.stopReason, /sensitive path/)
+
+const destructiveCommand = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git status && rm -rf dist' },
+  }),
+)
+assert.equal(destructiveCommand.continue, false)
+assert.match(destructiveCommand.stopReason, /recursive force delete/)
+
+const recursiveForceSwapped = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'rm -fr dist' },
+  }),
+)
+assert.equal(recursiveForceSwapped.continue, false)
+assert.match(recursiveForceSwapped.stopReason, /recursive force delete/)
+
+const recursiveForceSplit = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'rm -r -f dist' },
+  }),
+)
+assert.equal(recursiveForceSplit.continue, false)
+assert.match(recursiveForceSplit.stopReason, /recursive force delete/)
+
+const safeCommand = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git status --short' },
+  }),
+)
+assert.equal(safeCommand.continue, true)
+
+const envVarBypass = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'GIT_DIR=.git git reset --hard' },
+  }),
+)
+assert.equal(envVarBypass.continue, false)
+assert.match(envVarBypass.stopReason, /destructive git reset/)
+
+const gitClean = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git clean -fd' },
+  }),
+)
+assert.equal(gitClean.continue, false)
+assert.match(gitClean.stopReason, /destructive git clean/)
+
+const gitCleanSwapped = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git clean -df' },
+  }),
+)
+assert.equal(gitCleanSwapped.continue, false)
+assert.match(gitCleanSwapped.stopReason, /destructive git clean/)
+
+const gitCheckoutPath = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git checkout -- src/App.vue' },
+  }),
+)
+assert.equal(gitCheckoutPath.continue, false)
+assert.match(gitCheckoutPath.stopReason, /destructive git checkout/)
+
+const gitRestorePath = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git restore src/App.vue' },
+  }),
+)
+assert.equal(gitRestorePath.continue, false)
+assert.match(gitRestorePath.stopReason, /destructive git restore/)
+
+const forceRefSpec = parseStdout(
+  runHook(guardTool, [], {
+    tool_name: 'Bash',
+    tool_input: { command: 'git push origin +main' },
+  }),
+)
+assert.equal(forceRefSpec.continue, false)
+assert.match(forceRefSpec.stopReason, /force push via refspec/)
+
+const stopDryRun = parseStdout(runHook(qualityGate, ['stop', '--dry-run'], {}))
+assert.equal(stopDryRun.continue, true)
+assert.match(stopDryRun.systemMessage, /Harness 质量门禁(通过|跳过)/)
+
+// --- notify.cjs SubagentStop 测试 ---
+
+// JSON 契约 ok=false 应阻断
+const subagentJsonFail = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    last_assistant_message: 'Review done. {"ok": false, "reason": "test failure"}',
+  }),
+)
+assert.equal(subagentJsonFail.continue, false)
+assert.match(subagentJsonFail.stopReason, /审查未通过/)
+
+// JSON 契约 ok=true 应放行
+const subagentJsonPass = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    last_assistant_message: 'Review done. {"ok": true}',
+  }),
+)
+assert.equal(subagentJsonPass.continue, true)
+
+// 纯字符串 FAIL 标记（在末尾）应阻断
+const subagentStringFail = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    message: 'Some review output\nHARNESS_REVIEW_RESULT: FAIL',
+  }),
+)
+assert.equal(subagentStringFail.continue, false)
+assert.match(subagentStringFail.stopReason, /审查未通过/)
+
+// 纯字符串 PASS 标记（在末尾）应放行
+const subagentStringPass = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    message: 'Some review output\nHARNESS_REVIEW_RESULT: PASS',
+  }),
+)
+assert.equal(subagentStringPass.continue, true)
+
+// 边界：解释性文本含 FAIL 但 JSON ok=true，应放行（核心 bug 修复验证）
+const subagentExplainFail = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    message:
+      'Code review passed. Note: HARNESS_REVIEW_RESULT: FAIL would mean issues. {"ok": true, "reason": "All checks passed."}',
+  }),
+)
+assert.equal(subagentExplainFail.continue, true)
+
+// 边界：JSON 前有代码块含 {}，应正确解析最后一个 JSON
+const subagentCodeBlock = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    message: 'Config: {"name": "test"}. Result: {"ok": false, "reason": "missing type"}',
+  }),
+)
+assert.equal(subagentCodeBlock.continue, false)
+assert.match(subagentCodeBlock.stopReason, /审查未通过/)
+
+// 边界：中间含 FAIL 但末尾是 PASS（字符串 fallback），应放行
+const subagentMiddleFail = parseStdout(
+  runHook(notifyHook, ['subagent-stop', '--dry-run'], {
+    message:
+      'I checked the code. HARNESS_REVIEW_RESULT: FAIL would be bad.\nHARNESS_REVIEW_RESULT: PASS',
+  }),
+)
+assert.equal(subagentMiddleFail.continue, true)
+
+console.log('harness hook tests passed')

package/templates/harness/full/scripts/verify-skills.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * 校验 skills 体系的一致性
+ *
+ * 检查项：
+ * 1. .claude/skills 与 .agents/skills 目录结构完全镜像
+ * 2. SKILL.md 内容 hash 一致
+ * 3. api/assets/references/scripts/templates 等资源目录内容一致
+ * 4. skills-lock.json 的 computedHash 与实际目录内容一致
+ *
+ * --write 模式：更新 skills-lock.json（用于发布 skill 变更时）
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { lstat, readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const root = process.cwd()
+const skillsDir = path.join(root, '.claude', 'skills')
+const agentsSkillsDir = path.join(root, '.agents', 'skills')
+const lockPath = path.join(root, 'skills-lock.json')
+const writeMode = process.argv.includes('--write')
+const mirroredResourceDirs = new Set([
+  'api',
+  'assets',
+  'examples',
+  'references',
+  'scripts',
+  'templates',
+])
+
+const defaultSources = {
+  'element-plus-vue3': {
+    source: 'partme-ai/full-stack-skills',
+    sourceType: 'github',
+  },
+  'find-skills': {
+    source: 'anthropics/skills',
+    sourceType: 'github',
+  },
+  'frontend-design': {
+    source: 'anthropics/claude-code',
+    sourceType: 'github',
+  },
+  'vue-best-practices': {
+    source: 'moeru-ai/airi',
+    sourceType: 'github',
+  },
+}
+
+// 路径分隔符转 POSIX 格式（跨平台一致性）
+function toPosix(relativePath) {
+  return relativePath.split(path.sep).join('/')
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, 'utf8'))
+}
+
+// 递归收集目录下所有文件，跳过 .DS_Store，禁止符号链接（skill 路径必须是真实文件）
+async function collectFiles(dir, baseDir = dir) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files = []
+
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') {
+      continue
+    }
+
+    const fullPath = path.join(dir, entry.name)
+    const stat = await lstat(fullPath)
+
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Skill paths must be real project files, not links: ${fullPath}`)
+    }
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectFiles(fullPath, baseDir)))
+    } else if (entry.isFile()) {
+      files.push({
+        fullPath,
+        relativePath: toPosix(path.relative(baseDir, fullPath)),
+      })
+    }
+  }
+
+  return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))
+}
+
+// 计算目录内容确定性 hash：按相对路径排序，拼接路径+内容+分隔符后 SHA-256
+async function hashDirectory(dir) {
+  const hash = createHash('sha256')
+  const files = await collectFiles(dir)
+
+  for (const file of files) {
+    hash.update(file.relativePath)
+    hash.update('\0')
+    hash.update(await readFile(file.fullPath))
+    hash.update('\0')
+  }
+
+  return hash.digest('hex')
+}
+
+// 计算单个文件的 SHA-256 hash
+async function hashFile(filePath) {
+  const hash = createHash('sha256')
+  hash.update(await readFile(filePath))
+  return hash.digest('hex')
+}
+
+async function listSkillNames(dir) {
+  if (!existsSync(dir)) {
+    return []
+  }
+
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+// 断言两个 skill 名称集合完全一致（用于 .claude/skills 与 .agents/skills 镜像校验）
+function assertEqualSets(label, actual, expected) {
+  const actualList = [...actual].sort()
+  const expectedList = [...expected].sort()
+
+  if (actualList.join('\n') !== expectedList.join('\n')) {
+    throw new Error(
+      `${label} mismatch.\nActual: ${actualList.join(', ') || '(none)'}\nExpected: ${
+        expectedList.join(', ') || '(none)'
+      }`,
+    )
+  }
+}
+
+async function main() {
+  if (!existsSync(skillsDir)) {
+    throw new Error(`Missing skills directory: ${skillsDir}`)
+  }
+
+  if (!existsSync(agentsSkillsDir)) {
+    throw new Error(`Missing agents skills mirror directory: ${agentsSkillsDir}`)
+  }
+
+  const skillNames = await listSkillNames(skillsDir)
+  const agentsSkillNames = await listSkillNames(agentsSkillsDir)
+  assertEqualSets('.agents/skills mirror entries', new Set(agentsSkillNames), new Set(skillNames))
+
+  const hashes = {}
+
+  for (const skillName of skillNames) {
+    hashes[skillName] = await hashDirectory(path.join(skillsDir, skillName))
+  }
+
+  const existingLock = existsSync(lockPath) ? await readJson(lockPath) : { version: 1, skills: {} }
+  const nextLock = {
+    version: 1,
+    skills: Object.fromEntries(
+      skillNames.map((skillName) => {
+        const existing = existingLock.skills?.[skillName] || {}
+        const source = existing.source || defaultSources[skillName]?.source || 'project-local'
+        const sourceType = existing.sourceType || defaultSources[skillName]?.sourceType || 'local'
+
+        return [
+          skillName,
+          {
+            source,
+            sourceType,
+            computedHash: hashes[skillName],
+          },
+        ]
+      }),
+    ),
+  }
+
+  if (writeMode) {
+    await writeFile(lockPath, `${JSON.stringify(nextLock, null, 2)}\n`)
+    process.stdout.write(`Updated skills-lock.json for ${skillNames.length} skill(s).\n`)
+    return
+  }
+
+  const lock = existingLock
+  const lockNames = new Set(Object.keys(lock.skills || {}))
+  const skillNameSet = new Set(skillNames)
+  assertEqualSets('skills-lock.json entries', lockNames, skillNameSet)
+
+  // 校验每个 skill 的镜像同步、SKILL.md hash、资源目录和 lock hash
+  for (const skillName of skillNames) {
+    const skillPath = path.join(skillsDir, skillName)
+    const agentsSkillPath = path.join(agentsSkillsDir, skillName)
+    const sourceSkillMd = path.join(skillPath, 'SKILL.md')
+    const mirroredSkillMd = path.join(agentsSkillPath, 'SKILL.md')
+
+    if (!existsSync(sourceSkillMd)) {
+      throw new Error(`Missing skill entrypoint: ${sourceSkillMd}`)
+    }
+
+    if (!existsSync(mirroredSkillMd)) {
+      throw new Error(`Missing mirrored skill entrypoint: ${mirroredSkillMd}`)
+    }
+
+    if ((await hashFile(sourceSkillMd)) !== (await hashFile(mirroredSkillMd))) {
+      throw new Error(`Mirrored SKILL.md is out of sync for ${skillName}.`)
+    }
+
+    for (const resourceDir of mirroredResourceDirs) {
+      const sourceResourcePath = path.join(skillPath, resourceDir)
+      const mirroredResourcePath = path.join(agentsSkillPath, resourceDir)
+
+      if (!existsSync(sourceResourcePath)) {
+        continue
+      }
+
+      if (!existsSync(mirroredResourcePath)) {
+        throw new Error(
+          `Missing mirrored skill resource: ${toPosix(path.relative(root, mirroredResourcePath))}`,
+        )
+      }
+
+      if (
+        (await hashDirectory(sourceResourcePath)) !== (await hashDirectory(mirroredResourcePath))
+      ) {
+        throw new Error(`Mirrored skill resource is out of sync: ${skillName}/${resourceDir}`)
+      }
+    }
+
+    const lockedHash = lock.skills?.[skillName]?.computedHash
+
+    if (lockedHash !== hashes[skillName]) {
+      throw new Error(
+        `Hash mismatch for ${skillName}.\nExpected lock: ${hashes[skillName]}\nActual lock: ${lockedHash}`,
+      )
+    }
+  }
+
+  process.stdout.write(
+    `Harness skill check passed for ${skillNames.length} skill(s), including .agents/skills mirror.\n`,
+  )
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`)
+  process.exit(1)
+})

package/templates/harness/full/scripts/verify-skills.test.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * verify-skills.mjs 的最小集成测试
+ *
+ * 覆盖：
+ * 1. --write 能生成 lock
+ * 2. .agents/skills 镜像内容漂移时会失败
+ */
+
+import assert from 'node:assert/strict'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const verifyScript = path.join(repoRoot, 'scripts', 'verify-skills.mjs')
+
+async function writeFixtureFile(root, relativePath, content) {
+  const fullPath = path.join(root, relativePath)
+  await mkdir(path.dirname(fullPath), { recursive: true })
+  await writeFile(fullPath, content)
+}
+
+function runVerify(root, args = []) {
+  return spawnSync(process.execPath, [verifyScript, ...args], {
+    cwd: root,
+    encoding: 'utf8',
+  })
+}
+
+async function withSkillFixture(testFn) {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'verify-skills-'))
+
+  try {
+    const skill = `---
+name: sample-skill
+description: Sample skill for harness tests.
+---
+
+# Sample Skill
+`
+
+    await writeFixtureFile(root, '.claude/skills/sample-skill/SKILL.md', skill)
+    await writeFixtureFile(root, '.agents/skills/sample-skill/SKILL.md', skill)
+
+    await testFn(root)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+}
+
+await withSkillFixture(async (root) => {
+  const writeResult = runVerify(root, ['--write'])
+  assert.equal(writeResult.status, 0, writeResult.stderr)
+
+  const checkResult = runVerify(root)
+  assert.equal(checkResult.status, 0, checkResult.stderr)
+  assert.match(checkResult.stdout, /Harness skill check passed/)
+})
+
+await withSkillFixture(async (root) => {
+  assert.equal(runVerify(root, ['--write']).status, 0)
+  await writeFixtureFile(root, '.agents/skills/sample-skill/SKILL.md', '# Drifted Skill\n')
+
+  const result = runVerify(root)
+  assert.notEqual(result.status, 0)
+  assert.match(result.stderr, /Mirrored SKILL\.md is out of sync/)
+})
+
+console.log('verify-skills tests passed')

package/templates/harness/full/skills-lock.json

@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "skills": {
+    "element-plus-vue3": {
+      "source": "partme-ai/full-stack-skills",
+      "sourceType": "github",
+      "computedHash": "a2d4fa311bdce8b6e914ad5a84b9e6a1985a8df59a94aae8259b7aff7a3db41e"
+    },
+    "find-skills": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "c6bcd076436f910c67f591a5a83f8e6182a2b71d22a686084854fe9924324567"
+    },
+    "frontend-design": {
+      "source": "anthropics/claude-code",
+      "sourceType": "github",
+      "computedHash": "514ce855a27bfcf4e883a46fc02c68a3bc9cd8571a2d3fe5ac1aa93cde008433"
+    },
+    "openspec-apply-change": {
+      "source": "project-local",
+      "sourceType": "local",
+      "computedHash": "b0d3d68a1782fd8fd9c5b54c057461079bbdf8d8d597be2d2dc0d990f5f5509d"
+    },
+    "openspec-archive-change": {
+      "source": "project-local",
+      "sourceType": "local",
+      "computedHash": "cef47988c2959dbd2967efd2553bc94dc01178cffc76ae39c2d841eb4d5e6326"
+    },
+    "openspec-explore": {
+      "source": "partme-ai/full-stack-skills",
+      "sourceType": "github",
+      "computedHash": "7f84a20d2e1c238585bce57750d498c18d52ad7be6f2842f486bbdd074c29cf7"
+    },
+    "openspec-propose": {
+      "source": "project-local",
+      "sourceType": "local",
+      "computedHash": "5f1b30ef0e2134741b29affd8c5815d4e66d36bcf9404034bdb056bb6c25e405"
+    },
+    "project-structure-guard": {
+      "source": "project-local",
+      "sourceType": "local",
+      "computedHash": "bae2ec47defeae0d996fca6c05bce6d138ec31909bf0625ecc942926491fca72"
+    },
+    "vue-best-practices": {
+      "source": "moeru-ai/airi",
+      "sourceType": "github",
+      "computedHash": "ce4811a2206a750236deed1e7bc346c776a2d663bb386ba84d624e8852efd936"
+    }
+  }
+}