agentic-flow-kit 1.8.2 → 2.0.0

package/locales/en/overrides/workflow/specs/_TEMPLATE.md

@@ -0,0 +1,86 @@
+---
+状态: draft
+级别: L1
+模块: <one of the vocabulary entries; see .agents/config/workflow-modules.txt>
+---
+# SPEC — <same topic as the entry document>
+<!-- Pairs with the same-named entry document under intents/ or incidents/; L2 / L3 must have a confirmed spec before a plan may be drafted; L1 may omit this file -->
+<!-- frontmatter restricted subset (2026-09-13): status ∈ draft/approved/done/superseded/cancelled (done = closed, superseded = abandoned after confirmation, cancelled = cancelled before completion); after L3 confirmation, append two lines to frontmatter: `确认结果: approved` and `确认时间: YYYY-MM-DD` (check-loop enforces this for L3) -->
+<!-- ambiguity discipline (2026-10-16): when drafting/revising, do not guess at ambiguities you cannot decide yourself (multiple interpretations / missing semantics / dependence on external facts) — insert [NEEDS CLARIFICATION]: <one-sentence question> in place in the relevant section and keep the document in draft while asking the user; after clarification, delete the marker and record the decision as body text. Markers must be cleared before approval (see workflow/README.md document protocol "explicit ambiguity blocking"). -->
+
+对应入口：../intents/YYYY-MM-DD-<topic>.md or ../incidents/YYYY-MM-DD-<topic>.md (keep the actual one)
+
+## 功能行为
+<Explain clearly how the feature works; break user / system behavior into subsections, and add state-machine / sequence diagrams where needed>
+
+## 数据流
+<Where data comes from → what processing it goes through → where it lands; include field mappings, API contracts, and upstream/downstream dependencies>
+
+## 系统改动清单
+- Backend: modules / files / API contracts
+- Database: none / <table + fields + migration SQL path>
+- Frontend: routes / components / stores / api
+
+## 约束遵守映射（对照 AGENTS.md 触达红线）
+<!-- Since 2026-10-29: the mapping must cover the machine-gate / red-line items in the AGENTS.md files of project directories (regardless of this change's surface — it is the repository-wide contract baseline, required reading before drafting, see stages.md Design §2 "required inputs"); cite wiki evidence by path in the relevant section -->
+| Red line | How this spec satisfies it |
+|------|------------------|
+| Application must not reference Infrastructure / DbContext | <Via XXX, without introducing YYY> |
+| Rules / contracts (coding authority / shared contracts / existing API semantics / global cross-cutting semantics) | <Whether touched (touching it is the basis for L2); coding authority remains in the backend> |
+| schema / migration SQL (no dotnet ef) | <SQL paths involved; the historical EF Migrations directory (including ModelSnapshot) has been removed entirely and must not be recreated> |
+| Frontend: Drawer / no a-select / unified style.css | <Which frontend conventions this spec involves> |
+
+## 验收判据
+<!-- Machine input for criterion-level convergence reconciliation (check-loop check 23): one criterion per line; "evidence" must be machine-parseable.
+     Path: the file must exist. The machine does not read the body or judge whether it is relevant to the criterion (that step is left to a new-session review).
+     Command: only npm test / dotnet test / dotnet build / npm run build / verify.mjs that have been run by the full gate are accepted.
+     Since convergenceHardSince, workflow/verify-evidence.md must also contain an all-green line whose time is not earlier than this spec's "date"; without that line = not covered.
+     Date semantics: the frontmatter "date" and the all-green line time are both UTC (fill-spec defaults to this); for hand-written files do not use a local-timezone date — an all-green line recorded between 00:00 and 08:00 UTC+8 gets the previous day's date and will not match (hard block; rerun the gate after 08:00 to resolve).
+     verify-ui / vue-tsc / regression-smoke etc. are not part of the full gate; record an evidence file path instead.
+     Writing "covered" as the status while the evidence is invalid still counts as not covered. For manual walkthroughs write "manual" as the status and leave the evidence column empty (only "manual + empty evidence" is exempt from machine reconciliation; images such as screenshots are not on the path allowlist — save them in a .md report and cite that path).
+     Missing this section or an empty table → WARN. Invalid evidence: WARN only at convergenceSince; HARD-BLOCK from convergenceHardSince. -->
+| 判据（可观察行为） | 证据（测试文件 / 命令 / 证据文件） | 状态 | 对应验收 |
+|---|---|---|---|
+| <Behavior 1> | <path or command> | <覆盖 / 未覆盖 / 人工> | <A1 or A1, A3> |
+
+<!-- The "Corresponding acceptance" column = acceptance IDs from the entry intent (the confirmation gate has enforced this since anchor coverageSince 2026-10-22): each An must be referenced at least once, and one criterion may map to many; leave it blank when a technical criterion has no corresponding acceptance item (coverage is one-way only — do not invent fake acceptance items to satisfy it in reverse). See stage-gates coverageGate for the criterion gate. -->
+
+## 风险评估
+- <Risk 1> | Mitigation: <test / hook / review>
+- <Risk 2> | Mitigation: …
+
+## 前提质询
+<!-- Blocks "confidently wrong interpretations" (premise-interrogation 2026-10-29; root cause incidents/2026-10-23-pml-quota-substitute-identity-overwrite:
+     a presentation requirement was written as a stored-identity rewrite; tests locked in expectations based on the wrong premise, and review only checked internal consistency — three layers failed from the same source, and the only possible interception point is before the premise enters the source of truth).
+     One asserted premise per line: challenge the opposite interpretation and state why the conclusion was chosen; for small items with no interpretation risk, write one line "no key premises" + reason.
+     confirm-doc hard-blocks this (premiseSince 2026-10-30 anchor): missing section / empty table / unfilled placeholder / missing challenge or missing basis → reject. -->
+| 前提 | 反问（对立解读会怎样） | 结论与依据 |
+|---|---|---|
+| <Interpretation / semantic choice being asserted> | <What happens under the opposite interpretation; worst-case consequence> | <Chosen interpretation + why (user's exact words / document / experiment)> |
+
+## 歧义清单
+<!-- One line per dimension; confirmation is allowed only after pending items reach zero; see .agents/commands/stages.md Design §2.7 and stage-gates clarifyGate for the single source of process and criteria.
+     A missing dimension ≠ no ambiguity; legacy documents before the anchor and documents without frontmatter "date" do not participate. -->
+| 维度 | 结论 | 依据 / 问题 | 状态 |
+|---|---|---|---|
+| 状态与边界 | <Who can do what in which state; privilege escalation / concurrency / idempotency?> | <State-machine section number or code path> | <已定 / 待澄清> |
+| 数据口径 | <Nulls, precision, units, time zones, sort stability?> | <Query result or existing implementation> | <已定 / 待澄清> |
+| 失败路径 | <On partial success, is there a rollback, retry, and what prompt does the user see?> | <Basis> | <已定 / 待澄清> |
+| 契约对称 | <Do ≥2 consumers use the same semantics; how are old callers kept compatible?> | <Consumer list> | <已定 / 待澄清> |
+| 存量数据 | <How are historical rows interpreted; is backfill needed?> | <Measured data distribution> | <已定 / 待澄清> |
+| 验收可测性 | <Can each acceptance item be decided by one command or one experiment?> | <Test file or command> | <已定 / 待澄清> |
+
+## 假设与推断
+<!-- Record only inferences (semantic choices without experiment / code / documentation support), not measured facts; delete this section if there are no inferences. -->
+| Assumption | Impact surface | What if it does not hold |
+|---|---|---|
+| <One-sentence assumption> | <Affected modules / endpoints / pages> | <Rework scope and fallback> |
+
+## 确认与复核
+> AI-Native workflow: confirmation = the user approves in one sentence in the conversation; there is no second approver, and traceability relies on git (commits record the confirmation time).
+> Confirmation result / time go in the file-header frontmatter (enforced by check-loop for L3); this section only keeps narrative review records.
+
+- Independent review: <Mandatory for L3: open a new session and have AI review this spec, recording the review session and conclusion; delete this line if absent for L1 / L2. Since 2026-10-12 (reviewerSince) the review line must include "复核上下文：<session/subagent id>">
+- Review conclusion: <delete this line if none>
+- Rework comments: <delete this line if none>
+- Only after confirmation may you draft ../plans/YYYY-MM-DD-<topic>.md

package/locales/en/overrides/workflow/verify-evidence.md

@@ -0,0 +1,4 @@
+# Test-green evidence reconciliation (generated, do not hand-edit)
+
+> Regenerated by `node .agents/scripts/gen-verify-evidence.mjs` from `.agents/verifications.jsonl`.
+> Placeholder for new installs; populated after the first generation.

package/locales/zh-CN/installer.json

@@ -0,0 +1,25 @@
+{
+  "help": "agentic-flow-kit v{{version}}\n\n用法：\n  flow-kit install --agent <host> [--agent <host>...] [--lang zh-CN|en] [--stack dotnet|node|empty] [--target <dir>] [--dry-run] [--force] [--no-git-config] [--track-hosts]\n  flow-kit add-host <host> [--target <dir>] [--dry-run] [--force]\n  flow-kit upgrade [--target <dir>] [--dry-run] [--force]\n  flow-kit doctor [--target <dir>] [--deep] [--fix]\n  flow-kit list-hosts\n\n宿主：trae, codebuddy, claude, opencode, qwen, pi, cline, commandcode, qoder, zcode\n\n示例：\n  node cli-tools/agentic-flow-kit/bin/flow-kit.mjs install --agent trae --agent codebuddy --lang zh-CN --target .\n",
+  "install.start": "▶ {{command}} → {{target}}",
+  "install.plan": "  宿主={{hosts}} 栈={{stack}} 语言={{lang}} 计划={{count}} 个文件",
+  "install.dryRun": "  （dry-run：只打印计划，不写盘）",
+  "install.create": "创建",
+  "install.update": "更新",
+  "install.skip": "跳过",
+  "install.conflict": "冲突",
+  "install.summary": "完成：创建 {{create}} / 更新 {{update}} / 合并 {{merge}} / 跳过 {{skip}} / 冲突 {{conflict}}",
+  "install.manifest": "manifest：{{path}}",
+  "install.gitConfig": "已配置 git 门禁：core.hooksPath / merge.ours.driver / merge.jsonl-union.driver",
+  "install.gitSkip": "未配置 git（目标不是仓库或使用了 --no-git-config）；clone 后请手动执行三条例行配置",
+  "install.next": "下一步：node .agents/scripts/check-local-gates.mjs --fix",
+  "doctor.manifestMissing": "未找到 .agents/install-manifest.json；先运行 flow-kit install",
+  "doctor.fileMissing": "manifest 登记的文件缺失",
+  "doctor.unknownHost": "宿主模板不存在",
+  "doctor.ok": "doctor 全过（{{total}} 项）",
+  "doctor.fail": "doctor 失败：{{failed}}/{{total}} 项",
+  "error.noHosts": "未指定宿主。用 --agent <host> 指定，可选：{{hosts}}",
+  "error.unknownHost": "未知宿主：{{name}}。可选：{{hosts}}",
+  "error.noManifest": "目标未安装本引擎；先运行 install",
+  "error.noHostsInManifest": "manifest 未登记宿主；先运行 install",
+  "listHosts.title": "支持的宿主："
+}

package/package.json

@@ -1,50 +1,37 @@
 {
   "name": "agentic-flow-kit",
-  "version": "1.8.2",
-  "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完本地可跑、零运行时依赖",
+  "version": "2.0.0",
+  "description": "AI-Native workflow engine installer: generate .agents, git hooks, host adapters, wiki/workflow scaffolds from zero.",
+  "license": "UNLICENSED",
   "type": "module",
-  "scripts": {
-    "test": "node src/run-tests.mjs",
-    "lint": "eslint .",
-    "prepack": "node -e \"require('fs').rmSync('templates/_agents/cache',{recursive:true,force:true})\" && node scripts/check-pack-eol.mjs"
-  },
   "bin": {
     "flow-kit": "bin/flow-kit.mjs"
   },
-  "files": [
-    "bin",
-    "src",
-    "templates",
-    "modules",
-    "README.md",
-    "!templates/_agents/cache",
-    "!templates/_agents/cache/**"
-  ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22"
   },
   "keywords": [
     "ai-native",
     "workflow",
-    "agent",
-    "scaffold",
-    "cli",
-    "wiki",
-    "check-loop",
-    "closed-loop"
+    "agents",
+    "codex",
+    "claude-code",
+    "trae",
+    "codebuddy",
+    "installer"
   ],
-  "license": "MIT",
-  "private": false,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zerosloney/agentic-flow-kit.git"
-  },
-  "bugs": {
-    "url": "https://github.com/zerosloney/agentic-flow-kit/issues"
-  },
-  "homepage": "https://github.com/zerosloney/agentic-flow-kit#readme",
-  "devDependencies": {
-    "@eslint/js": "^9.39.5",
-    "eslint": "^9.39.4"
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "locales",
+    "schemas",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "extract": "node tools/extract-from-project.mjs",
+    "doctor:self": "node bin/flow-kit.mjs doctor --target .",
+    "prepublishOnly": "node --test tests/*.test.mjs"
   }
 }

package/schemas/install-manifest.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentic-flow-kit/install-manifest.schema.json",
+  "title": "agentic-flow-kit install manifest",
+  "type": "object",
+  "required": ["kit", "version", "language", "hosts", "stack", "files"],
+  "properties": {
+    "kit": { "const": "agentic-flow-kit" },
+    "version": { "type": "string" },
+    "installedAt": { "type": "string", "format": "date-time" },
+    "language": { "enum": ["zh-CN", "en"] },
+    "hosts": {
+      "type": "array",
+      "items": { "enum": ["trae", "codebuddy", "claude", "opencode", "qwen", "pi", "cline", "commandcode", "qoder", "zcode"] },
+      "uniqueItems": true
+    },
+    "stack": { "enum": ["dotnet", "node", "empty"] },
+    "files": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/project-profile.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentic-flow-kit/project-profile.schema.json",
+  "title": "agentic-flow-kit project profile",
+  "type": "object",
+  "required": ["stack"],
+  "properties": {
+    "stack": { "enum": ["dotnet", "node", "empty"] },
+    "ports": {
+      "type": "object",
+      "properties": {
+        "api": { "type": "integer", "minimum": 1, "maximum": 65535 },
+        "web": { "type": "integer", "minimum": 1, "maximum": 65535 },
+        "board": { "type": "integer", "minimum": 1, "maximum": 65535 }
+      },
+      "additionalProperties": false
+    },
+    "paths": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "commands": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/src/cli/args.mjs

@@ -0,0 +1,41 @@
+// 极简参数解析：--key value / --flag / --key=value；--agent 可重复。
+export function parseArgs(argv) {
+  const args = { _: [], agents: [], flags: new Set() };
+  const takeValue = (i) => {
+    const next = argv[i + 1];
+    if (next == null || (next.startsWith('--') && next !== '-')) return null;
+    return next;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (!raw.startsWith('--')) {
+      args._.push(raw);
+      continue;
+    }
+    const eq = raw.indexOf('=');
+    if (eq >= 0) {
+      const key = raw.slice(2, eq);
+      const value = raw.slice(eq + 1);
+      if (key === 'agent') args.agents.push(value);
+      else args[key] = value;
+      continue;
+    }
+    const key = raw.slice(2);
+    const value = takeValue(i);
+    if (value != null) {
+      if (key === 'agent') args.agents.push(value);
+      else args[key] = value;
+      i += 1;
+    } else {
+      args.flags.add(key);
+    }
+  }
+  // --agents a,b,c
+  if (typeof args.agents === 'string') args.agents = args.agents.split(',');
+  args.agents = args.agents.flatMap((a) => String(a).split(',')).map((a) => a.trim()).filter(Boolean);
+  return args;
+}
+
+export function flag(args, name) {
+  return args.flags.has(name) || args[name] === true || args[name] === 'true';
+}

package/src/cli/main.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs, flag } from './args.mjs';
+import { makeT } from '../i18n.mjs';
+import { HOST_NAMES, resolveHost } from '../hosts/registry.mjs';
+import { installCommand } from '../commands/install.mjs';
+import { doctorCommand } from '../commands/doctor.mjs';
+import { addHostCommand } from '../commands/add-host.mjs';
+import { upgradeCommand } from '../commands/upgrade.mjs';
+import { KIT_ROOT } from '../install/plan.mjs';
+
+const SUPPORTED_LANGS = new Set(['zh-CN', 'en']);
+
+function normalizeLang(input) {
+  const lang = String(input || 'zh-CN');
+  if (!SUPPORTED_LANGS.has(lang)) {
+    const err = new Error(`unsupported language: ${lang}`);
+    err.code = 'BAD_LANG';
+    throw err;
+  }
+  return lang;
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  const command = args._[0] || (args.help || args.h ? 'help' : 'help');
+  const lang = normalizeLang(args.lang);
+  const t = makeT(lang);
+
+  if (flag(args, 'version') || flag(args, 'v')) {
+    console.log(readVersion());
+    return 0;
+  }
+  if ((flag(args, 'help') || flag(args, 'h')) && command !== 'help') {
+    console.log(t('help', { version: readVersion() }));
+    return 0;
+  }
+
+  switch (command) {
+    case 'install':
+      return installCommand({ args, t, lang });
+    case 'add-host':
+      return addHostCommand({ args, t, lang });
+    case 'upgrade':
+      return upgradeCommand({ args, t, lang });
+    case 'doctor':
+      return doctorCommand({ args, t, lang });
+    case 'list-hosts':
+      for (const name of HOST_NAMES) {
+        const h = resolveHost(name);
+        console.log(`${name}\t${h.label}\t${h.dir}${h.tracked ? '\ttracked' : ''}`);
+      }
+      return 0;
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(t('help', { version: readVersion() }));
+      return 0;
+    default:
+      throw new Error(`unknown command: ${command}`);
+  }
+}
+
+function readVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(KIT_ROOT, 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+export { main, normalizeLang, SUPPORTED_LANGS, flag };

package/src/commands/add-host.mjs

@@ -0,0 +1,29 @@
+import { readManifest } from '../install/manifest.mjs';
+import { makeT } from '../i18n.mjs';
+import { resolveTarget, runInstall, resolveHosts } from './install.mjs';
+
+export function addHostCommand({ args, t, lang }) {
+  const target = resolveTarget(args);
+  const manifest = readManifest(target);
+  if (!manifest) {
+    const err = new Error(t('error.noManifest'));
+    err.code = 'NO_MANIFEST';
+    throw err;
+  }
+  // add-host 支持 `add-host claude` 位置参数，也兼容 `--agent claude`。
+  const positional = args._.slice(1);
+  const hostArgs = { ...args, agents: args.agents.length ? args.agents : positional };
+  const newHosts = resolveHosts(hostArgs, t);
+  const currentLang = args.lang || manifest.language || lang;
+  const tt = makeT(currentLang);
+  return runInstall({
+    args: { ...hostArgs, target },
+    t: tt,
+    lang: currentLang,
+    hosts: newHosts,
+    planHosts: newHosts,
+    categories: ['host'],
+    commandLabel: 'add-host',
+    stackOverride: manifest.stack,
+  });
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readManifest } from '../install/manifest.mjs';
+import { doctorGit } from '../git/config.mjs';
+import { HOSTS } from '../hosts/registry.mjs';
+import { listFiles, TEMPLATES } from '../install/plan.mjs';
+import { resolveTarget } from './install.mjs';
+
+const HOOK_FILES = ['pre-commit', 'commit-msg', 'post-commit', 'pre-merge-commit', 'pre-push'];
+
+export function doctorCommand({ args, t }) {
+  const target = resolveTarget(args);
+  const checks = [];
+  const add = (ok, name, detail, fix) => checks.push({ ok, name, detail, fix });
+
+  const manifest = readManifest(target);
+  if (!manifest) {
+    add(false, 'install-manifest', t('doctor.manifestMissing'));
+  } else {
+    add(true, 'install-manifest', `.agents/install-manifest.json (v${manifest.version || '?'})`);
+    for (const rel of Object.keys(manifest.files || {})) {
+      if (!fs.existsSync(path.join(target, rel))) add(false, `file ${rel}`, t('doctor.fileMissing'));
+    }
+  }
+
+  checks.push(...doctorGit(target));
+
+  const attrPath = path.join(target, '.gitattributes');
+  let attr = '';
+  try {
+    attr = fs.readFileSync(attrPath, 'utf8');
+  } catch {
+    /* missing handled below */
+  }
+  add(/merge=jsonl-union/.test(attr), '.gitattributes jsonl-union', attr ? '' : t('doctor.fileMissing'));
+  add(/merge=ours/.test(attr), '.gitattributes ours', attr ? '' : t('doctor.fileMissing'));
+
+  for (const hook of HOOK_FILES) {
+    add(fs.existsSync(path.join(target, '.githooks', hook)), `hook ${hook}`, '');
+  }
+
+  for (const host of manifest?.hosts || []) {
+    const h = HOSTS[host];
+    if (!h) {
+      add(false, `host ${host}`, t('doctor.unknownHost'));
+      continue;
+    }
+    for (const rel of listFiles(path.join(TEMPLATES, 'hosts', host))) {
+      const targetRel = host === 'claude' && rel === 'CLAUDE.md' ? 'CLAUDE.md' : `${h.dir}/${rel}`;
+      if (!fs.existsSync(path.join(target, targetRel))) add(false, `host ${host}: ${targetRel}`, t('doctor.fileMissing'));
+    }
+  }
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  add(nodeMajor >= 22, 'node >= 22', process.version);
+
+  let failed = 0;
+  for (const c of checks) {
+    if (c.ok) {
+      console.log(`✓ ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+    } else {
+      failed += 1;
+      console.log(`✗ ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+      if (c.fix) console.log(`  → ${c.fix}`);
+    }
+  }
+  console.log(failed ? t('doctor.fail', { failed, total: checks.length }) : t('doctor.ok', { total: checks.length }));
+
+  if (args.deep) {
+    const gates = path.join(target, '.agents/scripts/check-local-gates.mjs');
+    if (fs.existsSync(gates)) {
+      console.log(`\n$ node ${gates}`);
+      const r = spawnSync(process.execPath, [gates, ...(args.fix ? ['--fix'] : [])], { cwd: target, stdio: 'inherit' });
+      if (r.status !== 0) failed += 1;
+    }
+  }
+
+  return failed ? 1 : 0;
+}

package/src/commands/install.mjs

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { flag } from '../cli/args.mjs';
+import { buildPlan } from '../install/plan.mjs';
+import { applyPlan, summaryLine } from '../install/apply.mjs';
+import { emptyManifest, readManifest, writeManifest } from '../install/manifest.mjs';
+import { buildVars } from '../render/tokens.mjs';
+import { HOST_NAMES, resolveHost } from '../hosts/registry.mjs';
+import { configureGit, isGitRepo } from '../git/config.mjs';
+
+export function readKitVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+const KIT_VERSION = readKitVersion();
+
+export function resolveTarget(args) {
+  const target = path.resolve(args.target || process.cwd());
+  if (!fs.existsSync(target)) {
+    const err = new Error(`target not found: ${target}`);
+    err.code = 'TARGET_MISSING';
+    throw err;
+  }
+  return target;
+}
+
+export function resolveHosts(args, t, fallback = []) {
+  const names = args.agents && args.agents.length ? args.agents : fallback;
+  if (!names.length) {
+    const err = new Error(t('error.noHosts', { hosts: HOST_NAMES.join(', ') }));
+    err.code = 'NO_HOSTS';
+    throw err;
+  }
+  const out = [];
+  for (const name of names) {
+    try {
+      resolveHost(name);
+    } catch {
+      const err = new Error(t('error.unknownHost', { name, hosts: HOST_NAMES.join(', ') }));
+      err.code = 'UNKNOWN_HOST';
+      throw err;
+    }
+    const key = String(name).trim().toLowerCase();
+    if (!out.includes(key)) out.push(key);
+  }
+  return out;
+}
+
+export function detectStack(target) {
+  let top = [];
+  try {
+    top = fs.readdirSync(target);
+  } catch {
+    return 'empty';
+  }
+  if (top.some((n) => n.endsWith('.sln') || n.endsWith('.csproj'))) return 'dotnet';
+  if (top.includes('package.json')) return 'node';
+  return 'empty';
+}
+
+export function resolveStack(args, target) {
+  const stack = String(args.stack || args.profile || detectStack(target));
+  const abs = fileURLToPath(new URL(`../../templates/profiles/${stack}/`, import.meta.url));
+  return fs.existsSync(abs) ? stack : 'empty';
+}
+
+export function installCommand({ args, t, lang }) {
+  const hosts = resolveHosts(args, t);
+  return runInstall({ args, t, lang, hosts, commandLabel: 'install' });
+}
+
+export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories, commandLabel, stackOverride }) {
+  const target = resolveTarget(args);
+  const dryRun = flag(args, 'dry-run');
+  const force = flag(args, 'force');
+  const stack = stackOverride || resolveStack(args, target);
+  const projectName = args.name || path.basename(target);
+  const previous = readManifest(target);
+  const hostSet = [...new Set([...(previous?.hosts || []), ...hosts])];
+  const trackHosts = flag(args, 'track-hosts');
+
+  const plan = buildPlan({ target, hosts: planHosts, lang, stack, projectName, categories });
+  const vars = buildVars({
+    target,
+    projectName,
+    stack,
+    language: lang,
+    hosts: hostSet,
+    kitVersion: KIT_VERSION,
+    installedAt: new Date().toISOString(),
+    trackHosts,
+  });
+
+  console.log(t('install.start', { command: commandLabel, target }));
+  console.log(t('install.plan', { hosts: hostSet.join(', '), stack, lang, count: plan.entries.length }));
+  if (dryRun) console.log(t('install.dryRun'));
+
+  const manifest = previous || emptyManifest({
+    kitVersion: KIT_VERSION,
+    language: lang,
+    hosts: hostSet,
+    stack,
+  });
+
+  const result = applyPlan({
+    plan,
+    vars,
+    manifest,
+    dryRun,
+    force,
+    log: (action, msg) => {
+      const prefix = { create: '+', update: '~', skip: '-', conflict: '!', merge: '~' }[action] || ' ';
+      console.log(`${prefix} ${msg}`);
+    },
+  });
+
+  console.log(summaryLine(result.stats, t));
+
+  if (!dryRun) {
+    const next = {
+      ...manifest,
+      version: KIT_VERSION,
+      installedAt: new Date().toISOString(),
+      language: lang,
+      hosts: hostSet,
+      stack,
+      files: result.files,
+    };
+    writeManifest(target, next);
+    console.log(t('install.manifest', { path: path.join(target, '.agents/install-manifest.json') }));
+
+    const gitConfig = flag(args, 'git-config') || (!flag(args, 'no-git-config') && isGitRepo(target));
+    if (gitConfig && isGitRepo(target)) {
+      configureGit(target);
+      console.log(t('install.gitConfig'));
+    } else if (!gitConfig) {
+      console.log(t('install.gitSkip'));
+    }
+    console.log(t('install.next'));
+  }
+
+  return result.stats.conflict > 0 ? 0 : 0;
+}

package/src/commands/upgrade.mjs

@@ -0,0 +1,30 @@
+import { readManifest } from '../install/manifest.mjs';
+import { makeT } from '../i18n.mjs';
+import { resolveTarget, runInstall } from './install.mjs';
+
+export function upgradeCommand({ args, t, lang }) {
+  const target = resolveTarget(args);
+  const manifest = readManifest(target);
+  if (!manifest) {
+    const err = new Error(t('error.noManifest'));
+    err.code = 'NO_MANIFEST';
+    throw err;
+  }
+  const currentLang = args.lang || manifest.language || lang;
+  const tt = makeT(currentLang);
+  const hosts = manifest.hosts || [];
+  if (!hosts.length) {
+    const err = new Error(t('error.noHostsInManifest'));
+    err.code = 'NO_HOSTS_IN_MANIFEST';
+    throw err;
+  }
+  return runInstall({
+    args: { ...args, target },
+    t: tt,
+    lang: currentLang,
+    hosts,
+    planHosts: hosts,
+    commandLabel: 'upgrade',
+    stackOverride: args.stack || args.profile || manifest.stack,
+  });
+}