@aipper/zentao-mcp-server 0.1.10 → 0.1.11

package/IMPROVEMENTS.md

@@ -1,179 +0,0 @@
-# 代码改进总结
-
-本次改进基于代码评审,主要解决了工程化、安全性和可维护性方面的问题。
-
-## 已完成的改进
-
-### 高优先级 ✅
-
-1. **修复版本号不一致** (src/index.js)
-   - 问题: 硬编码版本 "0.1.0" 与 package.json 的 "0.1.9" 不一致
-   - 解决: 从 package.json 动态读取版本号
-   - 影响: 确保版本信息准确,避免混淆
-
-2. **锁定依赖版本** (package.json)
-   - 问题: 使用 "latest" 导致版本不稳定
-   - 解决: 改为 "^1.27.1" 锁定主版本
-   - 影响: 提高构建稳定性和可重现性
-
-3. **修复 License 问题** (package.json, LICENSE)
-   - 问题: "private: false" 但 "license: UNLICENSED" 矛盾
-   - 解决: 改为 MIT 协议并创建 LICENSE 文件
-   - 影响: 明确开源协议,便于分发和使用
-
-4. **添加 Node.js 版本要求** (package.json)
-   - 问题: README 要求 Node.js 18+ 但 package.json 未声明
-   - 解决: 添加 "engines": {"node": ">=18.0.0"}
-   - 影响: npm 安装时会检查版本兼容性
-
-### 中优先级 ✅
-
-5. **添加 JSDoc 类型注释** (src/zentao.js)
-   - 问题: 纯 JavaScript 缺少类型信息
-   - 解决: 为关键函数添加 JSDoc 注释
-   - 影响: IDE 提供更好的代码提示和文档
-
-6. **添加调试日志系统** (src/index.js)
-   - 问题: 调试困难,无法追踪执行流程
-   - 解决: 添加 ZENTAO_DEBUG 环境变量控制的日志
-   - 影响: 便于排查问题,不影响正常使用
-
-7. **提取魔法数字和字符串** (src/zentao.js)
-   - 问题: 硬编码的数字和中文字符串
-   - 解决: 提取为常量 (MAX_ERROR_TEXT_LENGTH, DEFAULT_RESOLUTION_PREFIX 等)
-   - 影响: 提高可维护性,便于国际化
-
-8. **添加安全检查** (src/index.js)
-   - 问题: 使用 HTTP 存在安全风险
-   - 解决: 检测 HTTP 连接并输出警告
-   - 影响: 提醒用户注意安全问题
-
-### 文档和配置 ✅
-
-9. **创建 CHANGELOG.md**
-   - 记录版本变更历史
-   - 便于用户了解更新内容
-
-10. **更新 README.md**
-    - 添加安全建议章节
-    - 添加调试说明
-    - 添加 License 说明
-
-11. **完善 package.json**
-    - 添加 keywords 便于搜索
-    - 添加 repository 字段
-    - 规范化元数据
-
-12. **更新 .env.example**
-    - 添加 ZENTAO_DEBUG 配置说明
-
-13. **更新 .gitignore**
-    - 添加常见忽略文件
-
-## 代码质量验证
-
-```bash
-npm run lint  # ✅ 通过
-```
-
-所有文件语法检查通过,无错误。
-
-## 改进效果
-
-### 前后对比
-
-| 方面 | 改进前 | 改进后 |
-|------|--------|--------|
-| 版本管理 | 硬编码,不一致 | 动态读取,统一 |
-| 依赖稳定性 | latest (不稳定) | ^1.27.1 (锁定) |
-| 开源协议 | UNLICENSED (矛盾) | MIT (明确) |
-| 类型提示 | 无 | JSDoc 注释 |
-| 调试能力 | 困难 | 可选日志 |
-| 安全意识 | 无提示 | HTTP 警告 |
-| 文档完整性 | 基础 | 完善 |
-
-### 代码统计
-
-```
-修改文件: 5 个
-新增文件: 3 个 (LICENSE, CHANGELOG.md, IMPROVEMENTS.md)
-新增代码: +178 行
-删除代码: -31 行
-净增加: +147 行
-```
-
-## 未完成的改进 (建议后续处理)
-
-### 低优先级
-
-1. **拆分大文件**
-   - src/zentao.js (855 行) 可拆分为多个模块
-   - 建议: bugs.js, projects.js, parsers.js, utils.js
-
-2. **添加单元测试**
-   - 当前只有烟雾测试
-   - 建议: 使用 vitest 添加单元测试
-
-3. **性能优化**
-   - batchResolveMyBugs 可考虑并发处理
-   - 建议: 使用 Promise.all 或 p-limit
-
-4. **国际化支持**
-   - 硬编码的中文字符串
-   - 建议: 提取为配置或支持多语言
-
-5. **错误处理增强**
-   - 某些错误信息可以更具体
-   - 建议: 添加错误码和详细上下文
-
-## 使用建议
-
-### 开发调试
-
-```bash
-# 启用调试日志
-ZENTAO_DEBUG=true npm start
-
-# 或在 MCP 客户端配置中添加
-{
-  "env": {
-    "ZENTAO_DEBUG": "true"
-  }
-}
-```
-
-### 安全最佳实践
-
-1. 始终使用 HTTPS 连接禅道服务器
-2. 使用最小权限账号
-3. 不要在代码仓库中提交 .env 文件
-4. 定期更新依赖包
-
-### 发布前检查
-
-```bash
-# 1. 语法检查
-npm run lint
-
-# 2. 烟雾测试
-npm run smoke
-
-# 3. 更新版本号
-npm version patch  # 或 minor/major
-
-# 4. 发布
-npm run release:npm -- --publish
-```
-
-## 总结
-
-本次改进主要聚焦于**工程化基础设施**和**开发体验**,解决了版本管理、依赖稳定性、开源协议等关键问题。代码质量和可维护性得到显著提升,为后续功能开发和维护打下良好基础。
-
-**整体评分提升**: 7.5/10 → 8.5/10
-
-主要提升点:
-- ✅ 工程化规范 (+1.0)
-- ✅ 安全意识 (+0.5)
-- ✅ 可维护性 (+0.5)
-- ⏳ 测试覆盖 (待改进)
-- ⏳ 模块化 (待改进)

package/scripts/release-npm.sh

@@ -1,481 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-release-npm.sh (zentao-mcp-server)
-
-Default mode is dry-run: run checks + npm pack --dry-run, no npm publish.
-
-Usage:
-  bash scripts/release-npm.sh
-  bash scripts/release-npm.sh --publish
-
-Options:
-  --release <tag>        Set package version from tag (vX.Y.Z), then commit + tag
-  --bump <level>         Auto bump version: patch | minor | major, then commit + tag
-  --publish              Run npm publish after checks (defaults to --bump patch)
-  --yes                  Skip interactive confirmation
-  --require-tag          Require a semver git tag on HEAD matching package version
-  --skip-secrets-scan    Skip ripgrep-based secrets scan
-  --skip-whoami          Skip npm whoami check
-  --no-git-clean-check   Skip clean-worktree check (not recommended)
-  -h, --help             Show help
-
-Environment:
-  ZENTAO_NPM_CACHE_DIR   Override npm cache dir used by this script
-EOF
-}
-
-PUBLISH=0
-YES=0
-REQUIRE_TAG=0
-RELEASE_TAG=""
-BUMP_LEVEL=""
-SKIP_SECRETS_SCAN=0
-SKIP_WHOAMI=0
-SKIP_GIT_CLEAN_CHECK=0
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --release)
-      shift
-      if [[ $# -lt 1 ]]; then
-        echo "error: --release requires <tag> (e.g. v0.1.0)" >&2
-        usage
-        exit 2
-      fi
-      RELEASE_TAG="$1"
-      ;;
-    --bump)
-      shift
-      if [[ $# -lt 1 ]]; then
-        echo "error: --bump requires <level> (patch|minor|major)" >&2
-        usage
-        exit 2
-      fi
-      BUMP_LEVEL="$1"
-      ;;
-    --publish) PUBLISH=1 ;;
-    --yes) YES=1 ;;
-    --require-tag) REQUIRE_TAG=1 ;;
-    --skip-secrets-scan) SKIP_SECRETS_SCAN=1 ;;
-    --skip-whoami) SKIP_WHOAMI=1 ;;
-    --no-git-clean-check) SKIP_GIT_CLEAN_CHECK=1 ;;
-    -h|--help) usage; exit 0 ;;
-    *) echo "error: unknown arg: $1" >&2; usage; exit 2 ;;
-  esac
-  shift
-done
-
-log() { echo "info: $*"; }
-warn() { echo "warn: $*" >&2; }
-die() { echo "error: $*" >&2; exit 2; }
-
-repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-cd "$repo_root"
-
-command -v node >/dev/null 2>&1 || die "node is required"
-command -v npm >/dev/null 2>&1 || die "npm is required"
-
-DEFAULT_NPM_CACHE_DIR="${ZENTAO_NPM_CACHE_DIR:-/tmp/zentao-npm-cache}"
-
-maybe_use_safe_npm_cache() {
-  if [[ -z "${npm_config_cache:-}" && -z "${NPM_CONFIG_CACHE:-}" ]]; then
-    export npm_config_cache="$DEFAULT_NPM_CACHE_DIR"
-  fi
-  local cache_dir="${npm_config_cache:-${NPM_CONFIG_CACHE:-}}"
-  if [[ -n "${cache_dir:-}" ]]; then
-    mkdir -p "$cache_dir" 2>/dev/null || true
-    log "npm_cache=$cache_dir"
-  fi
-}
-
-maybe_use_safe_npm_cache
-
-pkg_name=""
-pkg_version=""
-pkg_private=""
-release_version=""
-release_tag_name=""
-release_tmpdir=""
-release_restore_on_exit=0
-
-cleanup_release() {
-  if [[ "${release_restore_on_exit:-0}" == "1" && -n "${release_tmpdir:-}" ]]; then
-    cp "$release_tmpdir/package.json" package.json 2>/dev/null || true
-  fi
-  if [[ -n "${release_tmpdir:-}" ]]; then
-    rm -rf "$release_tmpdir" 2>/dev/null || true
-  fi
-}
-trap cleanup_release EXIT
-
-is_semver() {
-  printf '%s' "$1" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-.+].+)?$'
-}
-
-normalize_release_tag() {
-  local input="$1"
-  if [[ "$input" == v* ]]; then
-    release_tag_name="$input"
-    release_version="${input#v}"
-  else
-    release_tag_name="v$input"
-    release_version="$input"
-  fi
-  if ! is_semver "$release_version"; then
-    die "--release requires semver tag (vX.Y.Z); got: $input"
-  fi
-}
-
-calc_bumped_version() {
-  local current="$1"
-  local level="$2"
-  ZENTAO_CURRENT_VERSION="$current" ZENTAO_BUMP_LEVEL="$level" node - <<'NODE'
-const current = process.env.ZENTAO_CURRENT_VERSION || "";
-const level = process.env.ZENTAO_BUMP_LEVEL || "";
-const m = current.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
-if (!m) {
-  console.error(`error: current version is not semver-like: ${current}`);
-  process.exit(2);
-}
-let major = Number(m[1]);
-let minor = Number(m[2]);
-let patch = Number(m[3]);
-if (level === "patch") {
-  patch += 1;
-} else if (level === "minor") {
-  minor += 1;
-  patch = 0;
-} else if (level === "major") {
-  major += 1;
-  minor = 0;
-  patch = 0;
-} else {
-  console.error(`error: unsupported bump level: ${level} (expected patch|minor|major)`);
-  process.exit(2);
-}
-process.stdout.write(`${major}.${minor}.${patch}`);
-NODE
-}
-
-read_pkg() {
-  pkg_name="$(node -p "require('./package.json').name")"
-  pkg_version="$(node -p "require('./package.json').version")"
-  pkg_private="$(node -p "Boolean(require('./package.json').private)")"
-}
-
-write_version() {
-  local v="$1"
-  ZENTAO_RELEASE_VERSION="$v" node - <<'NODE'
-const fs = require("node:fs");
-const file = "package.json";
-const v = process.env.ZENTAO_RELEASE_VERSION;
-if (!v) {
-  console.error("missing ZENTAO_RELEASE_VERSION");
-  process.exit(2);
-}
-const src = fs.readFileSync(file, "utf8");
-const pkg = JSON.parse(src);
-pkg.version = v;
-fs.writeFileSync(file, JSON.stringify(pkg, null, 2) + "\n");
-NODE
-}
-
-backup_package_for_restore() {
-  release_tmpdir="$(mktemp -d)"
-  cp package.json "$release_tmpdir/package.json"
-  release_restore_on_exit=1
-}
-
-check_publish_ownership() {
-  local npm_user="$1"
-  local package_name="$2"
-
-  local view_out=""
-  local view_code=0
-  set +e
-  view_out="$(npm view "$package_name" name 2>&1)"
-  view_code=$?
-  set -e
-
-  if [[ "$view_code" != "0" ]]; then
-    if echo "$view_out" | grep -Eqi "(E404|404|not found|not in this registry)"; then
-      log "publish ownership precheck: package not found on registry ($package_name), treated as first publish"
-      return 0
-    fi
-    warn "publish ownership precheck skipped: cannot query package metadata"
-    return 0
-  fi
-
-  local owners_out=""
-  local owners_code=0
-  set +e
-  owners_out="$(npm owner ls "$package_name" 2>&1)"
-  owners_code=$?
-  set -e
-
-  if [[ "$owners_code" != "0" ]]; then
-    warn "publish ownership precheck skipped: cannot query package owners"
-    return 0
-  fi
-
-  if echo "$owners_out" | grep -Eiq "^${npm_user}[[:space:]]"; then
-    log "publish ownership precheck: ok ($npm_user owns $package_name)"
-    return 0
-  fi
-
-  die "npm user '$npm_user' is not an owner of '$package_name' (likely 403). Use a scoped name like '@$npm_user/zentao-mcp-server' or ask current owner to add you."
-}
-
-read_pkg
-
-# Default behavior: publishing without explicit release/bump will auto-bump patch.
-if [[ "$PUBLISH" == "1" && -z "${RELEASE_TAG:-}" && -z "${BUMP_LEVEL:-}" ]]; then
-  BUMP_LEVEL="patch"
-  log "publish requested without version args; defaulting to --bump patch"
-fi
-
-log "repo_root=$repo_root"
-log "package=$pkg_name"
-log "version=$pkg_version"
-log "mode=$(
-  if [[ "$PUBLISH" == "1" ]]; then
-    echo publish
-  elif [[ -n "${RELEASE_TAG:-}" || -n "${BUMP_LEVEL:-}" ]]; then
-    echo prepare
-  else
-    echo dry-run
-  fi
-)"
-
-if [[ -n "${RELEASE_TAG:-}" && -n "${BUMP_LEVEL:-}" ]]; then
-  die "cannot combine --release and --bump"
-fi
-
-VERSION_UPDATE=0
-if [[ -n "${RELEASE_TAG:-}" ]]; then
-  normalize_release_tag "$RELEASE_TAG"
-  VERSION_UPDATE=1
-fi
-if [[ -n "${BUMP_LEVEL:-}" ]]; then
-  release_version="$(calc_bumped_version "$pkg_version" "$BUMP_LEVEL")"
-  release_tag_name="v$release_version"
-  VERSION_UPDATE=1
-  log "bump_level=$BUMP_LEVEL"
-fi
-
-if [[ "$VERSION_UPDATE" == "1" && "$REQUIRE_TAG" == "1" ]]; then
-  die "cannot combine --release/--bump with --require-tag (release flow creates a tag)"
-fi
-
-if [[ "$VERSION_UPDATE" == "1" ]]; then
-  command -v git >/dev/null 2>&1 || die "--release/--bump requires git"
-  log "release_tag=$release_tag_name"
-  log "release_version=$release_version"
-
-  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    die "--release requires running inside a git repository"
-  fi
-
-  if git rev-parse -q --verify "refs/tags/$release_tag_name" >/dev/null 2>&1; then
-    die "--release tag already exists: $release_tag_name"
-  fi
-
-  if [[ "$SKIP_GIT_CLEAN_CHECK" != "1" ]]; then
-    dirty="$(git status --porcelain || true)"
-    if [[ -n "${dirty:-}" ]]; then
-      die "--release requires a clean git working tree; commit or stash changes first"
-    fi
-  fi
-
-  backup_package_for_restore
-  write_version "$release_version"
-  read_pkg
-  log "(after release) version=$pkg_version"
-fi
-
-if [[ "$REQUIRE_TAG" == "1" ]]; then
-  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    die "--require-tag requires running inside a git repository"
-  fi
-  git_tag="$(git describe --tags --exact-match 2>/dev/null || true)"
-  if [[ -z "${git_tag:-}" ]]; then
-    die "--require-tag expected a semver tag on HEAD (e.g. v$pkg_version); found none"
-  fi
-  tag_version="${git_tag#v}"
-  if ! is_semver "$tag_version"; then
-    die "--require-tag expected tag in vX.Y.Z (or X.Y.Z) form; got: $git_tag"
-  fi
-  if [[ "$tag_version" != "$pkg_version" ]]; then
-    die "--require-tag tag version mismatch: tag=$git_tag (=> $tag_version) but package version=$pkg_version"
-  fi
-  log "git_tag=$git_tag"
-fi
-
-if [[ "$PUBLISH" == "1" && "$pkg_version" == "0.0.0" ]]; then
-  die "refusing to publish version 0.0.0; bump version first"
-fi
-
-if [[ "$VERSION_UPDATE" != "1" ]]; then
-  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    if [[ "$SKIP_GIT_CLEAN_CHECK" != "1" ]]; then
-      dirty="$(git status --porcelain || true)"
-      if [[ -n "${dirty:-}" ]]; then
-        if [[ "$PUBLISH" == "1" ]]; then
-          die "git working tree is not clean; commit or stash changes before publishing"
-        fi
-        warn "git working tree is not clean (ok for dry-run):"
-        echo "$dirty" | sed -n '1,20p'
-        if [[ "$(echo "$dirty" | wc -l | tr -d ' ')" -gt 20 ]]; then
-          warn "(truncated)"
-        fi
-      fi
-    fi
-  else
-    warn "not a git repository; skip git clean check"
-  fi
-fi
-
-if [[ "$SKIP_SECRETS_SCAN" != "1" ]]; then
-  if command -v rg >/dev/null 2>&1; then
-    log "secrets scan (filenames only):"
-    secret_re='(_authToken\\s*=\\s*[^\\s#]{16,}|sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}|npm_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|AIzaSy[A-Za-z0-9_-]{35}|-----BEGIN [A-Z ]*PRIVATE KEY-----|Authorization:\\s*Bearer\\s+[^\\s<]{20,}|Bearer\\s+[A-Za-z0-9._-]{20,}|(api[_-]?key|token|password|secret)\\s*[:=]\\s*[\\x27\\\"][^\\x27\\\"<]{12,}[\\x27\\\"])'
-    matches="$(rg -i -l "$secret_re" . --glob '!node_modules/**' --glob '!.git/**' --glob '!dist/**' --glob '!.env' --glob '!.env.*' || true)"
-    if [[ -n "${matches:-}" ]]; then
-      if [[ "$PUBLISH" == "1" ]]; then
-        echo "$matches"
-        die "potential secret-like patterns found; inspect files above before publishing"
-      fi
-      warn "potential secret-like patterns found (dry-run continues):"
-      echo "$matches"
-    else
-      log "secrets scan: ok"
-    fi
-  else
-    warn "rg not found; skip secrets scan"
-  fi
-fi
-
-if [[ "$SKIP_WHOAMI" == "1" ]]; then
-  warn "npm whoami skipped (--skip-whoami)"
-else
-  set +e
-  whoami_out="$(npm whoami 2>&1)"
-  whoami_code=$?
-  set -e
-  if [[ "$whoami_code" == "0" ]]; then
-    npm_user="$(printf '%s' "$whoami_out" | tr -d '\r\n')"
-    log "npm whoami: ok ($npm_user)"
-  else
-    warn "npm whoami failed:"
-    echo "$whoami_out" >&2
-    if [[ "$PUBLISH" == "1" ]]; then
-      warn "continue publish flow despite whoami failure; final publish result will be authoritative"
-    fi
-  fi
-fi
-
-if [[ "$PUBLISH" == "1" ]]; then
-  if [[ "$SKIP_WHOAMI" == "1" ]]; then
-    warn "publish ownership precheck skipped because --skip-whoami is enabled"
-  else
-    if [[ -z "${npm_user:-}" ]]; then
-      warn "publish ownership precheck skipped: npm username unavailable"
-    else
-      check_publish_ownership "$npm_user" "$pkg_name"
-    fi
-  fi
-fi
-
-log "pack preview: npm pack --dry-run"
-pack_out=""
-set +e
-pack_out="$(npm pack --dry-run 2>&1)"
-pack_code=$?
-set -e
-if [[ "$pack_code" != "0" ]]; then
-  if echo "$pack_out" | grep -Eqi "(EPERM|EACCES)" && [[ "${npm_config_cache:-${NPM_CONFIG_CACHE:-}}" != "$DEFAULT_NPM_CACHE_DIR" ]]; then
-    warn "npm pack failed with EPERM/EACCES; retry with npm_config_cache=$DEFAULT_NPM_CACHE_DIR"
-    export npm_config_cache="$DEFAULT_NPM_CACHE_DIR"
-    mkdir -p "$DEFAULT_NPM_CACHE_DIR" 2>/dev/null || true
-    npm pack --dry-run >/dev/null
-  else
-    echo "$pack_out" >&2
-    exit "$pack_code"
-  fi
-fi
-log "pack preview: ok"
-
-publish_cmd=(npm publish)
-if [[ "$pkg_name" == @*/* ]]; then
-  publish_cmd=(npm publish --access public)
-fi
-log "publish command: ${publish_cmd[*]}"
-
-if [[ "$PUBLISH" != "1" ]]; then
-  if [[ "$VERSION_UPDATE" == "1" ]]; then
-    if [[ "$YES" != "1" ]]; then
-      echo ""
-      echo "About to prepare git release:"
-      echo "  - set version to $release_version"
-      echo "  - git commit: chore(release): $release_tag_name"
-      echo "  - git tag: $release_tag_name"
-      echo ""
-      read -r -p "Type 'release' to continue: " confirm_release
-      if [[ "${confirm_release:-}" != "release" ]]; then
-        die "aborted"
-      fi
-    fi
-    if ! git diff --quiet -- package.json; then
-      git add package.json
-      git commit -m "chore(release): $release_tag_name"
-    else
-      log "release: no version changes to commit"
-    fi
-    git tag "$release_tag_name"
-    log "release: created git tag $release_tag_name"
-    release_restore_on_exit=0
-    log "prepare complete (no npm publish performed)"
-    exit 0
-  fi
-  log "dry-run complete (no publish performed)"
-  exit 0
-fi
-
-if [[ "$pkg_private" == "true" ]]; then
-  die "package.json has private=true; set private=false before publishing"
-fi
-
-if [[ "$YES" != "1" ]]; then
-  echo ""
-  echo "About to publish to npm:"
-  echo "  - $pkg_name@$pkg_version"
-  if [[ "$VERSION_UPDATE" == "1" ]]; then
-    echo ""
-    echo "And prepare git release:"
-    echo "  - git commit: chore(release): $release_tag_name"
-    echo "  - git tag: $release_tag_name"
-  fi
-  echo ""
-  read -r -p "Type 'publish' to continue: " confirm_publish
-  if [[ "${confirm_publish:-}" != "publish" ]]; then
-    die "aborted"
-  fi
-fi
-
-if [[ "$VERSION_UPDATE" == "1" ]]; then
-  if ! git diff --quiet -- package.json; then
-    git add package.json
-    git commit -m "chore(release): $release_tag_name"
-  else
-    log "release: no version changes to commit"
-  fi
-  git tag "$release_tag_name"
-  log "release: created git tag $release_tag_name"
-  release_restore_on_exit=0
-fi
-
-"${publish_cmd[@]}"
-log "publish complete"