@fitlab-ai/agent-infra 0.3.0

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+/**
+ * sync-templates.js — Deterministic template sync for managed & ejected files.
+ *
+ * Handles SKILL steps: 2 (git pull), 3.0 (registry sync), 4 (managed),
+ * 6 (ejected), 7 (.airc.json update).
+ *
+ * Merged files (step 5) are NOT handled — they require AI semantic merge.
+ * The report includes `merged.pending` so the AI knows what to process.
+ *
+ * Usage:
+ *   node .agents/skills/update-agent-infra/scripts/sync-templates.js [project-root]
+ *
+ * Output: JSON report to stdout.
+ */
+
+import childProcess from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Keep these helpers aligned with lib/paths.js for clone installs.
+function resolveInstallDir() {
+  return path.join(os.homedir(), '.agent-infra');
+}
+
+function resolveTemplateDir() {
+  const clonePath = path.join(resolveInstallDir(), 'templates');
+  if (fs.existsSync(clonePath)) {
+    return clonePath;
+  }
+
+  return null;
+}
+
+const DEFAULTS = {
+  "files": {
+    "managed": [
+      ".agents/skills/",
+      ".agents/templates/",
+      ".agents/workflows/",
+      ".agent-workspace/README.md",
+      ".claude/commands/",
+      ".editorconfig",
+      ".gemini/commands/",
+      ".github/hooks/",
+      ".github/ISSUE_TEMPLATE/",
+      ".github/PULL_REQUEST_TEMPLATE.md",
+      ".github/release.yml",
+      ".github/workflows/pr-title-check.yml",
+      ".opencode/commands/"
+    ],
+    "merged": [
+      "**/release.*",
+      "**/test-integration.*",
+      "**/test.*",
+      "**/upgrade-dependency.*",
+      ".agents/QUICKSTART.md",
+      ".agents/README.md",
+      ".agents/skills/release/SKILL.*",
+      ".agents/skills/test-integration/SKILL.*",
+      ".agents/skills/test/SKILL.*",
+      ".agents/skills/upgrade-dependency/SKILL.*",
+      ".claude/CLAUDE.md",
+      ".claude/project-rules.md",
+      ".claude/settings.json",
+      ".codex/README.md",
+      ".gemini/settings.json",
+      ".github/dependabot.yml",
+      ".gitignore",
+      ".mailmap",
+      ".opencode/COMMAND_STYLE_GUIDE.md",
+      ".opencode/README.md",
+      "AGENTS.md",
+      "CONTRIBUTING.md",
+      "SECURITY.md"
+    ],
+    "ejected": []
+  }
+};
+
+const INSTALLER_VERSION = "0.3.0";
+
+function norm(p) { return p.replace(/\\/g, '/'); }
+
+function globMatch(pattern, filePath) {
+  const p = norm(pattern), f = norm(filePath);
+  const globstarDir = '__GLOBSTAR_DIR__';
+  const globstar = '__GLOBSTAR__';
+  const star = '__STAR__';
+  const qmark = '__QMARK__';
+  const re = p
+    .replace(/([.+^${}()|[\]\\])/g, '\\$1')
+    .replace(/\*\*\//g, globstarDir)
+    .replace(/\*\*/g, globstar)
+    .replace(/\*/g, star)
+    .replace(/\?/g, qmark)
+    .replace(new RegExp(globstarDir, 'g'), '(?:.+/)?')
+    .replace(new RegExp(globstar, 'g'), '[^/]*')
+    .replace(new RegExp(star, 'g'), '[^/]*')
+    .replace(new RegExp(qmark, 'g'), '[^/]');
+  return new RegExp('^' + re + '$').test(f);
+}
+
+function walkDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    e.isDirectory() ? out.push(...walkDir(p)) : out.push(p);
+  }
+  return out;
+}
+
+function removeEmptyDirs(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) removeEmptyDirs(path.join(dir, e.name));
+  }
+  if (fs.readdirSync(dir).length === 0) {
+    fs.rmdirSync(dir);
+  }
+}
+
+function matchesAny(rel, patterns) {
+  const n = norm(rel);
+  return patterns.some(p => norm(p) === n || globMatch(p, n));
+}
+
+function renderContent(text, vars) {
+  return text
+    .replace(/\{\{project\}\}/g, vars.project)
+    .replace(/\{\{org\}\}/g, vars.org);
+}
+
+function renderPathname(p, project) {
+  return p.replace(/_project_/g, project);
+}
+
+function resolveProjectTemplateDir(projectRoot, templateSource) {
+  const fallbackRoot = resolveTemplateDir();
+
+  const candidates = [];
+  if (templateSource) {
+    if (path.isAbsolute(templateSource)) {
+      candidates.push(templateSource);
+    } else {
+      if (fallbackRoot) {
+        candidates.push(path.resolve(path.dirname(fallbackRoot), templateSource));
+      }
+      candidates.push(path.resolve(projectRoot, templateSource));
+    }
+  }
+  if (fallbackRoot) {
+    candidates.push(fallbackRoot);
+  }
+
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate).isDirectory()) {
+        return candidate;
+      }
+    } catch {
+      // Keep scanning until a valid directory is found.
+    }
+  }
+
+  return null;
+}
+
+function isBinary(fp) {
+  const fd = fs.openSync(fp, 'r');
+  const buf = Buffer.alloc(8192);
+  const n = fs.readSync(fd, buf, 0, 8192, 0);
+  fs.closeSync(fd);
+  if (n === 0) return false;
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+function fileModule(rel) {
+  const p = norm(rel);
+  if (p.startsWith('.github/')) return 'github';
+  if (p.startsWith('.agents/') || p.startsWith('.claude/') ||
+      p.startsWith('.gemini/') || p.startsWith('.opencode/') ||
+      p.startsWith('.codex/') || p === 'AGENTS.md') return 'ai';
+  return null;
+}
+
+function gitUrl(dir) {
+  try {
+    return childProcess.execSync('git remote get-url origin', {
+      cwd: dir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch { return null; }
+}
+
+// Public-facing docs should keep all available language variants in sync.
+const MULTI_LANG = new Set(['SECURITY.md']);
+
+function langSelect(rels, lang, allSet, project) {
+  const sel = new Map();
+
+  if (lang === 'zh-CN') {
+    for (const r of rels) {
+      if (!r.includes('.zh-CN.')) continue;
+      const target = norm(renderPathname(r.replace(/\.zh-CN\./, '.'), project));
+      sel.set(target, r);
+    }
+    for (const r of rels) {
+      if (r.includes('.zh-CN.')) continue;
+      const target = norm(renderPathname(r, project));
+      if (sel.has(target)) continue;
+      const ext = path.extname(r), base = r.slice(0, -ext.length);
+      if (allSet.has(norm(base + '.zh-CN' + ext))) continue;
+      sel.set(target, r);
+    }
+  } else {
+    for (const r of rels) {
+      if (r.includes('.zh-CN.')) continue;
+      sel.set(norm(renderPathname(r, project)), r);
+    }
+  }
+
+  return sel;
+}
+
+function syncTemplates(projectRoot) {
+  const cfgPath = path.join(projectRoot, '.airc.json');
+  if (!fs.existsSync(cfgPath)) {
+    return { error: 'No .airc.json in project root.' };
+  }
+
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  const templateRoot = resolveProjectTemplateDir(projectRoot, cfg.templateSource);
+  if (!templateRoot) {
+    return { error: 'Template source not found. Install: curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh' };
+  }
+  const installDir = resolveInstallDir();
+
+  const hasGit = fs.existsSync(path.join(installDir, '.git'));
+  if (hasGit) {
+    try { childProcess.execSync('git fetch --tags --quiet', { cwd: installDir, stdio: 'pipe' }); } catch { /* network */ }
+  }
+
+  let version = 'unknown';
+  if (hasGit) {
+    let tagOutput;
+    try {
+      tagOutput = childProcess.execSync('git tag --sort=-v:refname', {
+        cwd: installDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+    } catch {
+      return { error: 'Failed to list tags in agent-infra repository. Please check git installation.' };
+    }
+    const latestTag = tagOutput.split('\n')[0];
+    if (!latestTag) {
+      return { error: 'No tags found in agent-infra repository. This is unexpected — please reinstall.' };
+    }
+    try { childProcess.execFileSync('git', ['checkout', latestTag, '--quiet'], { cwd: installDir, stdio: 'pipe' }); } catch { /* ignore */ }
+    version = latestTag;
+  } else {
+    version = INSTALLER_VERSION || version;
+  }
+
+  const { project, org, language: lang = 'en', modules = [] } = cfg;
+  const vars = { project, org };
+
+  const managed = [...(cfg.files.managed || [])];
+  const merged  = [...(cfg.files.merged  || [])];
+  const ejected = [...(cfg.files.ejected || [])];
+
+  const report = {
+    templateVersion: version,
+    templateRoot: norm(templateRoot),
+    registryAdded: [],
+    managed: { written: [], created: [], unchanged: [], skippedMerged: [], skippedModule: [], removed: [] },
+    ejected: { created: [], skipped: [] },
+    merged:  { pending: [] },
+    configUpdated: false,
+    selfUpdate: false
+  };
+
+  const known = new Set([...managed, ...merged, ...ejected]);
+  for (const e of (DEFAULTS.files.managed || [])) {
+    if (!known.has(e)) { managed.push(e); known.add(e); report.registryAdded.push({ entry: e, list: 'managed' }); }
+  }
+  for (const e of (DEFAULTS.files.merged || [])) {
+    if (!known.has(e)) { merged.push(e); known.add(e); report.registryAdded.push({ entry: e, list: 'merged' }); }
+  }
+
+  const allRels = walkDir(templateRoot).map(f => norm(path.relative(templateRoot, f)));
+  const allSet = new Set(allRels);
+  const modSet = new Set(modules);
+
+  for (const entry of managed) {
+    const isDir = entry.endsWith('/');
+    let entryRels;
+    const expectedTargets = isDir ? new Set() : null;
+
+    if (isDir) {
+      const dir = path.join(templateRoot, entry);
+      if (!fs.existsSync(dir)) continue;
+      entryRels = walkDir(dir).map(f => norm(path.relative(templateRoot, f)));
+    } else {
+      entryRels = [];
+      const n = norm(entry);
+      if (allSet.has(n)) entryRels.push(n);
+      const ext = path.extname(entry), base = entry.slice(0, -ext.length);
+      const zh = norm(base + '.zh-CN' + ext);
+      if (allSet.has(zh)) entryRels.push(zh);
+      if (!entryRels.length) continue;
+    }
+
+    const selected = MULTI_LANG.has(norm(entry))
+      ? entryRels.map(r => [norm(renderPathname(r, project)), r])
+      : langSelect(entryRels, lang, allSet, project);
+
+    for (const [tgt, src] of selected) {
+      if (expectedTargets) expectedTargets.add(tgt);
+
+      const mod = fileModule(tgt);
+      if (mod !== null && !modSet.has(mod)) {
+        report.managed.skippedModule.push(tgt);
+        continue;
+      }
+
+      if (matchesAny(tgt, merged) || matchesAny(tgt, ejected)) {
+        report.managed.skippedMerged.push(tgt);
+        continue;
+      }
+
+      const srcFull = path.join(templateRoot, src);
+      const dstFull = path.join(projectRoot, tgt);
+      const bin = isBinary(srcFull);
+      const content = bin
+        ? fs.readFileSync(srcFull)
+        : renderContent(fs.readFileSync(srcFull, 'utf8'), vars);
+
+      const exists = fs.existsSync(dstFull);
+      if (exists) {
+        const cur = bin ? fs.readFileSync(dstFull) : fs.readFileSync(dstFull, 'utf8');
+        if (bin ? content.equals(cur) : content === cur) {
+          report.managed.unchanged.push(tgt);
+          continue;
+        }
+      }
+
+      const dir = path.dirname(dstFull);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(dstFull, content);
+      if (tgt.endsWith('.sh')) {
+        try { fs.chmodSync(dstFull, 0o755); } catch { /* Windows */ }
+      }
+
+      (exists ? report.managed.written : report.managed.created).push(tgt);
+    }
+
+    if (isDir) {
+      const projDir = path.join(projectRoot, entry);
+      if (fs.existsSync(projDir)) {
+        const removedBefore = report.managed.removed.length;
+        const projFiles = walkDir(projDir).map(f => norm(path.relative(projectRoot, f)));
+        for (const projFile of projFiles) {
+          if (expectedTargets.has(projFile)) continue;
+          if (matchesAny(projFile, merged) || matchesAny(projFile, ejected)) continue;
+
+          const mod = fileModule(projFile);
+          if (mod !== null && !modSet.has(mod)) continue;
+
+          fs.unlinkSync(path.join(projectRoot, projFile));
+          report.managed.removed.push(projFile);
+        }
+        if (report.managed.removed.length > removedBefore) {
+          removeEmptyDirs(projDir);
+        }
+      }
+    }
+  }
+
+  for (const entry of ejected) {
+    const dstFull = path.join(projectRoot, entry);
+    if (fs.existsSync(dstFull)) {
+      report.ejected.skipped.push(entry);
+      continue;
+    }
+
+    let src = norm(entry);
+    if (lang === 'zh-CN') {
+      const ext = path.extname(entry), base = entry.slice(0, -ext.length);
+      const zh = norm(base + '.zh-CN' + ext);
+      if (allSet.has(zh)) src = zh;
+    }
+    if (!allSet.has(src)) continue;
+
+    const content = renderContent(fs.readFileSync(path.join(templateRoot, src), 'utf8'), vars);
+    const dir = path.dirname(dstFull);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(dstFull, content);
+    report.ejected.created.push(entry);
+  }
+
+  const mergedMap = new Map();
+  for (const entry of merged) {
+    if (entry.includes('*')) {
+      const hits = allRels.filter(r => {
+        const t = norm(renderPathname(
+          r.includes('.zh-CN.') ? r.replace(/\.zh-CN\./, '.') : r, project
+        ));
+        return globMatch(entry, t);
+      });
+      for (const [t, s] of langSelect(hits, lang, allSet, project)) {
+        if (!mergedMap.has(t)) mergedMap.set(t, s);
+      }
+    } else {
+      const rels = [];
+      const n = norm(entry);
+      if (allSet.has(n)) rels.push(n);
+      const ext = path.extname(entry), base = entry.slice(0, -ext.length);
+      const zh = norm(base + '.zh-CN' + ext);
+      if (allSet.has(zh)) rels.push(zh);
+      const selected = MULTI_LANG.has(n)
+        ? rels.map(r => [norm(renderPathname(r, project)), r])
+        : langSelect(rels, lang, allSet, project);
+      for (const [t, s] of selected) {
+        if (!mergedMap.has(t)) mergedMap.set(t, s);
+      }
+    }
+  }
+  report.merged.pending = [...mergedMap].map(
+    ([target, template]) => ({ target, template })
+  );
+
+  const projUrl = gitUrl(projectRoot);
+  const instUrl = gitUrl(installDir);
+  report.selfUpdate = !!(projUrl && instUrl && projUrl === instUrl);
+
+  const hasChanges = (
+    report.managed.written.length +
+    report.managed.created.length +
+    report.managed.removed.length +
+    report.ejected.created.length +
+    report.registryAdded.length
+  ) > 0;
+
+  const prevVersion = cfg.templateVersion;
+
+  cfg.files.managed = managed;
+  cfg.files.merged  = merged;
+  cfg.files.ejected = ejected;
+  cfg.templateVersion = version;
+
+  report.configUpdated = hasChanges || prevVersion !== version;
+
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+
+  return report;
+}
+
+const entryPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
+if (entryPath === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(process.argv[2] || process.cwd());
+  const result = syncTemplates(root);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  if (result.error) process.exitCode = 1;
+}
+
+export { syncTemplates };

package/templates/.agents/skills/upgrade-dependency/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: upgrade-dependency
+description: >
+  Upgrade a specified dependency package to a new version and verify
+  the change. Triggered when the user requests dependency upgrade.
+  Arguments: package name, old version, new version.
+---
+
+# Upgrade Dependency
+
+Upgrade a dependency package to the specified version with build and test verification.
+
+<!-- TODO: Adapt the commands below to your project's package manager -->
+
+## Execution Flow
+
+### 1. Parse Arguments
+
+Extract from arguments: package name, old version, new version.
+
+### 2. Find Dependency Location
+
+Search for the package in dependency files:
+- `package.json` (Node.js)
+- `pom.xml` (Maven)
+- `requirements.txt` / `pyproject.toml` (Python)
+- `go.mod` (Go)
+- Other project-specific dependency files
+
+### 3. Update Version
+
+Update the version number in the dependency file.
+
+### 4. Install Dependencies
+
+<!-- TODO: Replace with your project's install command -->
+```bash
+# npm install          (Node.js)
+# mvn clean install    (Maven)
+# pip install -r requirements.txt  (Python)
+# go mod tidy          (Go)
+```
+
+### 5. Verify Build
+
+<!-- TODO: Replace with your project's build command -->
+```bash
+# npm run build        (Node.js)
+# mvn compile          (Maven)
+# make build           (generic)
+```
+
+### 6. Run Tests
+
+Execute the project's test command. Reference the test skill for the project-specific test command.
+
+### 7. Output Results
+
+Report:
+- Files modified
+- Build status (pass/fail)
+- Test status (pass/fail)
+- Any deprecation warnings or breaking changes noticed
+
+Suggest next step:
+
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+
+```
+Next step - commit changes:
+  - Claude Code / OpenCode: /commit
+  - Gemini CLI: /{{project}}:commit
+  - Codex CLI: $commit
+```
+
+## Notes
+
+1. **No auto-commit**: Do NOT automatically commit changes
+2. **Major version upgrades**: Warn about potential breaking changes
+3. **Test failures**: Report the failure details and wait for user decision
+4. **Lock files**: If the project uses lock files (package-lock.json, yarn.lock, etc.), ensure they are updated
+5. **Transitive dependencies**: Note if the upgrade affects transitive dependencies
+
+## Error Handling
+
+- Package not found: Prompt "Package {name} not found in dependency files"
+- Build failure: Output errors and suggest checking for breaking changes
+- Test failure: Output test errors and suggest checking migration guide

package/templates/.agents/skills/upgrade-dependency/SKILL.zh-CN.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-dependency
+description: >
+  升级项目中的指定依赖包到新版本并验证变更。
+  当用户要求升级依赖时触发。参数：包名、原版本和新版本。
+---
+
+# 升级依赖
+
+将依赖包升级到指定版本，并进行构建和测试验证。
+
+<!-- TODO: 根据你的项目包管理器调整以下命令 -->
+
+## 执行流程
+
+### 1. 解析参数
+
+从参数中提取：包名、原版本、新版本。
+
+### 2. 查找依赖位置
+
+在依赖文件中搜索目标包：
+- `package.json`（Node.js）
+- `pom.xml`（Maven）
+- `requirements.txt` / `pyproject.toml`（Python）
+- `go.mod`（Go）
+- 其他项目特定的依赖文件
+
+### 3. 更新版本
+
+在依赖文件中更新版本号。
+
+### 4. 安装依赖
+
+<!-- TODO: 替换为你的项目安装命令 -->
+```bash
+# npm install          (Node.js)
+# mvn clean install    (Maven)
+# pip install -r requirements.txt  (Python)
+# go mod tidy          (Go)
+```
+
+### 5. 验证构建
+
+<!-- TODO: 替换为你的项目构建命令 -->
+```bash
+# npm run build        (Node.js)
+# mvn compile          (Maven)
+# make build           (通用)
+```
+
+### 6. 运行测试
+
+执行项目的测试命令。参考 test 技能获取项目特定的测试命令。
+
+### 7. 输出结果
+
+报告：
+- 修改的文件
+- 构建状态（通过/失败）
+- 测试状态（通过/失败）
+- 发现的任何弃用警告或破坏性变更
+
+建议下一步：
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+```
+下一步 - 提交代码：
+  - Claude Code / OpenCode：/commit
+  - Gemini CLI：/{{project}}:commit
+  - Codex CLI：$commit
+```
+
+## 注意事项
+
+1. **禁止自动提交**：不要自动提交变更
+2. **主版本升级**：警告潜在的破坏性变更
+3. **测试失败**：报告失败详情并等待用户决定
+4. **锁文件**：如果项目使用锁文件（package-lock.json、yarn.lock 等），确保一并更新
+5. **传递依赖**：注意升级是否影响传递依赖
+
+## 错误处理
+
+- 包未找到：提示 "Package {name} not found in dependency files"
+- 构建失败：输出错误并建议检查破坏性变更
+- 测试失败：输出测试错误并建议查看迁移指南

package/templates/.agents/templates/handoff.md

@@ -0,0 +1,60 @@
+# Handoff Document
+
+## Metadata
+
+- **Task ID**: task-XXX
+- **From**: [AI tool name, e.g., claude]
+- **To**: [AI tool name, e.g., codex]
+- **Phase Completed**: [e.g., analysis]
+- **Next Phase**: [e.g., design]
+- **Date**: YYYY-MM-DD
+
+## Summary of Completed Work
+
+[Brief summary of what was accomplished in the completed phase.]
+
+## Current State
+
+### Files Modified
+
+- `path/to/file1` - What was changed and why
+- `path/to/file2` - What was changed and why
+
+### Branch Status
+
+- **Branch**: `feature/xxx`
+- **Commits**: [Number of commits made]
+- **Tests**: [Passing / Failing / Not yet written]
+
+### Key Decisions Made
+
+1. [Decision 1 and rationale]
+2. [Decision 2 and rationale]
+
+## Next Steps
+
+[What the receiving AI should do next. Be specific.]
+
+1. [ ] Step 1
+2. [ ] Step 2
+3. [ ] Step 3
+
+## Important Context
+
+[Anything the receiving AI needs to know that isn't obvious from the code.]
+
+### Constraints
+
+- [Constraint 1]
+- [Constraint 2]
+
+### Risks and Concerns
+
+- [Risk 1]
+- [Risk 2]
+
+## References
+
+- Task file: `.agent-workspace/active/task-XXX.md`
+- Related docs: [links or file paths]
+- Related issues: #XXX