@pzy560117/opentest 0.1.0

package/assets/skills/opentest/scripts/opentest-state.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+STATE_FILE="${OPENTEST_STATE_FILE:-.opentest.yaml}"
+
+red() { printf '\033[31m%s\033[0m\n' "$1" >&2; }
+green() { printf '\033[32m%s\033[0m\n' "$1" >&2; }
+
+usage() {
+  red "Usage: opentest-state.sh <init|get|set|transition|check>"
+  exit 1
+}
+
+today() {
+  date +%Y-%m-%d
+}
+
+strip_wrapping_quotes() {
+  local value="${1-}"
+  case "$value" in
+    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
+    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
+    *) printf '%s\n' "$value" ;;
+  esac
+}
+
+yaml_field() {
+  local field="$1"
+  [ -f "$STATE_FILE" ] || return 0
+  local raw
+  raw=$(awk -v key="$field" '
+    $1 == key ":" {
+      sub(/^[^:]+:[[:space:]]*/, "", $0)
+      print
+      exit
+    }
+  ' "$STATE_FILE")
+  strip_wrapping_quotes "$raw"
+}
+
+replace_yaml_field() {
+  local field="$1"
+  local value="$2"
+  local tmp_file
+  tmp_file=$(mktemp)
+  awk -v key="$field" -v value="$value" '
+    BEGIN { replaced = 0 }
+    $1 == key ":" {
+      print key ": " value
+      replaced = 1
+      next
+    }
+    { print }
+    END {
+      if (replaced == 0) {
+        print key ": " value
+      }
+    }
+  ' "$STATE_FILE" > "$tmp_file"
+  mv "$tmp_file" "$STATE_FILE"
+}
+
+require_state_file() {
+  if [ ! -f "$STATE_FILE" ]; then
+    red "ERROR: $STATE_FILE not found"
+    exit 1
+  fi
+}
+
+validate_known_field() {
+  case "$1" in
+    workflow|phase|plan|matrix|acceptance|run_mode|run_report|verification_result|verification_report|archived|created_at|updated_at)
+      return 0
+      ;;
+    *)
+      red "ERROR: unknown field '$1'"
+      exit 1
+      ;;
+  esac
+}
+
+validate_enum() {
+  local value="$1"
+  shift
+  local item
+  for item in "$@"; do
+    if [ "$value" = "$item" ]; then
+      return 0
+    fi
+  done
+  red "ERROR: invalid value '$value'. Valid values: $*"
+  exit 1
+}
+
+set_field() {
+  local field="$1"
+  local value="$2"
+  replace_yaml_field "$field" "$value"
+}
+
+cmd_init() {
+  if [ -f "$STATE_FILE" ]; then
+    red "ERROR: $STATE_FILE already exists"
+    exit 1
+  fi
+  local stamp
+  stamp=$(today)
+  cat > "$STATE_FILE" <<EOF
+workflow: standard
+phase: plan
+plan: null
+matrix: null
+acceptance: null
+run_mode: targeted
+run_report: null
+verification_result: pending
+verification_report: null
+archived: false
+created_at: $stamp
+updated_at: $stamp
+EOF
+  green "Initialized $STATE_FILE"
+}
+
+cmd_get() {
+  [ $# -eq 1 ] || usage
+  require_state_file
+  validate_known_field "$1"
+  yaml_field "$1"
+}
+
+cmd_set() {
+  [ $# -eq 2 ] || usage
+  require_state_file
+
+  local field="$1"
+  local value="$2"
+
+  validate_known_field "$field"
+  case "$field" in
+    phase)
+      validate_enum "$value" plan author run accept verify heal archive
+      ;;
+    run_mode)
+      validate_enum "$value" targeted fast full ci-like
+      ;;
+    verification_result)
+      validate_enum "$value" pending pass fail risk-accepted
+      ;;
+    archived)
+      validate_enum "$value" true false
+      ;;
+  esac
+
+  set_field "$field" "$value"
+  if [ "$field" != "updated_at" ]; then
+    set_field updated_at "$(today)"
+  fi
+  green "[SET] $field=$value"
+}
+
+require_phase() {
+  local expected="$1"
+  local actual
+  actual=$(yaml_field phase)
+  if [ "$actual" != "$expected" ]; then
+    red "ERROR: expected phase '$expected', got '${actual:-null}'"
+    exit 1
+  fi
+}
+
+cmd_transition() {
+  [ $# -eq 1 ] || usage
+  require_state_file
+
+  local event="$1"
+  validate_enum "$event" \
+    plan-complete \
+    author-complete \
+    run-complete \
+    accept-complete \
+    verify-pass \
+    verify-risk-accepted \
+    verify-fail \
+    heal-complete \
+    archived
+
+  case "$event" in
+    plan-complete)
+      require_phase plan
+      cmd_set phase author
+      ;;
+    author-complete)
+      require_phase author
+      cmd_set phase run
+      ;;
+    run-complete)
+      require_phase run
+      cmd_set phase accept
+      ;;
+    accept-complete)
+      require_phase accept
+      cmd_set phase verify
+      ;;
+    verify-pass)
+      require_phase verify
+      cmd_set verification_result pass
+      cmd_set phase archive
+      ;;
+    verify-risk-accepted)
+      require_phase verify
+      cmd_set verification_result risk-accepted
+      cmd_set phase archive
+      ;;
+    verify-fail)
+      require_phase verify
+      cmd_set verification_result fail
+      cmd_set phase heal
+      ;;
+    heal-complete)
+      require_phase heal
+      cmd_set phase run
+      ;;
+    archived)
+      require_phase archive
+      cmd_set archived true
+      ;;
+  esac
+  green "[TRANSITION] $event"
+}
+
+cmd_check() {
+  require_state_file
+
+  local workflow phase run_mode verification_result archived
+  workflow=$(yaml_field workflow)
+  phase=$(yaml_field phase)
+  run_mode=$(yaml_field run_mode)
+  verification_result=$(yaml_field verification_result)
+  archived=$(yaml_field archived)
+
+  validate_enum "$workflow" standard
+  validate_enum "$phase" plan author run accept verify heal archive
+  validate_enum "$run_mode" targeted fast full ci-like
+  validate_enum "$verification_result" pending pass fail risk-accepted
+  validate_enum "$archived" true false
+
+  green "[PASS] $STATE_FILE exists and phase=$phase"
+}
+
+case "${1:-}" in
+  init)
+    shift
+    [ $# -eq 0 ] || usage
+    cmd_init
+    ;;
+  get)
+    shift
+    cmd_get "$@"
+    ;;
+  set)
+    shift
+    cmd_set "$@"
+    ;;
+  transition)
+    shift
+    cmd_transition "$@"
+    ;;
+  check)
+    shift
+    [ $# -eq 0 ] || usage
+    cmd_check
+    ;;
+  *)
+    usage
+    ;;
+esac

package/assets/skills/opentest/templates/acceptance-template.md

@@ -0,0 +1,23 @@
+# OpenTest 验收用例
+
+## ACC-001
+
+- intent:
+- context:
+- actor:
+- execution surface:
+- status: pending
+
+### Steps
+
+1.
+
+### Expected Outcome
+
+- 
+
+### Evidence
+
+- status:
+- notes:
+- artifacts:

package/assets/skills/opentest/templates/archive-layout.md

@@ -0,0 +1,14 @@
+# OpenTest Archive Layout
+
+Archive completed evidence under:
+
+`docs/opentest/archive/YYYY-MM-DD-<topic>/`
+
+Include:
+
+- plan
+- matrix
+- acceptance evidence
+- run report
+- verification report
+- screenshots or logs when available

package/assets/skills/opentest/templates/matrix-template.md

@@ -0,0 +1,5 @@
+# Acceptance-to-Test Matrix
+
+| ID | 意图 | 风险 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- |
+| ACC-001 |  | low | targeted review | pending |

package/assets/skills/opentest/templates/plan-template.md

@@ -0,0 +1,18 @@
+# OpenTest 测试策略
+
+## 变更摘要
+
+- 变更类型:
+- 风险等级:
+- 影响面:
+
+## 适用覆盖面
+
+- 必需:
+- 不适用:
+- gap:
+
+## 证据计划
+
+| 证据 | 命令或执行面 | 产物路径 | 状态 |
+| --- | --- | --- | --- |

package/assets/skills/opentest/templates/report-template.md

@@ -0,0 +1,23 @@
+# OpenTest 验证报告
+
+## Summary
+
+- result:
+- run mode:
+- verified at:
+
+## Commands
+
+| command | exit code | result | log |
+| --- | --- | --- | --- |
+
+## Acceptance Evidence
+
+| ID | result | evidence | notes |
+| --- | --- | --- | --- |
+
+## Quality Gate
+
+- blocking:
+- risk accepted:
+- non-blocking gaps:

package/assets/skills/opentest-accept/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: opentest-accept
+description: "OpenTest 阶段 4：执行自然语言验收、MCP 验收或真实链路验收，并回写证据。"
+---
+
+# OpenTest Accept
+
+## 目标
+
+执行必需验收项，并把 PASS、FAIL 或 blocked evidence 回写到验收用例和矩阵。
+
+## 步骤
+
+1. 读取矩阵和 `docs/opentest/acceptance/`。
+2. 对前端交互，优先用 Chrome DevTools MCP 执行真实页面验收。
+3. 对 API 或后台链路，使用项目已有命令或直接 API 检查。
+4. 工具、环境或前置数据不可用时，记录 blocked evidence。
+5. 更新验收记录。
+6. 运行 `bash "$OPENTEST_GUARD" accept --apply`。
+
+## Existing Skill Routing
+
+前端交互验收优先使用自然语言用例加 Chrome DevTools MCP。执行前先确认用例覆盖的是本次适用维度；执行后把 PASS、FAIL 或 blocked 写回对应 ACC ID。

package/assets/skills/opentest-archive/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: opentest-archive
+description: "OpenTest 阶段 6：归档已通过验证的质量证据并关闭状态。"
+---
+
+# OpenTest Archive
+
+验证通过后，将 plan、matrix、acceptance、runs、reports 和可用截图或日志复制到 `docs/opentest/archive/`，运行 `bash "$OPENTEST_GUARD" archive --apply`。验证未通过时拒绝完成归档。

package/assets/skills/opentest-author/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: opentest-author
+description: "OpenTest 阶段 2：根据矩阵补齐测试资产和自然语言验收用例。"
+---
+
+# OpenTest Author
+
+## 目标
+
+根据 acceptance-to-test matrix 创建或更新测试资产。
+
+## 步骤
+
+1. 读取 `.opentest.yaml` 中的 `matrix`。
+2. 对代码级证据，按项目已有测试框架创建或更新测试文件。
+3. 对真实链路证据，写入 `docs/opentest/acceptance/` 自然语言验收用例。
+4. 对不适用或当前无法补齐的证据，记录原因和风险。
+5. 写入 `.opentest.yaml` 的 `acceptance` 字段。
+6. 运行 `bash "$OPENTEST_GUARD" author --apply`。
+
+## Existing Skill Routing
+
+当矩阵要求代码级测试证据时，优先加载现有 TDD guidance。若项目规则要求特定测试框架，遵循项目规则。若当前任务更适合真实验收而不是新增测试框架代码，记录原因并交给 `opentest-accept`。

package/assets/skills/opentest-heal/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: opentest-heal
+description: "OpenTest 恢复阶段：修复测试资产问题，不掩盖产品行为失败。"
+---
+
+# OpenTest Heal
+
+只处理 selector、等待策略、过期 label、过期自然语言步骤等测试资产问题。若失败说明产品行为不满足验收，停止 heal 并记录需要回到 author、run 或 verify。

package/assets/skills/opentest-plan/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: opentest-plan
+description: "OpenTest 阶段 1：分析变更、风险和项目事实，生成测试策略与 acceptance-to-test matrix。"
+---
+
+# OpenTest Plan
+
+## 目标
+
+生成 `docs/opentest/plans/` 下的测试策略和 `docs/opentest/matrices/` 下的矩阵。
+
+## 步骤
+
+1. 读取项目规则、需求、diff、现有测试命令和 `opentest/references/codex-harness-coverage-heuristics.md`。
+2. 判断变更类型、风险等级和适用覆盖面。
+3. 生成窄矩阵，至少包含 `ID`、`意图`、`风险`、`必需证据`、`状态`。
+4. 对适用但未覆盖的证据面标记 `gap`。
+5. 写入 `.opentest.yaml` 的 `plan` 和 `matrix` 字段。
+6. 运行 `bash "$OPENTEST_GUARD" plan --apply`。
+
+## 约束
+
+不要把 Codex Harness 全量 checklist 展开成固定必需项。低风险变更保留轻量覆盖摘要，高风险闭环再展开详细验收维度。

package/assets/skills/opentest-run/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: opentest-run
+description: "OpenTest 阶段 3：按 targeted、fast、full 或 ci-like 模式运行项目测试命令。"
+---
+
+# OpenTest Run
+
+## 目标
+
+执行项目已有验证命令并写入运行报告。
+
+## 模式
+
+- `targeted`：只运行与矩阵相关的测试命令。
+- `fast`：运行快速反馈命令，例如 type、lint、unit。
+- `full`：运行项目完整测试命令。
+- `ci-like`：尽量复现 CI 验证顺序。
+
+## 步骤
+
+1. 读取 `.opentest.yaml` 的 `run_mode` 和矩阵。
+2. 优先使用项目显式命令。
+3. 记录命令、退出码、摘要和日志路径到 `docs/opentest/runs/`。
+4. 写入 `.opentest.yaml` 的 `run_report` 字段。
+5. 运行 `bash "$OPENTEST_GUARD" run --apply`。

package/assets/skills/opentest-verify/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: opentest-verify
+description: "OpenTest 阶段 5：应用质量门并生成验证报告。"
+---
+
+# OpenTest Verify
+
+## 目标
+
+应用质量门，输出结构化验证报告，并把结果写回状态文件。
+
+## Verification Order
+
+验证报告按 build、type、lint、test、security、diff 组织。若项目没有某类命令，记录为 missing command 或 not applicable，不把未知状态写成 pass。
+
+按 build、type、lint、test、security、diff 的顺序组织证据。必需测试、必需验收、构建、类型或 lint 失败时标记 `fail`。非必需缺口可记录为 `risk-accepted`。写入 `docs/opentest/reports/` 和 `.opentest.yaml` 的 `verification_report`、`verification_result`。

package/bin/opentest.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, readdir, rm, stat } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '..');
+const skillsSource = path.join(packageRoot, 'assets', 'skills');
+
+function usage(exitCode = 0) {
+  const text = `OpenTest skill installer
+
+Usage:
+  opentest install [--global] [--force] [--project <path>]
+  opentest list
+
+Options:
+  --global        Install to ~/.codex/skills instead of ./ .codex/skills
+  --project PATH  Install to PATH/.codex/skills
+  --force         Overwrite existing opentest skill directories
+`;
+  (exitCode === 0 ? console.log : console.error)(text.trim());
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = { command, global: false, force: false, project: process.cwd() };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--global') {
+      options.global = true;
+    } else if (arg === '--force') {
+      options.force = true;
+    } else if (arg === '--project') {
+      const value = rest[i + 1];
+      if (!value) usage(1);
+      options.project = path.resolve(value);
+      i += 1;
+    } else {
+      usage(1);
+    }
+  }
+
+  return options;
+}
+
+function homeDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error('Cannot resolve home directory. Set HOME or USERPROFILE.');
+  }
+  return home;
+}
+
+function targetSkillsDir(options) {
+  if (options.global) {
+    return path.join(homeDir(), '.codex', 'skills');
+  }
+  return path.join(options.project, '.codex', 'skills');
+}
+
+async function listSkills() {
+  const entries = await readdir(skillsSource, { withFileTypes: true });
+  for (const entry of entries.filter((item) => item.isDirectory()).map((item) => item.name).sort()) {
+    console.log(entry);
+  }
+}
+
+async function install(options) {
+  const target = targetSkillsDir(options);
+  await mkdir(target, { recursive: true });
+
+  const entries = await readdir(skillsSource, { withFileTypes: true });
+  const skillDirs = entries.filter((entry) => entry.isDirectory() && entry.name.startsWith('opentest'));
+
+  for (const entry of skillDirs) {
+    const src = path.join(skillsSource, entry.name);
+    const dest = path.join(target, entry.name);
+    const exists = await stat(dest).then(() => true, () => false);
+
+    if (exists && !options.force) {
+      throw new Error(`${dest} already exists. Re-run with --force to overwrite.`);
+    }
+
+    if (exists) {
+      await rm(dest, { recursive: true, force: true });
+    }
+    await cp(src, dest, { recursive: true });
+  }
+
+  console.log(`Installed ${skillDirs.length} OpenTest skills to ${target}`);
+  console.log('Restart Codex or open a new session to pick up newly installed skills.');
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (!options.command || options.command === '--help' || options.command === '-h') {
+    usage(0);
+  }
+
+  if (options.command === 'list') {
+    await listSkills();
+    return;
+  }
+
+  if (options.command === 'install') {
+    await install(options);
+    return;
+  }
+
+  usage(1);
+}
+
+main().catch((error) => {
+  console.error(`ERROR: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@pzy560117/opentest",
+  "version": "0.1.0",
+  "description": "OpenTest quality evidence lifecycle skills for Codex",
+  "keywords": [
+    "opentest",
+    "codex",
+    "skills",
+    "testing",
+    "workflow"
+  ],
+  "license": "MIT",
+  "author": "benym",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "opentest": "bin/opentest.js"
+  },
+  "files": [
+    "assets",
+    "bin",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "!scripts/**/*.test.js"
+  ],
+  "scripts": {
+    "test": "node scripts/smoke-test.js",
+    "prepublishOnly": "node scripts/prepublish-check.js && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}