@fitlab-ai/agent-infra 0.5.6 → 0.5.7

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

@@ -24,6 +24,7 @@ const DEFAULTS = {
     "type": "github"
   },
   "sandbox": {
+    "engine": null,
     "runtimes": [
       "node20"
     ],
@@ -78,7 +79,7 @@ const DEFAULTS = {
   }
 };
 
-const INSTALLER_VERSION = "v0.5.6";
+const INSTALLER_VERSION = "v0.5.7";
 const PACKAGE_NAME = '@fitlab-ai/agent-infra';
 // Add a new identifier here only after shipping matching .{platform}. template variants.
 const KNOWN_PLATFORMS = new Set(['github']);
@@ -86,6 +87,21 @@ const KNOWN_LANGUAGES = new Set(['en', 'zh-CN']);
 
 function norm(p) { return p.replace(/\\/g, '/'); }
 
+function normDir(p) {
+  return norm(p).replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+function isInsideProject(projectRoot, relativePath) {
+  if (typeof relativePath !== 'string' || relativePath.trim() === '' || path.isAbsolute(relativePath)) {
+    return false;
+  }
+
+  const root = path.resolve(projectRoot);
+  const resolved = path.resolve(projectRoot, relativePath);
+  const rel = path.relative(root, resolved);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
 function globMatch(pattern, filePath) {
   const p = norm(pattern), f = norm(filePath);
   const globstarDir = '__GLOBSTAR_DIR__';
@@ -192,17 +208,26 @@ function detectCustomSkills(projectRoot, templateSkillNames) {
     .sort((left, right) => left.dirName.localeCompare(right.dirName));
 }
 
-function isCustomProtected(targetPath, customSkills, project) {
+function isCustomProtected(targetPath, customSkills, project, customTUICommandTargets) {
   const normalized = norm(targetPath);
 
   return customSkills.some(({ dirName }) => (
     normalized.startsWith(`.agents/skills/${dirName}/`) ||
     normalized === `.claude/commands/${dirName}.md` ||
     normalized === `.opencode/commands/${dirName}.md` ||
-    normalized === '.gemini/commands/' + project + '/' + dirName + '.toml'
+    normalized === '.gemini/commands/' + project + '/' + dirName + '.toml' ||
+    customTUICommandTargets.has(normalized)
   ));
 }
 
+function recordCustomTUISkipped(report, entry) {
+  report?.custom?.customTUIs?.skipped?.push(entry);
+}
+
+function recordCustomTUISkippedRef(report, entry) {
+  report?.custom?.customTUIs?.skippedRefs?.push(entry);
+}
+
 function expandHome(inputPath) {
   if (inputPath === '~') return os.homedir();
   if (inputPath.startsWith('~/')) {
@@ -212,6 +237,81 @@ function expandHome(inputPath) {
   return path.resolve(inputPath);
 }
 
+function mergeTemplateSources(baseRoot, sources, report) {
+  const sourceMap = new Map();
+  const sourceMeta = new Map();
+  const conflictsByRel = new Map();
+  const baseRels = walkDir(baseRoot).map((filePath) => norm(path.relative(baseRoot, filePath)));
+
+  for (const rel of baseRels) {
+    sourceMap.set(rel, baseRoot);
+    sourceMeta.set(rel, { type: 'builtin' });
+  }
+
+  const recordConflict = (rel, winner, ignored) => {
+    const existing = conflictsByRel.get(rel);
+    if (existing) {
+      existing.winner = winner;
+      existing.ignored.push(...ignored);
+      return;
+    }
+
+    const conflict = { rel, winner, ignored: [...ignored] };
+    conflictsByRel.set(rel, conflict);
+    report.templateSources.conflicts.push(conflict);
+  };
+
+  const templateSources = Array.isArray(sources) ? sources : [];
+  for (const [index, source] of templateSources.entries()) {
+    if (source?.type !== 'local') continue;
+    if (typeof source.path !== 'string' || source.path.trim() === '') {
+      report.templateSources.errors.push({
+        index,
+        type: String(source?.type || ''),
+        path: String(source?.path || ''),
+        reason: 'invalid path'
+      });
+      continue;
+    }
+
+    const srcDir = expandHome(source.path);
+    if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory()) {
+      report.templateSources.errors.push({
+        index,
+        type: source.type,
+        path: source.path,
+        reason: 'directory not found'
+      });
+      continue;
+    }
+
+    const extRels = walkDir(srcDir).map((filePath) => norm(path.relative(srcDir, filePath)));
+    const sourceInfo = { type: source.type, path: source.path };
+    for (const rel of extRels) {
+      const existing = sourceMeta.get(rel);
+      if (existing?.type === 'builtin') {
+        recordConflict(rel, existing, [sourceInfo]);
+        continue;
+      }
+
+      if (existing) {
+        recordConflict(rel, sourceInfo, [existing]);
+      }
+
+      sourceMap.set(rel, srcDir);
+      sourceMeta.set(rel, sourceInfo);
+    }
+
+    report.templateSources.loaded += 1;
+    report.templateSources.files += extRels.length;
+  }
+
+  return {
+    mergedRels: [...sourceMap.keys()],
+    sourceMap
+  };
+}
+
 function writeIfChanged(projectRoot, targetPath, content, reportBucket) {
   const fullPath = path.join(projectRoot, targetPath);
   const exists = fs.existsSync(fullPath);
@@ -388,7 +488,154 @@ function generateOpenCodeCommand(skill, lang) {
   return `${lines.join('\n')}\n`;
 }
 
-function generateCustomCommands(projectRoot, customSkills, project, lang, report) {
+function validateCustomTUIs(projectRoot, customTUIs, report) {
+  const tools = Array.isArray(customTUIs) ? customTUIs : [];
+  return tools
+    .map((tool, index) => {
+      if (typeof tool?.dir !== 'string' || tool.dir.trim() === '') {
+        recordCustomTUISkipped(report, {
+          index,
+          name: String(tool?.name || ''),
+          dir: String(tool?.dir || ''),
+          reason: 'invalid dir'
+        });
+        return null;
+      }
+
+      if (!isInsideProject(projectRoot, tool.dir)) {
+        recordCustomTUISkipped(report, {
+          index,
+          name: String(tool?.name || ''),
+          dir: tool.dir,
+          reason: 'dir must be a relative path inside the project root'
+        });
+        return null;
+      }
+
+      return { ...tool, index, dir: normDir(tool.dir) };
+    })
+    .filter(Boolean);
+}
+
+function customTUITargetPath(tool, refFile, refSkillName, skillName) {
+  const targetFile = refFile.includes(refSkillName)
+    ? refFile.replaceAll(refSkillName, skillName)
+    : `${skillName}${path.extname(refFile)}`;
+  return norm(path.join(tool.dir, targetFile));
+}
+
+function findCustomTUIReference(projectRoot, tool, templateSkillNames, report, logSkipped = false) {
+  const cmdDir = path.join(projectRoot, tool.dir);
+  if (!fs.existsSync(cmdDir) || !fs.statSync(cmdDir).isDirectory()) {
+    if (logSkipped) {
+      recordCustomTUISkipped(report, {
+        index: tool.index,
+        name: String(tool.name || ''),
+        dir: tool.dir,
+        reason: 'directory not found'
+      });
+    }
+    return null;
+  }
+
+  const cmdFiles = fs.readdirSync(cmdDir)
+    .filter((file) => fs.statSync(path.join(cmdDir, file)).isFile())
+    .sort((left, right) => left.localeCompare(right));
+  if (cmdFiles.length === 0) {
+    if (logSkipped) {
+      recordCustomTUISkipped(report, {
+        index: tool.index,
+        name: String(tool.name || ''),
+        dir: tool.dir,
+        reason: 'no command files'
+      });
+    }
+    return null;
+  }
+
+  let sawKnownSkillReference = false;
+
+  for (const file of cmdFiles) {
+    const content = fs.readFileSync(path.join(cmdDir, file), 'utf8');
+    const match = content.match(/\.agents\/skills\/([^/]+)\/SKILL\.md/);
+    if (!match) continue;
+
+    const skillName = match[1];
+    if (!templateSkillNames.has(skillName)) continue;
+
+    const skillMd = path.join(projectRoot, '.agents/skills', skillName, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) continue;
+
+    const meta = parseSkillFrontmatter(skillMd);
+    if (!meta.description) continue;
+
+    sawKnownSkillReference = true;
+    if (!content.includes(meta.description)) {
+      if (logSkipped) {
+        recordCustomTUISkippedRef(report, {
+          index: tool.index,
+          name: String(tool.name || ''),
+          dir: tool.dir,
+          file,
+          skill: skillName,
+          reason: 'description not found in reference command file'
+        });
+      }
+      continue;
+    }
+
+    return { content, file, skillName, skillDesc: meta.description };
+  }
+
+  if (logSkipped) {
+    recordCustomTUISkipped(report, {
+      index: tool.index,
+      name: String(tool.name || ''),
+      dir: tool.dir,
+      reason: sawKnownSkillReference
+        ? 'no reference command file with matching description'
+        : 'no usable reference command file'
+    });
+  }
+
+  return null;
+}
+
+function buildCustomTUICommandTargets(projectRoot, customSkills, customTUIs, templateSkillNames) {
+  const targets = new Set();
+  for (const tool of customTUIs) {
+    const ref = findCustomTUIReference(projectRoot, tool, templateSkillNames, null, false);
+    if (!ref) continue;
+
+    for (const skill of customSkills) {
+      targets.add(customTUITargetPath(tool, ref.file, ref.skillName, skill.dirName));
+    }
+  }
+
+  return targets;
+}
+
+function learnAndGenerateCommands(projectRoot, customSkills, tool, templateSkillNames, report) {
+  const ref = findCustomTUIReference(projectRoot, tool, templateSkillNames, report, true);
+  if (!ref) return;
+
+  for (const skill of customSkills) {
+    const descToken = '__AGENT_INFRA_CUSTOM_SKILL_DESCRIPTION__';
+    const generated = ref.content
+      .replaceAll(ref.skillDesc, descToken)
+      .replaceAll(ref.skillName, skill.dirName)
+      .replaceAll(descToken, skill.description);
+
+    writeIfChanged(
+      projectRoot,
+      customTUITargetPath(tool, ref.file, ref.skillName, skill.dirName),
+      generated,
+      report.custom.commands
+    );
+  }
+}
+
+function generateCustomCommands(projectRoot, customSkills, project, lang, report, customTUIs, templateSkillNames) {
   for (const skill of customSkills) {
     writeIfChanged(
       projectRoot,
@@ -409,6 +656,11 @@ function generateCustomCommands(projectRoot, customSkills, project, lang, report
       report.custom.commands
     );
   }
+
+  const tools = Array.isArray(customTUIs) ? customTUIs : [];
+  for (const tool of tools) {
+    learnAndGenerateCommands(projectRoot, customSkills, tool, templateSkillNames, report);
+  }
 }
 
 function matchesAny(rel, patterns) {
@@ -698,6 +950,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
 
   const { project, org, language: lang = 'en' } = cfg;
   const platformType = cfg.platform?.type || DEFAULTS.platform.type;
+  const customTUIsConfig = Array.isArray(cfg.customTUIs) ? cfg.customTUIs : [];
   const vars = { project, org };
   const templateSkillNames = listTemplateSkillNames(templateRoot);
   const protectedCustomSkills = detectCustomSkills(projectRoot, templateSkillNames);
@@ -710,6 +963,13 @@ function syncTemplates(projectRoot, templateRootOverride) {
     templateVersion: version,
     templateRoot: norm(templateRoot),
     registryAdded: [],
+    templateSources: {
+      configured: 0,
+      loaded: 0,
+      files: 0,
+      errors: [],
+      conflicts: []
+    },
     managed: { written: [], created: [], unchanged: [], skippedMerged: [], removed: [] },
     custom: {
       detected: [],
@@ -718,6 +978,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
       unchanged: [],
       removed: [],
       sourceErrors: [],
+      customTUIs: { skipped: [], skippedRefs: [] },
       commands: { generated: [], updated: [], unchanged: [] }
     },
     ejected: { created: [], skipped: [] },
@@ -725,6 +986,13 @@ function syncTemplates(projectRoot, templateRootOverride) {
     configUpdated: false,
     selfUpdate: false
   };
+  const customTUIs = validateCustomTUIs(projectRoot, customTUIsConfig, report);
+  const customTUICommandTargets = buildCustomTUICommandTargets(
+    projectRoot,
+    protectedCustomSkills,
+    customTUIs,
+    templateSkillNames
+  );
 
   const known = new Set([...managed, ...merged, ...ejected]);
   for (const e of (DEFAULTS.files.managed || [])) {
@@ -734,7 +1002,10 @@ function syncTemplates(projectRoot, templateRootOverride) {
     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 templateSources = Array.isArray(cfg.templates?.sources) ? cfg.templates.sources : [];
+  report.templateSources.configured = templateSources.length;
+  const { mergedRels, sourceMap } = mergeTemplateSources(templateRoot, templateSources, report);
+  const allRels = mergedRels;
   const allSet = new Set(allRels);
   for (const entry of managed) {
     const isDir = entry.endsWith('/');
@@ -743,10 +1014,14 @@ function syncTemplates(projectRoot, templateRootOverride) {
 
     if (isDir) {
       const dir = path.join(templateRoot, entry);
-      if (!fs.existsSync(dir)) continue;
-      entryRels = walkDir(dir).map(f => norm(path.relative(templateRoot, f)));
+      const builtinRels = fs.existsSync(dir)
+        ? walkDir(dir).map((filePath) => norm(path.relative(templateRoot, filePath)))
+        : [];
+      const prefix = norm(entry);
+      const externalRels = allRels.filter((rel) => rel.startsWith(prefix) && !builtinRels.includes(rel));
+      entryRels = [...builtinRels, ...externalRels];
+      if (!entryRels.length) continue;
     } else {
-      entryRels = [];
       entryRels = entryVariantRels(entry, allSet, platformType);
       if (!entryRels.length) continue;
     }
@@ -761,7 +1036,8 @@ function syncTemplates(projectRoot, templateRootOverride) {
         continue;
       }
 
-      const srcFull = path.join(templateRoot, src);
+      const srcRoot = sourceMap.get(src) || templateRoot;
+      const srcFull = path.join(srcRoot, src);
       const dstFull = path.join(projectRoot, tgt);
       const bin = isBinary(srcFull);
       const content = bin
@@ -795,7 +1071,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
         for (const projFile of projFiles) {
           if (expectedTargets.has(projFile)) continue;
           if (projFile === configPathRel) continue;
-          if (isCustomProtected(projFile, protectedCustomSkills, project)) continue;
+          if (isCustomProtected(projFile, protectedCustomSkills, project, customTUICommandTargets)) continue;
           if (matchesAny(projFile, merged) || matchesAny(projFile, ejected)) continue;
 
           fs.unlinkSync(path.join(projectRoot, projFile));
@@ -816,7 +1092,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
 
   const customSkills = detectCustomSkills(projectRoot, templateSkillNames);
   report.custom.detected = customSkills.map((skill) => skill.dirName);
-  generateCustomCommands(projectRoot, customSkills, project, lang, report);
+  generateCustomCommands(projectRoot, customSkills, project, lang, report, customTUIs, templateSkillNames);
 
   for (const entry of ejected) {
     const dstFull = path.join(projectRoot, entry);
@@ -830,7 +1106,8 @@ function syncTemplates(projectRoot, templateRootOverride) {
     const src = selected.get(target);
     if (!src) continue;
 
-    const content = renderContent(fs.readFileSync(path.join(templateRoot, src), 'utf8'), vars);
+    const srcRoot = sourceMap.get(src) || templateRoot;
+    const content = renderContent(fs.readFileSync(path.join(srcRoot, src), 'utf8'), vars);
     const dir = path.dirname(dstFull);
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(dstFull, content);

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

@@ -61,7 +61,7 @@ Report:
 
 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.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
 
 ```
 Next step - commit changes:

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

@@ -61,7 +61,7 @@ description: "升级项目依赖到新版本并验证"
 
 建议下一步：
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ```
 下一步 - 提交代码：

package/templates/.agents/templates/task.en.md

@@ -1,13 +1,13 @@
 ---
 id: task-XXX
 type: feature                  # feature | bugfix | refactor | docs | review
-branch: ""                     # <project>-<type>-<slug>
+branch:                        # <project>-<type>-<slug>
 workflow: feature-development  # feature-development | bug-fix | code-review | refactoring
 status: open                   # open | in-progress | review | blocked | completed
 created_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 updated_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 current_step: analysis         # analysis | design | implementation | review | fix | commit
-assigned_to: ""                # claude | codex | gemini | opencode | human
+assigned_to:                   # claude | codex | gemini | opencode | human
 ---
 
 # Task: [Title]

package/templates/.agents/templates/task.zh-CN.md

@@ -1,13 +1,13 @@
 ---
 id: task-XXX
 type: feature                  # feature | bugfix | refactor | docs | review
-branch: ""                     # <project>-<type>-<slug>
+branch:                        # <project>-<type>-<slug>
 workflow: feature-development  # feature-development | bug-fix | code-review | refactoring
 status: open                   # open | in-progress | review | blocked | completed
 created_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 updated_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 current_step: analysis         # analysis | design | implementation | review | fix | commit
-assigned_to: ""                # claude | codex | gemini | opencode | human
+assigned_to:                   # claude | codex | gemini | opencode | human
 ---
 
 # 任务：[标题]

package/templates/.claude/commands/post-release.en.md

@@ -0,0 +1,8 @@
+---
+description: "Run post-release tasks"
+disable-model-invocation: true
+---
+
+Read and execute the post-release skill from `.agents/skills/post-release/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.claude/commands/post-release.zh-CN.md

@@ -0,0 +1,8 @@
+---
+description: "执行版本发布后处理"
+disable-model-invocation: true
+---
+
+读取并执行 `.agents/skills/post-release/SKILL.md` 中的 post-release 技能。
+
+严格按照技能中定义的所有步骤执行。

package/templates/.gemini/commands/_project_/post-release.en.toml

@@ -0,0 +1,6 @@
+description = "Run post-release tasks"
+prompt = """
+Read and execute the post-release skill from `.agents/skills/post-release/SKILL.md`.
+
+Follow all steps defined in the skill exactly.
+"""

package/templates/.gemini/commands/_project_/post-release.zh-CN.toml

@@ -0,0 +1,6 @@
+description = "执行版本发布后处理"
+prompt = """
+读取并执行 `.agents/skills/post-release/SKILL.md` 中的 post-release 技能。
+
+严格按照技能中定义的所有步骤执行。
+"""

package/templates/.opencode/commands/post-release.en.md

@@ -0,0 +1,9 @@
+---
+description: "Run post-release tasks"
+agent: general
+subtask: false
+---
+
+Read and execute the post-release skill from `.agents/skills/post-release/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.opencode/commands/post-release.zh-CN.md

@@ -0,0 +1,9 @@
+---
+description: "执行版本发布后处理"
+agent: general
+subtask: false
+---
+
+读取并执行 `.agents/skills/post-release/SKILL.md` 中的 post-release 技能。
+
+严格按照技能中定义的所有步骤执行。