@andyqiu/teamkit 0.1.1

package/install.sh

@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+# install.sh — teamkit 安装脚本
+#
+# 四件事：
+#   1. node scripts/capability-detect.mjs（hard fail 门）
+#   2. 把 @andyqiu/teamkit 注册到 ~/.config/opencode/opencode.json plugins 数组（排首位）
+#   3. 把 context-templates/kh-instructions.md 注入 ~/.config/opencode/AGENTS.md <!-- knowledge-hub:start/end -->
+#      把 context-templates/git-instructions.md 注入 ~/.config/opencode/AGENTS.md <!-- teamkit-git:start/end -->
+#   4. 把 agents/teamkit-git.md 复制到 ~/.config/opencode/agents/teamkit-git.md
+#
+# 支持 --dry-run 参数：打印将执行的操作但不实际写文件
+#
+# ADR: install-sh-wsl-path-guard
+# ADR: opencode-version-compatibility
+
+set -euo pipefail
+
+# ────────────────────────────────────────────────────────────────────────────
+# 颜色 & 输出工具
+# ────────────────────────────────────────────────────────────────────────────
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+err()  { printf "${RED}❌  %s${NC}\n" "$*" >&2; }
+warn() { printf "${YELLOW}⚠️   %s${NC}\n" "$*"; }
+info() { printf "${CYAN}ℹ️   %s${NC}\n" "$*"; }
+ok()   { printf "${GREEN}✅  %s${NC}\n" "$*"; }
+
+# ────────────────────────────────────────────────────────────────────────────
+# 参数解析
+# ────────────────────────────────────────────────────────────────────────────
+DRY_RUN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    *)
+      err "未知参数: $arg"
+      printf "用法: install.sh [--dry-run]\n" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ────────────────────────────────────────────────────────────────────────────
+# 脚本所在目录（teamkit 包根）
+# ────────────────────────────────────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ────────────────────────────────────────────────────────────────────────────
+# WSL 路径检查（ADR: install-sh-wsl-path-guard）
+# 必须在所有路径解析之前执行
+# ────────────────────────────────────────────────────────────────────────────
+if command -v wslpath >/dev/null 2>&1 || [[ "${TEAMKIT_FORCE_WSL_CHECK:-}" == "1" ]]; then
+  case "$HOME" in
+    /mnt/c/*|/mnt/d/*|/mnt/e/*|/mnt/f/*|/mnt/g/*)
+      err "WSL 路径错位：\$HOME 落在 Windows NTFS 挂载路径 ($HOME)"
+      err "问题：teamkit 配置将写到 NTFS 文件系统，导致性能差 / 权限失效 / 路径混乱"
+      err "修复：在 /etc/wsl.conf 中设置 [user] default=<你的Linux用户名>，重启 WSL"
+      err "绕过：若你确实需要在 NTFS 路径运行，设置 TEAMKIT_ALLOW_WSL_WINDOWS_HOME=1"
+      if [[ "${TEAMKIT_ALLOW_WSL_WINDOWS_HOME:-}" != "1" ]]; then
+        exit 1
+      fi
+      warn "已通过 TEAMKIT_ALLOW_WSL_WINDOWS_HOME=1 跳过 WSL 路径检查"
+      ;;
+  esac
+fi
+
+# ────────────────────────────────────────────────────────────────────────────
+# 路径配置
+# ────────────────────────────────────────────────────────────────────────────
+OPENCODE_CONFIG_DIR="${HOME}/.config/opencode"
+OPENCODE_JSON="${OPENCODE_CONFIG_DIR}/opencode.json"
+AGENTS_MD="${OPENCODE_CONFIG_DIR}/AGENTS.md"
+KH_TEMPLATE="${SCRIPT_DIR}/context-templates/kh-instructions.md"
+GIT_TEMPLATE="${SCRIPT_DIR}/context-templates/git-instructions.md"
+MERGE_SCRIPT="${SCRIPT_DIR}/scripts/merge-agents-md.mjs"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 前置检查
+# ────────────────────────────────────────────────────────────────────────────
+if ! command -v node >/dev/null 2>&1; then
+  err "Node.js 未安装，请先安装 Node.js >= 18"
+  exit 1
+fi
+
+if [[ ! -f "${KH_TEMPLATE}" ]]; then
+  err "模板文件不存在: ${KH_TEMPLATE}"
+  exit 1
+fi
+
+if [[ ! -f "${GIT_TEMPLATE}" ]]; then
+  err "模板文件不存在: ${GIT_TEMPLATE}"
+  exit 1
+fi
+
+# ────────────────────────────────────────────────────────────────────────────
+# STEP 0：capability detection（hard fail 门）
+# ADR: opencode-version-compatibility §Decision §4
+# ────────────────────────────────────────────────────────────────────────────
+info "Step 0/3: 运行能力探测..."
+
+if [[ "${DRY_RUN}" == "1" ]]; then
+  info "[dry-run] 将运行: node ${SCRIPT_DIR}/scripts/capability-detect.mjs"
+else
+  if ! node "${SCRIPT_DIR}/scripts/capability-detect.mjs"; then
+    err "capability detection 失败，install 中止"
+    err "运行 \`teamkit doctor\` 获取详细诊断信息"
+    exit 1
+  fi
+  ok "能力探测通过"
+fi
+
+# ────────────────────────────────────────────────────────────────────────────
+# STEP 1：注册 @andyqiu/teamkit 到 opencode.json plugins 数组（排首位）
+# ────────────────────────────────────────────────────────────────────────────
+info "Step 1/3: 注册 plugin entry 到 opencode.json..."
+
+register_plugin_entry() {
+  local config_file="${OPENCODE_JSON}"
+  local plugin_name="@andyqiu/teamkit"
+
+  if [[ "${DRY_RUN}" == "1" ]]; then
+    info "[dry-run] 将把 ${plugin_name} 注册到 ${config_file} plugin 数组首位"
+    return 0
+  fi
+
+  # 确保配置目录存在
+  mkdir -p "${OPENCODE_CONFIG_DIR}"
+
+  # 用 Node.js 做 JSON 操作（避免 shell 解析 JSON 的各种坑）
+  # 通过 argv 传路径，Node.js 内自己读文件；heredoc 用单引号防止变量展开
+  node - "${config_file}" <<'NODEJS_EOF'
+const fs = require('fs');
+const path = process.argv[2];
+let cfg = {};
+try {
+  if (fs.existsSync(path)) cfg = JSON.parse(fs.readFileSync(path, 'utf8'));
+} catch { cfg = {}; }
+
+// opencode 用 "plugin"（单数），兼容读取两种 key
+const existing = Array.isArray(cfg.plugin) ? cfg.plugin
+               : Array.isArray(cfg.plugins) ? cfg.plugins
+               : [];
+
+const pluginName = '@andyqiu/teamkit';
+const filtered = existing.filter(p => {
+  const name = typeof p === 'string' ? p : (p?.name ?? p?.path ?? '');
+  return !name.includes('teamkit');
+});
+filtered.unshift(pluginName);
+
+// 统一写到 "plugin" key
+cfg.plugin = filtered;
+// 如果原来有 "plugins" key，同步删除避免混淆
+if (cfg.plugins !== undefined) delete cfg.plugins;
+
+fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+process.stdout.write('  ✓ 已注册 ' + pluginName + ' 到 plugin[0]\n');
+NODEJS_EOF
+}
+
+register_plugin_entry
+
+# ────────────────────────────────────────────────────────────────────────────
+# STEP 2：注入 AGENTS.md
+# ────────────────────────────────────────────────────────────────────────────
+info "Step 2/3: 注入 AGENTS.md..."
+
+inject_agents_md() {
+  if [[ "${DRY_RUN}" == "1" ]]; then
+    node "${MERGE_SCRIPT}" \
+      --target "${AGENTS_MD}" \
+      --template "${KH_TEMPLATE}" \
+      --dry-run
+    # git-instructions 注入（dry-run）
+    info "[dry-run] 将注入 git-instructions.md 到 <!-- teamkit-git:start/end --> 块"
+    return 0
+  fi
+
+  # 确保配置目录存在
+  mkdir -p "${OPENCODE_CONFIG_DIR}"
+
+  # 注入 KH instructions（<!-- knowledge-hub:start/end -->）
+  node "${MERGE_SCRIPT}" \
+    --target "${AGENTS_MD}" \
+    --template "${KH_TEMPLATE}"
+
+  # 注入 git instructions（<!-- teamkit-git:start/end -->）
+  # merge-agents-md.mjs 只处理 knowledge-hub marker，
+  # git-instructions 需要单独处理 teamkit-git marker
+  # 通过 argv 传路径，heredoc 用单引号防止变量展开
+  node - "${AGENTS_MD}" "${GIT_TEMPLATE}" <<'NODEJS_EOF'
+const fs = require('fs');
+const agentsMdPath = process.argv[2];
+const gitTemplatePath = process.argv[3];
+const template = fs.readFileSync(gitTemplatePath, 'utf8').replace(/\n+$/, '');
+const GIT_START = '<!-- teamkit-git:start -->';
+const GIT_END = '<!-- teamkit-git:end -->';
+
+let content = fs.existsSync(agentsMdPath) ? fs.readFileSync(agentsMdPath, 'utf8') : '';
+
+const startIdx = content.indexOf(GIT_START);
+const endIdx = content.indexOf(GIT_END);
+
+if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+  const before = content.slice(0, startIdx + GIT_START.length);
+  const after = content.slice(endIdx);
+  content = before + '\n\n' + template + '\n\n' + after;
+  process.stdout.write('  ✓ AGENTS.md teamkit-git 块已更新\n');
+} else {
+  content = content + '\n\n' + GIT_START + '\n\n' + template + '\n\n' + GIT_END + '\n';
+  process.stdout.write('  ✓ AGENTS.md teamkit-git 块已追加\n');
+}
+
+fs.writeFileSync(agentsMdPath, content, 'utf8');
+NODEJS_EOF
+}
+
+inject_agents_md
+
+# ────────────────────────────────────────────────────────────────────────────
+# STEP 3：注册 Git Agent（teamkit-git subagent）到全局 agents 目录
+# ────────────────────────────────────────────────────────────────────────────
+info "Step 3/3: 注册 Git Agent 到 opencode agents 目录..."
+
+register_git_agent() {
+  local agents_dir="${HOME}/.config/opencode/agents"
+  local src="${SCRIPT_DIR}/agents/teamkit-git.md"
+
+  if [[ ! -f "${src}" ]]; then
+    warn "agents/teamkit-git.md 不存在，跳过 Git Agent 注册"
+    return 0
+  fi
+
+  if [[ "${DRY_RUN}" == "1" ]]; then
+    info "[dry-run] 将复制 ${src} → ${agents_dir}/teamkit-git.md"
+    return 0
+  fi
+
+  mkdir -p "${agents_dir}"
+  cp "${src}" "${agents_dir}/teamkit-git.md"
+  echo "  → Git Agent 已注册到 ${agents_dir}/teamkit-git.md"
+}
+
+register_git_agent
+
+# ────────────────────────────────────────────────────────────────────────────
+# STEP 4：初始化全局 git-rules.json（不存在时生成默认配置）
+# 全局配置路径：~/.config/teamkit/git-rules.json
+# 默认 narrative + zh，面向非程序员（程序员可在项目级覆盖）
+# ────────────────────────────────────────────────────────────────────────────
+info "Step 4/4: 初始化全局 git-rules.json..."
+
+init_global_git_rules() {
+  local teamkit_config_dir="${HOME}/.config/teamkit"
+  local global_rules_file="${teamkit_config_dir}/git-rules.json"
+
+  if [[ "${DRY_RUN}" == "1" ]]; then
+    if [[ -f "${global_rules_file}" ]]; then
+      info "[dry-run] 全局 git-rules.json 已存在，将跳过（不覆盖）: ${global_rules_file}"
+    else
+      info "[dry-run] 将创建全局 git-rules.json: ${global_rules_file}"
+    fi
+    return 0
+  fi
+
+  if [[ -f "${global_rules_file}" ]]; then
+    ok "全局 git-rules.json 已存在，跳过（保留用户配置）"
+    return 0
+  fi
+
+  mkdir -p "${teamkit_config_dir}"
+  cat > "${global_rules_file}" <<'JSON_EOF'
+{
+  "branchPrefixes": ["feat/", "fix/", "docs/", "art/", "design/", "data/"],
+  "messageStyle": "narrative",
+  "messageLanguage": "zh",
+  "maxFilesPerCommit": 20,
+  "sensitivePatterns": [],
+  "lfsThresholdMB": 10
+}
+JSON_EOF
+  ok "已生成全局 git-rules.json（narrative + zh，适合非程序员）: ${global_rules_file}"
+}
+
+init_global_git_rules
+
+# ────────────────────────────────────────────────────────────────────────────
+# 结尾输出
+# ────────────────────────────────────────────────────────────────────────────
+if [[ "${DRY_RUN}" == "1" ]]; then
+  info "[dry-run] 以上为模拟操作，未实际写文件"
+  printf "\n"
+  ok "dry-run 完成。使用不带 --dry-run 参数运行以实际安装。"
+else
+  printf "\n"
+  ok "teamkit installed successfully. Run: teamkit doctor to verify."
+fi

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@andyqiu/teamkit",
+  "version": "0.1.1",
+  "description": "Team-level shared OpenCode plugin: KH integration + future team-wide workflows",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "bin": {
+    "teamkit": "bin/teamkit.mjs",
+    "teamkit-doctor": "bin/teamkit-doctor.mjs"
+  },
+  "files": [
+    "dist/index.cjs",
+    "bin/",
+    "agents/",
+    "context-templates/",
+    "scripts/",
+    "install.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.cjs --target=node --format=cjs",
+    "test": "node tests/compaction-guard.test.ts",
+    "test:verify": "echo 'TODO: vitest --run tests/'",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'no lint configured (pre-publish TODO)'",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
+    "adr:check": "node scripts/adr-check.mjs",
+    "adr:sync": "node scripts/adr-index-sync.mjs",
+    "adr:check-sync": "node scripts/adr-index-sync.mjs --check",
+    "publish:patch": "bash scripts/publish.sh --patch",
+    "publish:minor": "bash scripts/publish.sh --minor",
+    "publish:major": "bash scripts/publish.sh --major",
+    "publish:release": "bash scripts/publish.sh"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "author": "Andy",
+  "license": "MIT"
+}