agentic-flow-kit 1.8.7 → 2.0.0

package/src/git/config.mjs

@@ -0,0 +1,61 @@
+import { execFileSync } from 'node:child_process';
+
+export const HOOKS_PATH = '.githooks';
+export const JSONL_UNION_DRIVER = 'node .agents/scripts/git-merge-jsonl.mjs %O %A %B';
+
+export function isGitRepo(target) {
+  try {
+    execFileSync('git', ['-C', target, 'rev-parse', '--git-dir'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getConfig(target, key) {
+  try {
+    return execFileSync('git', ['-C', target, 'config', '--get', key], { encoding: 'utf8' }).trim();
+  } catch {
+    return '';
+  }
+}
+
+export function setConfig(target, key, value) {
+  execFileSync('git', ['-C', target, 'config', key, value], { stdio: 'ignore' });
+}
+
+export function configureGit(target) {
+  setConfig(target, 'core.hooksPath', HOOKS_PATH);
+  setConfig(target, 'merge.ours.driver', 'true');
+  setConfig(target, 'merge.jsonl-union.driver', JSONL_UNION_DRIVER);
+}
+
+export function doctorGit(target) {
+  const checks = [];
+  if (!isGitRepo(target)) {
+    checks.push({ ok: false, name: 'git repository', detail: '目标不是 git 仓库，无法配置/校验 git 门禁' });
+    return checks;
+  }
+  const hooks = getConfig(target, 'core.hooksPath');
+  checks.push({
+    ok: hooks === HOOKS_PATH,
+    name: 'core.hooksPath',
+    detail: hooks || '未配置',
+    fix: `git -C "${target}" config core.hooksPath ${HOOKS_PATH}`,
+  });
+  const ours = getConfig(target, 'merge.ours.driver');
+  checks.push({
+    ok: ours === 'true',
+    name: 'merge.ours.driver',
+    detail: ours || '未配置',
+    fix: `git -C "${target}" config merge.ours.driver true`,
+  });
+  const jsonl = getConfig(target, 'merge.jsonl-union.driver');
+  checks.push({
+    ok: jsonl === JSONL_UNION_DRIVER,
+    name: 'merge.jsonl-union.driver',
+    detail: jsonl || '未配置',
+    fix: `git -C "${target}" config merge.jsonl-union.driver "${JSONL_UNION_DRIVER}"`,
+  });
+  return checks;
+}

package/src/hosts/registry.mjs

@@ -0,0 +1,26 @@
+// 宿主注册表：v1 十宿主。dir 为宿主点目录；rootMemory 为项目根记忆文件（仅 Claude 有）。
+// tracked 仅描述当前本仓的人库政策，不影响安装能力。
+export const HOSTS = {
+  trae: { dir: '.trae', label: 'Trae', tracked: true },
+  codebuddy: { dir: '.codebuddy', label: 'CodeBuddy', tracked: true },
+  claude: { dir: '.claude', label: 'Claude Code', tracked: false, rootMemory: 'CLAUDE.md' },
+  opencode: { dir: '.opencode', label: 'OpenCode', tracked: false },
+  qwen: { dir: '.qwen', label: 'Qwen Code', tracked: false },
+  pi: { dir: '.pi', label: 'PI', tracked: false },
+  cline: { dir: '.cline', label: 'Cline', tracked: false },
+  commandcode: { dir: '.commandcode', label: 'Command Code', tracked: false },
+  qoder: { dir: '.qoder', label: 'Qoder', tracked: false },
+  zcode: { dir: '.zcode', label: 'ZCode', tracked: false },
+};
+
+export const HOST_NAMES = Object.keys(HOSTS);
+
+export function resolveHost(name) {
+  const key = String(name || '').trim().toLowerCase();
+  if (!HOSTS[key]) {
+    const err = new Error(`unknown host: ${name}`);
+    err.code = 'UNKNOWN_HOST';
+    throw err;
+  }
+  return { name: key, ...HOSTS[key] };
+}

package/src/i18n.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const KIT = path.resolve(HERE, '..');
+const LOCALES = path.join(KIT, 'locales');
+const FALLBACK = 'zh-CN';
+
+const cache = new Map();
+export function loadCatalog(lang) {
+  if (cache.has(lang)) return cache.get(lang);
+  const file = path.join(LOCALES, lang, 'installer.json');
+  let cat = {};
+  try {
+    cat = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    if (lang !== FALLBACK) return loadCatalog(FALLBACK);
+    throw new Error(`missing installer locale: ${file}`);
+  }
+  cache.set(lang, cat);
+  return cat;
+}
+
+export function makeT(lang) {
+  const cat = loadCatalog(lang);
+  const fallback = lang === FALLBACK ? cat : loadCatalog(FALLBACK);
+  return (key, vars = {}) => {
+    const raw = cat[key] ?? fallback[key] ?? key;
+    return String(raw).replace(/\{\{(\w+)\}\}/g, (m, k) => (Object.prototype.hasOwnProperty.call(vars, k) ? String(vars[k]) : m));
+  };
+}

package/src/install/apply.mjs

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { render } from '../render/tokens.mjs';
+import { sha256Text } from './manifest.mjs';
+
+const GITATTR_BEGIN = '# >>> agentic-flow-kit gitattributes';
+const GITATTR_END = '# <<< agentic-flow-kit gitattributes';
+const GITIGNORE_BEGIN = '# >>> agentic-flow-kit ignores';
+const GITIGNORE_END = '# <<< agentic-flow-kit ignores';
+
+const BINARY_EXT = new Set(['.exe', '.png', '.jpg', '.jpeg', '.gif', '.ico', '.ttf', '.woff', '.woff2', '.zip', '.gz', '.pdf']);
+
+function isBinary(file) {
+  return BINARY_EXT.has(path.extname(file).toLowerCase());
+}
+
+function readText(abs) {
+  return fs.readFileSync(abs, 'utf8');
+}
+
+function eolOf(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function mergeBlock(existing, block, begin, end) {
+  const eol = eolOf(existing);
+  const normalized = block.replace(/\r?\n/g, eol);
+  const beginIdx = existing.indexOf(begin);
+  const endIdx = existing.indexOf(end);
+  if (beginIdx >= 0 && endIdx > beginIdx) {
+    const after = endIdx + end.length;
+    return existing.slice(0, beginIdx) + normalized + existing.slice(after);
+  }
+  const sep = existing.length && !existing.endsWith(eol) ? eol : '';
+  const gap = existing.length ? eol : '';
+  return `${existing}${sep}${gap}${normalized}${eol}`;
+}
+
+export function readPlanEntry(entry, vars) {
+  if (isBinary(entry.srcAbs)) return null;
+  const raw = readText(entry.srcAbs);
+  return render(raw, vars);
+}
+
+export function applyPlan({ plan, vars, manifest, dryRun, force, log }) {
+  const stats = { create: 0, update: 0, skip: 0, conflict: 0, merge: 0 };
+  const nextFiles = { ...(manifest.files || {}) };
+  const writes = [];
+
+  for (const entry of plan.entries) {
+    const abs = path.join(plan.target, entry.targetRel);
+    const exists = fs.existsSync(abs);
+    const currentHash = exists ? sha256Text(readText(abs)) : null;
+    const managedHash = manifest.files ? manifest.files[entry.targetRel] : null;
+
+    if (entry.kind === 'merge-gitattributes' || entry.kind === 'merge-gitignore') {
+      const text = readPlanEntry(entry, vars) || '';
+      const begin = entry.kind === 'merge-gitattributes' ? GITATTR_BEGIN : GITIGNORE_BEGIN;
+      const end = entry.kind === 'merge-gitattributes' ? GITATTR_END : GITIGNORE_END;
+      const block = `${begin}\n${text.trimEnd()}\n${end}\n`;
+      const existing = exists ? readText(abs) : '';
+      const merged = exists ? mergeBlock(existing, block, begin, end) : block;
+      if (existing === merged) {
+        stats.skip += 1;
+        log('skip', `${entry.targetRel}（已是最新）`);
+        continue;
+      }
+      writes.push({ abs, text: merged, targetRel: entry.targetRel });
+      stats.merge += 1;
+      log(exists ? 'update' : 'create', `${entry.targetRel}（合并块）`);
+      continue;
+    }
+
+    const text = readPlanEntry(entry, vars);
+    if (text == null) {
+      stats.skip += 1;
+      log('skip', `${entry.targetRel}（二进制模板跳过）`);
+      continue;
+    }
+
+    if (!exists) {
+      writes.push({ abs, text, targetRel: entry.targetRel });
+      stats.create += 1;
+      log('create', entry.targetRel);
+      continue;
+    }
+
+    if (force || (managedHash && managedHash === currentHash)) {
+      writes.push({ abs, text, targetRel: entry.targetRel });
+      stats.update += 1;
+      log('update', entry.targetRel);
+      continue;
+    }
+
+    if (managedHash && managedHash !== currentHash) {
+      stats.conflict += 1;
+      log('conflict', `${entry.targetRel}（已安装后被修改，跳过；--force 可覆盖）`);
+      continue;
+    }
+
+    stats.skip += 1;
+    log('skip', `${entry.targetRel}（已存在且非本工具安装，跳过；--force 可覆盖）`);
+  }
+
+  if (!dryRun) {
+    for (const w of writes) {
+      fs.mkdirSync(path.dirname(w.abs), { recursive: true });
+      fs.writeFileSync(w.abs, w.text, 'utf8');
+      nextFiles[w.targetRel] = sha256Text(w.text);
+    }
+  }
+
+  return { stats, files: nextFiles };
+}
+
+export function summaryLine(stats, t) {
+  return t('install.summary', {
+    create: stats.create,
+    update: stats.update,
+    merge: stats.merge,
+    skip: stats.skip,
+    conflict: stats.conflict,
+  });
+}

package/src/install/manifest.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const MANIFEST_REL = '.agents/install-manifest.json';
+
+export function readManifest(target) {
+  const file = path.join(target, MANIFEST_REL);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeManifest(target, manifest) {
+  const file = path.join(target, MANIFEST_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+
+export function sha256Text(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+export function sha256File(abs) {
+  return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+}
+
+export function emptyManifest({ kitVersion, language, hosts, stack }) {
+  return {
+    kit: 'agentic-flow-kit',
+    version: kitVersion,
+    installedAt: new Date().toISOString(),
+    language,
+    hosts,
+    stack,
+    files: {},
+  };
+}

package/src/install/plan.mjs

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HOSTS } from '../hosts/registry.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const KIT_ROOT = path.resolve(HERE, '..', '..');
+export const TEMPLATES = path.join(KIT_ROOT, 'templates');
+export const LOCALES = path.join(KIT_ROOT, 'locales');
+
+export function listFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const walk = (abs, rel) => {
+    for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
+      const childAbs = path.join(abs, ent.name);
+      const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) walk(childAbs, childRel);
+      else if (ent.isFile()) out.push(childRel);
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+function localeOverride(lang, targetRel) {
+  const p = path.join(LOCALES, lang, 'overrides', targetRel);
+  return fs.existsSync(p) ? p : null;
+}
+
+// 构建安装计划。targetRel 使用 / 分隔；profile 覆盖 engine，宿主只写自己的点目录。
+export function buildPlan({ target, hosts, lang, stack, projectName, categories }) {
+  const plan = [];
+  const push = (srcAbs, targetRel, category, priority = 10, kind = 'file') => {
+    plan.push({ srcAbs, targetRel: targetRel.replace(/\\/g, '/'), category, priority, kind });
+  };
+
+  // 1) 引擎核心
+  for (const rel of listFiles(path.join(TEMPLATES, 'engine'))) {
+    push(path.join(TEMPLATES, 'engine', rel), rel, 'engine', 10);
+  }
+
+  // 2) 项目 profile（栈相关配置与 AGENTS.md）
+  for (const rel of listFiles(path.join(TEMPLATES, 'profiles', stack))) {
+    push(path.join(TEMPLATES, 'profiles', stack, rel), rel, 'profile', 20);
+  }
+
+  // 3) 宿主适配层
+  for (const host of hosts) {
+    const h = HOSTS[host];
+    if (!h) continue;
+    for (const rel of listFiles(path.join(TEMPLATES, 'hosts', host))) {
+      const targetRel = host === 'claude' && rel === 'CLAUDE.md' ? 'CLAUDE.md' : `${h.dir}/${rel}`;
+      push(path.join(TEMPLATES, 'hosts', host, rel), targetRel, 'host', 30);
+    }
+  }
+
+  // 4) 数据资产脚手架（空目录由 scaffold 中的 .gitkeep 保证）
+  for (const rel of listFiles(path.join(TEMPLATES, 'scaffold'))) {
+    push(path.join(TEMPLATES, 'scaffold', rel), rel, 'scaffold', 10);
+  }
+
+  // 5) git 门禁与合并策略
+  for (const rel of listFiles(path.join(TEMPLATES, 'git'))) {
+    if (rel === '.gitattributes') push(path.join(TEMPLATES, 'git', rel), '.gitattributes', 'git', 40, 'merge-gitattributes');
+    else if (rel === '.gitignore.engine') push(path.join(TEMPLATES, 'git', rel), '.gitignore', 'git', 40, 'merge-gitignore');
+    else push(path.join(TEMPLATES, 'git', rel), rel, 'git', 40);
+  }
+
+  // 6) 语言包覆盖（按目标路径镜像）
+  for (const entry of plan) {
+    const override = localeOverride(lang, entry.targetRel);
+    if (override) entry.srcAbs = override;
+  }
+
+  // 同目标去重：高优先级覆盖低优先级
+  const byTarget = new Map();
+  for (const entry of plan.sort((a, b) => a.priority - b.priority)) byTarget.set(entry.targetRel, entry);
+  let deduped = [...byTarget.values()];
+  if (categories && categories.length) deduped = deduped.filter((e) => categories.includes(e.category));
+
+  return { target, hosts, lang, stack, projectName, entries: deduped };
+}

package/src/render/tokens.mjs

@@ -0,0 +1,58 @@
+import { HOSTS } from '../hosts/registry.mjs';
+
+// 模板变量：只替换已知 token，未知 {{...}} 原样保留（避免误伤代码模板字符串）。
+export function buildVars({ target, projectName, stack, language, hosts, kitVersion, installedAt, trackHosts = false }) {
+  const stackDefaults = {
+    dotnet: {
+      description: 'ASP.NET Core 后端 + Vue 3 前端 + SQL Server。',
+      descriptionEn: 'ASP.NET Core backend + Vue 3 frontend + SQL Server.',
+      apiPort: 8932,
+      webPort: 5203,
+    },
+    node: {
+      description: 'Node.js / TypeScript 项目。',
+      descriptionEn: 'A Node.js / TypeScript project.',
+      apiPort: 3000,
+      webPort: 5173,
+    },
+    empty: {
+      description: '项目技术栈按实际填写。',
+      descriptionEn: 'Fill in the project stack description.',
+      apiPort: 3000,
+      webPort: 5173,
+    },
+  };
+  const d = stackDefaults[stack] || stackDefaults.empty;
+  const stackDescription = language === 'en' ? d.descriptionEn : d.description;
+  const hostIgnores = trackHosts
+    ? ''
+    : hosts
+        .filter((h) => HOSTS[h] && !HOSTS[h].tracked)
+        .map((h) => `${HOSTS[h].dir}/`)
+        .join('\n');
+  return {
+    projectName: projectName || pathBase(target),
+    stack,
+    stackDescription,
+    language,
+    apiPort: String(d.apiPort),
+    webPort: String(d.webPort),
+    boardPort: '8933',
+    hosts: hosts.join(', '),
+    hostsJson: JSON.stringify(hosts),
+    kitVersion,
+    installedAt,
+    nodeMinimum: '22',
+    hostIgnores,
+  };
+}
+
+function pathBase(p) {
+  const s = String(p || '').replace(/\\/g, '/').replace(/\/+$/, '');
+  const i = s.lastIndexOf('/');
+  return i >= 0 ? s.slice(i + 1) : s;
+}
+
+export function render(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (m, key) => (Object.prototype.hasOwnProperty.call(vars, key) ? String(vars[key]) : m));
+}