@buaa_smat/hometrans 0.1.11 → 0.1.13

package/dist/cli/init.js

@@ -7,14 +7,14 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import figlet from 'figlet';
 import inquirer from 'inquirer';
 import { parseTree, modify, applyEdits } from 'jsonc-parser';
 import { setupMcpForAllEditors } from './mcp-setup.js';
-import { deriveSdkPaths, expandHome, getConfigPath, getToolsDir, loadHomeTransConfig, saveHomeTransConfig, } from './config-store.js';
+import { deriveSdkPaths, expandHome, getConfigDir, getConfigPath, getToolsDir, loadHomeTransConfig, saveHomeTransConfig, } from './config-store.js';
 function ensureChalkColor() {
     if (process.stdout.isTTY && chalk.level === 0) {
         chalk.level = 1;
@@ -90,6 +90,55 @@ async function installTools(toolsRoot, config) {
 function resolveAutotestDir(toolPath) {
     return path.join(toolPath, 'test-tools', 'autotest');
 }
+async function readFileIfExists(p) {
+    try {
+        return await fs.readFile(p, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Template drift check; line-ending differences alone don't count. */
+export function templatesDiffer(a, b) {
+    if (a === null || b === null)
+        return false;
+    const norm = (s) => s.replace(/\r\n/g, '\n');
+    return norm(a) !== norm(b);
+}
+/** e.g. 20260610-153012 — used to name config backups. */
+function timestampSuffix() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    return (`${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}` +
+        `-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`);
+}
+/**
+ * The bundled template changed since the local config was created — ask
+ * whether to regenerate. Y = back up the current file with a timestamp and
+ * recreate from the new template; N (default, and the non-interactive
+ * fallback) = keep the current file and only refresh the keys in place.
+ * Ctrl-C aborts init.
+ */
+async function confirmRegenerateFromTemplate(label) {
+    console.log(chalk.yellow(`  ! ${label}: the bundled template changed since this file was created.`));
+    try {
+        const answers = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'regenerate',
+                message: `Regenerate ${label} from the new template? (Y = back up current file with a timestamp, then recreate; N = keep current file, only refresh keys)`,
+                default: false,
+            },
+        ]);
+        return answers.regenerate;
+    }
+    catch (err) {
+        if (isPromptAbort(err))
+            abortInit();
+        console.log(chalk.yellow('    Non-interactive: keeping current file (keys refreshed only).'));
+        return false;
+    }
+}
 /**
  * Initialize / refresh `agents/test-tools/autotest/config.yaml`:
  *   - If config.yaml does not exist, seed it from config.yaml.example.
@@ -98,7 +147,7 @@ function resolveAutotestDir(toolPath) {
  * Returns a status string for the result summary, or null if nothing was done
  * (e.g., the autotest folder isn't present in this package).
  */
-async function refreshAutotestConfig(autotestDir, apiKey) {
+async function refreshAutotestConfig(autotestDir, apiKey, prevExampleContent = null) {
     const examplePath = path.join(autotestDir, 'config.yaml.example');
     const configPath = path.join(autotestDir, 'config.yaml');
     const hasExample = await fs
@@ -108,6 +157,8 @@ async function refreshAutotestConfig(autotestDir, apiKey) {
     if (!hasExample)
         return null;
     let seeded = false;
+    let backupName = null;
+    let templateBackupName = null;
     const hasConfig = await fs
         .access(configPath)
         .then(() => true)
@@ -116,7 +167,33 @@ async function refreshAutotestConfig(autotestDir, apiKey) {
         await fs.copyFile(examplePath, configPath);
         seeded = true;
     }
+    else {
+        // Template drift: the bundled example changed since the local config was
+        // created (prevExampleContent = local example snapshot taken before the
+        // tools copy). Y regenerates from the new template after a timestamped
+        // backup; N keeps the local file (key-only refresh below) — but saves the
+        // old template alongside, since the new one just overwrote it on disk
+        // and the local config is still based on the old one.
+        const newExample = await fs.readFile(examplePath, 'utf-8');
+        if (templatesDiffer(prevExampleContent, newExample)) {
+            if (await confirmRegenerateFromTemplate('autotest config.yaml')) {
+                backupName = `config.yaml.${timestampSuffix()}.bak`;
+                await fs.copyFile(configPath, path.join(autotestDir, backupName));
+                await fs.copyFile(examplePath, configPath);
+            }
+            else {
+                templateBackupName = `config.yaml.example.${timestampSuffix()}.bak`;
+                await fs.writeFile(path.join(autotestDir, templateBackupName), prevExampleContent, 'utf-8');
+            }
+        }
+    }
     if (!apiKey) {
+        if (backupName) {
+            return `autotest config.yaml regenerated from new template (backup: ${backupName}; api_key left as placeholder)`;
+        }
+        if (templateBackupName) {
+            return `autotest config.yaml kept (old template backed up: ${templateBackupName})`;
+        }
         return seeded
             ? `autotest config.yaml seeded (api_key left as placeholder)`
             : null;
@@ -127,6 +204,12 @@ async function refreshAutotestConfig(autotestDir, apiKey) {
     if (updated !== original) {
         await fs.writeFile(configPath, updated, 'utf-8');
     }
+    if (backupName) {
+        return `autotest config.yaml regenerated from new template + api_key filled (backup: ${backupName})`;
+    }
+    if (templateBackupName) {
+        return `autotest config.yaml api_key refreshed (kept local file; old template backed up: ${templateBackupName})`;
+    }
     return seeded
         ? `autotest config.yaml seeded + api_key filled`
         : `autotest config.yaml api_key refreshed`;
@@ -144,7 +227,7 @@ const UI_ALIGN_SKILL = 'hmos-incremental-ui-align';
  * Returns a status string for the result summary, or null if nothing was
  * done (skill not installed there, or no values to write into an existing file).
  */
-export async function refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir) {
+export async function refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir, prevExampleContent = null) {
     const skillDir = path.join(skillsDir, UI_ALIGN_SKILL);
     const examplePath = path.join(skillDir, 'config-example.json');
     const configPath = path.join(skillDir, 'config.json');
@@ -155,6 +238,8 @@ export async function refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir) {
     if (!hasExample)
         return null;
     let seeded = false;
+    let backupName = null;
+    let templateBackupName = null;
     const hasConfig = await fs
         .access(configPath)
         .then(() => true)
@@ -163,12 +248,38 @@ export async function refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir) {
         await fs.copyFile(examplePath, configPath);
         seeded = true;
     }
+    else {
+        // Template drift: bundled config-example.json changed since the local
+        // config.json was created (prevExampleContent = snapshot taken before the
+        // skills copy). Y regenerates from the new template after a timestamped
+        // backup; N keeps the local file (key-only update below) — but saves the
+        // old template alongside, since the new one just overwrote it on disk
+        // and the local config is still based on the old one.
+        const newExample = await fs.readFile(examplePath, 'utf-8');
+        if (templatesDiffer(prevExampleContent, newExample)) {
+            if (await confirmRegenerateFromTemplate(`${UI_ALIGN_SKILL}/config.json`)) {
+                backupName = `config.json.${timestampSuffix()}.bak`;
+                await fs.copyFile(configPath, path.join(skillDir, backupName));
+                await fs.copyFile(examplePath, configPath);
+            }
+            else {
+                templateBackupName = `config-example.json.${timestampSuffix()}.bak`;
+                await fs.writeFile(path.join(skillDir, templateBackupName), prevExampleContent, 'utf-8');
+            }
+        }
+    }
     const updates = [];
     if (glmApiKey)
         updates.push(['glm_api_key', glmApiKey]);
     if (hmosSdkDir)
         updates.push(['hmos_sdk_dir', hmosSdkDir]);
     if (updates.length === 0) {
+        if (backupName) {
+            return `${UI_ALIGN_SKILL}/config.json regenerated from new template (backup: ${backupName}; glm_api_key / hmos_sdk_dir left empty)`;
+        }
+        if (templateBackupName) {
+            return `${UI_ALIGN_SKILL}/config.json kept (old template backed up: ${templateBackupName})`;
+        }
         return seeded
             ? `${UI_ALIGN_SKILL}/config.json seeded (glm_api_key / hmos_sdk_dir left empty)`
             : null;
@@ -191,11 +302,17 @@ export async function refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir) {
         await fs.writeFile(configPath, raw, 'utf-8');
     }
     const what = updates.map(([k]) => k).join(' + ');
+    if (backupName) {
+        return `${UI_ALIGN_SKILL}/config.json regenerated from new template + ${what} filled (backup: ${backupName})`;
+    }
+    if (templateBackupName) {
+        return `${UI_ALIGN_SKILL}/config.json ${what} refreshed (kept local file; old template backed up: ${templateBackupName})`;
+    }
     return seeded
         ? `${UI_ALIGN_SKILL}/config.json seeded + ${what} filled`
         : `${UI_ALIGN_SKILL}/config.json ${what} refreshed`;
 }
-async function installSkillsTo(skillsRoot, targetDir) {
+async function installSkillsTo(skillsRoot, targetDir, skipNames = new Set()) {
     let entries;
     try {
         entries = await fs.readdir(skillsRoot, { withFileTypes: true });
@@ -207,6 +324,8 @@ async function installSkillsTo(skillsRoot, targetDir) {
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
+        if (skipNames.has(entry.name))
+            continue;
         const skillSrc = path.join(skillsRoot, entry.name);
         const hasSkillFile = await fs
             .access(path.join(skillSrc, 'SKILL.md'))
@@ -220,7 +339,7 @@ async function installSkillsTo(skillsRoot, targetDir) {
     }
     return installed;
 }
-async function installAgentsTo(agentsRoot, targetDir) {
+async function installAgentsTo(agentsRoot, targetDir, skipNames = new Set()) {
     let entries;
     try {
         entries = await fs.readdir(agentsRoot, { withFileTypes: true });
@@ -231,6 +350,8 @@ async function installAgentsTo(agentsRoot, targetDir) {
     await fs.mkdir(targetDir, { recursive: true });
     const installed = [];
     for (const entry of entries) {
+        if (skipNames.has(entry.name))
+            continue;
         const srcPath = path.join(agentsRoot, entry.name);
         const destPath = path.join(targetDir, entry.name);
         if (entry.isDirectory()) {
@@ -245,6 +366,78 @@ async function installAgentsTo(agentsRoot, targetDir) {
     }
     return installed;
 }
+/** Names of bundled skill folders (those containing a SKILL.md). */
+async function listBundledSkillNames(skillsRoot) {
+    try {
+        const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+        const names = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const hasSkillFile = await fs
+                .access(path.join(skillsRoot, entry.name, 'SKILL.md'))
+                .then(() => true)
+                .catch(() => false);
+            if (hasSkillFile)
+                names.push(entry.name);
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/** Top-level names (files and folders) under the bundled agents dir. */
+async function listBundledAgentNames(agentsRoot) {
+    try {
+        const entries = await fs.readdir(agentsRoot, { withFileTypes: true });
+        return entries.map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ask whether same-name skills/agents already present in the editor's target
+ * dirs may be overwritten. Returns true (overwrite) when the user confirms or
+ * the shell is non-interactive (legacy behavior); false keeps existing files —
+ * the caller then only refreshes the API-key config files. Ctrl-C aborts init.
+ */
+async function confirmOverwrite(editorName, skillConflicts, agentConflicts) {
+    console.log(chalk.yellow(`  ! ${editorName}: the following already exist and would be overwritten:`));
+    if (skillConflicts.length > 0) {
+        console.log(chalk.yellow(`      skills: ${skillConflicts.join(', ')}`));
+    }
+    if (agentConflicts.length > 0) {
+        console.log(chalk.yellow(`      agents: ${agentConflicts.join(', ')}`));
+    }
+    try {
+        const answers = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: `Overwrite them in ${editorName}? (N = keep existing files; new items are still installed and API-key configs refreshed)`,
+                default: true,
+            },
+        ]);
+        return answers.overwrite;
+    }
+    catch (err) {
+        if (isPromptAbort(err))
+            abortInit();
+        console.log(chalk.yellow('    Non-interactive: overwriting by default.'));
+        return true;
+    }
+}
 async function installForEditor(editor, skillsRoot, agentsRoot, glmApiKey, hmosSdkDir, result) {
     const marker = expandHome(editor.markerDir);
     if (marker && !(await dirExists(marker))) {
@@ -253,8 +446,30 @@ async function installForEditor(editor, skillsRoot, agentsRoot, glmApiKey, hmosS
     }
     const skillsDir = expandHome(editor.skillsDir);
     const agentsDir = expandHome(editor.agentsDir);
+    // Same-name items already in the editor's dirs → ask before overwriting.
+    const skillConflicts = [];
+    for (const name of await listBundledSkillNames(skillsRoot)) {
+        if (await pathExists(path.join(skillsDir, name)))
+            skillConflicts.push(name);
+    }
+    const agentConflicts = [];
+    for (const name of await listBundledAgentNames(agentsRoot)) {
+        if (await pathExists(path.join(agentsDir, name)))
+            agentConflicts.push(name);
+    }
+    let overwrite = true;
+    if (skillConflicts.length > 0 || agentConflicts.length > 0) {
+        overwrite = await confirmOverwrite(editor.name, skillConflicts, agentConflicts);
+    }
+    // Snapshot the installed ui-align template BEFORE the skills copy updates
+    // it — refreshUiAlignConfig uses it to detect template drift.
+    const prevUiAlignExample = await readFileIfExists(path.join(skillsDir, UI_ALIGN_SKILL, 'config-example.json'));
+    // N = incremental install: keep the conflicting items untouched, still copy
+    // everything that doesn't exist in the target dirs yet.
+    const skipSkills = overwrite ? new Set() : new Set(skillConflicts);
+    const skipAgents = overwrite ? new Set() : new Set(agentConflicts);
     try {
-        const skills = await installSkillsTo(skillsRoot, skillsDir);
+        const skills = await installSkillsTo(skillsRoot, skillsDir, skipSkills);
         if (skills.length > 0) {
             result.configured.push(`${editor.name} skills (${skills.length} -> ${prettyHome(skillsDir)})`);
         }
@@ -262,10 +477,14 @@ async function installForEditor(editor, skillsRoot, agentsRoot, glmApiKey, hmosS
     catch (err) {
         result.errors.push(`${editor.name} skills: ${err.message}`);
     }
+    if (!overwrite) {
+        result.skipped.push(`${editor.name} existing kept: ${skipSkills.size} skills, ${skipAgents.size} agents (new items installed, API-key configs refreshed)`);
+    }
     // Seed / refresh the incremental-ui-align per-skill config.json with the
-    // GLM key + SDK dir from ~/.hometrans/config.json (existing files: key-only update).
+    // GLM key + SDK dir from ~/.hometrans/config.json (existing files: key-only
+    // update). Runs regardless of the overwrite decision above.
     try {
-        const status = await refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir);
+        const status = await refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir, prevUiAlignExample);
         if (status) {
             result.configured.push(`${editor.name} ${status}`);
         }
@@ -274,7 +493,7 @@ async function installForEditor(editor, skillsRoot, agentsRoot, glmApiKey, hmosS
         result.errors.push(`${editor.name} ${UI_ALIGN_SKILL}/config.json: ${err.message}`);
     }
     try {
-        const agents = await installAgentsTo(agentsRoot, agentsDir);
+        const agents = await installAgentsTo(agentsRoot, agentsDir, skipAgents);
         if (agents.length > 0) {
             result.configured.push(`${editor.name} agents (${agents.length} -> ${prettyHome(agentsDir)})`);
         }
@@ -291,6 +510,51 @@ async function installForEditor(editor, skillsRoot, agentsRoot, glmApiKey, hmosS
 export function prettyHome(p) {
     return p;
 }
+/** Bundled at the package root, alongside skills/ and agents/. */
+function resolveEnvRequirementsPath() {
+    return path.resolve(__dirname, '..', '..', 'env-requirements.json');
+}
+/**
+ * Copy the bundled env-requirements.json into ~/.hometrans, alongside
+ * config.json, so it sits next to the user's config. Returns the destination
+ * path, or null if the package ships no env-requirements.json.
+ */
+async function installEnvRequirements() {
+    const src = resolveEnvRequirementsPath();
+    if (!(await fileExists(src)))
+        return null;
+    const dest = path.join(getConfigDir(), 'env-requirements.json');
+    await fs.mkdir(getConfigDir(), { recursive: true });
+    await fs.copyFile(src, dest);
+    return dest;
+}
+/**
+ * Load env-requirements.json. The leading `$`-prefixed keys are documentation
+ * and ignored. Returns null (with a warning) if the file is missing or invalid
+ * so `ht init` degrades gracefully instead of crashing.
+ */
+export async function loadEnvRequirements() {
+    const p = resolveEnvRequirementsPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch {
+        console.log(chalk.yellow(`  ! env-requirements.json not found at ${p} — skipping impact check.`));
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed.tools || !Array.isArray(parsed.requirements)) {
+            throw new Error('expected { tools: {...}, requirements: [...] }');
+        }
+        return parsed;
+    }
+    catch (err) {
+        console.log(chalk.yellow(`  ! env-requirements.json is invalid (${err.message}) — skipping impact check.`));
+        return null;
+    }
+}
 /** Locate a command on PATH (`where` on Windows, `which` elsewhere). */
 function whichSync(cmd) {
     const isWin = process.platform === 'win32';
@@ -307,18 +571,19 @@ function whichSync(cmd) {
         return null;
     }
 }
-function captureVersion(cmd, args) {
-    try {
-        const out = execFileSync(cmd, args, {
-            encoding: 'utf-8',
-            timeout: 5000,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        return out.split('\n')[0].trim() || null;
-    }
-    catch {
+/**
+ * Run a tool's verify command and return its first non-empty output line.
+ * Reads the configured stream first (stdout by default; stderr for `java
+ * -version`), falling back to the combined output if that stream is empty.
+ */
+function captureVerify(cmd, args, stream) {
+    const r = spawnSync(cmd, args, { encoding: 'utf-8', timeout: 5000 });
+    if (r.error)
         return null;
-    }
+    const primary = stream === 'stderr' ? r.stderr : r.stdout;
+    const text = primary && primary.trim() ? primary : `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+    const line = (text ?? '').split('\n').map((l) => l.trim()).filter(Boolean)[0];
+    return line || null;
 }
 async function fileExists(p) {
     try {
@@ -329,123 +594,197 @@ async function fileExists(p) {
         return false;
     }
 }
-/** Install hints shown when a tool is missing. */
-const TOOL_HINTS = {
-    deveco: 'set DEVECO_SDK_HOME via `ht init` (DevEco Studio install)',
-    adb: 'Android SDK platform-tools (needed for Android-device capture)',
-    hdc: 'ships with DevEco: <sdk>/default/openharmony/toolchains',
-    python: 'install Python >= 3.10 and add to PATH (UI-align capture/parse scripts)',
-    uv: 'https://docs.astral.sh/uv (AutoTest runs under uv)',
-    java: 'any JDK 17+, or reuse DevEco jbr: <deveco>/jbr/bin',
-    gitnexus: 'npm i -g gitnexus && gitnexus setup',
-};
+/** Parse the first dotted-number sequence into [major, minor, patch]. */
+export function parseVersion(s) {
+    const m = s.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!m)
+        return null;
+    return [Number(m[1] || 0), Number(m[2] || 0), Number(m[3] || 0)];
+}
+function cmpVersion(a, b) {
+    for (let i = 0; i < 3; i++) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Is `version` inside the [min, max) window? Unparseable versions or an absent
+ * range are treated as satisfied (we never block on what we can't measure).
+ */
+export function versionInRange(version, range) {
+    if (!range || (!range.min && !range.max))
+        return true;
+    const pv = parseVersion(version);
+    if (!pv)
+        return true;
+    if (range.min) {
+        const pm = parseVersion(range.min);
+        if (pm && cmpVersion(pv, pm) < 0)
+            return false;
+    }
+    if (range.max) {
+        const px = parseVersion(range.max);
+        if (px && cmpVersion(pv, px) >= 0)
+            return false;
+    }
+    return true;
+}
+/** Human-readable form of a range, e.g. ">= 3.10", "< 2.0", "[1.0, 2.0)". */
+function describeRange(range) {
+    if (!range)
+        return '';
+    if (range.min && range.max)
+        return `[${range.min}, ${range.max})`;
+    if (range.min)
+        return `>= ${range.min}`;
+    if (range.max)
+        return `< ${range.max}`;
+    return '';
+}
 /**
- * Detect external tools. `hdc` falls back to the DevEco toolchains dir and
- * `java` to DevEco's bundled jbr when not on PATH, mirroring how the
- * skills/agents themselves resolve them.
+ * Detect every tool declared in env-requirements.json. `source: 'env-dir'`
+ * tools are a directory check; `source: 'path'` tools are located by trying
+ * each alias on PATH, then the optional DevEco fallback path. When a `verify`
+ * command is present we also capture and parse the tool's version.
  */
-async function detectEnvironment(env) {
+async function detectEnvironment(spec, env) {
     const status = new Map();
     const isWin = process.platform === 'win32';
-    const sdkOk = env.DEVECO_SDK_HOME ? await dirExists(env.DEVECO_SDK_HOME) : false;
-    status.set('deveco', {
-        found: sdkOk,
-        path: sdkOk ? env.DEVECO_SDK_HOME : undefined,
-    });
-    for (const cmd of ['adb', 'python', 'uv', 'gitnexus']) {
-        const p = whichSync(cmd);
-        const st = { found: !!p, path: p ?? undefined };
-        if (cmd === 'python' && p) {
-            const v = captureVersion('python', ['--version']);
-            if (v) {
-                st.note = v;
-                const m = v.match(/(\d+)\.(\d+)/);
-                if (m && (Number(m[1]) < 3 || (Number(m[1]) === 3 && Number(m[2]) < 10))) {
-                    st.note += '  (UI-align scripts require >= 3.10)';
+    const baseDir = (key) => key === 'DEVECO_SDK_HOME'
+        ? env.DEVECO_SDK_HOME
+        : key === 'DEVECO_PATH'
+            ? env.DEVECO_PATH
+            : '';
+    for (const [id, tool] of Object.entries(spec.tools)) {
+        if (tool.source === 'env-dir') {
+            const dir = tool.envVar ? baseDir(tool.envVar) : '';
+            const ok = dir ? await dirExists(dir) : false;
+            status.set(id, { found: ok, path: ok ? dir : undefined });
+            continue;
+        }
+        // source 'path': try each alias on PATH, then the fallback path.
+        const aliases = tool.aliases?.length ? tool.aliases : [id];
+        let resolvedPath = null;
+        let cmdToRun = null;
+        for (const alias of aliases) {
+            const p = whichSync(alias);
+            if (p) {
+                resolvedPath = p;
+                cmdToRun = alias;
+                break;
+            }
+        }
+        let viaFallback = false;
+        if (!resolvedPath && tool.fallback) {
+            const base = baseDir(tool.fallback.base);
+            if (base) {
+                const exe = isWin ? `${tool.fallback.exe}.exe` : tool.fallback.exe;
+                const cand = path.join(base, ...tool.fallback.segments, exe);
+                if (await fileExists(cand)) {
+                    resolvedPath = cand;
+                    cmdToRun = cand;
+                    viaFallback = true;
                 }
             }
         }
-        status.set(cmd, st);
-    }
-    // hdc: PATH first, then DevEco toolchains.
-    let hdcPath = whichSync('hdc');
-    if (!hdcPath && sdkOk) {
-        const cand = path.join(env.DEVECO_SDK_HOME, 'default', 'openharmony', 'toolchains', isWin ? 'hdc.exe' : 'hdc');
-        if (await fileExists(cand))
-            hdcPath = cand;
-    }
-    status.set('hdc', { found: !!hdcPath, path: hdcPath ?? undefined });
-    // java: PATH first, then DevEco jbr.
-    let javaPath = whichSync('java');
-    let javaNote;
-    if (!javaPath && env.DEVECO_PATH) {
-        const cand = path.join(env.DEVECO_PATH, 'jbr', 'bin', isWin ? 'java.exe' : 'java');
-        if (await fileExists(cand)) {
-            javaPath = cand;
-            javaNote = 'via DevEco jbr';
+        const st = { found: !!resolvedPath, path: resolvedPath ?? undefined };
+        if (resolvedPath && cmdToRun && tool.verify) {
+            const raw = captureVerify(cmdToRun, tool.verify, tool.versionStream === 'stderr' ? 'stderr' : 'stdout');
+            if (raw) {
+                st.note = viaFallback ? `${raw}  (via ${tool.fallback.base} fallback)` : raw;
+                if (tool.versionRegex) {
+                    const m = raw.match(new RegExp(tool.versionRegex));
+                    if (m && m[1])
+                        st.version = m[1];
+                }
+            }
+            else if (viaFallback) {
+                st.note = `via ${tool.fallback.base} fallback`;
+            }
+        }
+        else if (viaFallback) {
+            st.note = `via ${tool.fallback.base} fallback`;
         }
+        status.set(id, st);
     }
-    status.set('java', { found: !!javaPath, path: javaPath ?? undefined, note: javaNote });
     return status;
 }
 /**
- * Which tools each skill/agent needs. `required` missing → BLOCKED;
- * only `optional` missing → LIMITED. Kept in sync with the README
- * "Per-skill environment requirements" matrix.
+ * A dependency is satisfied when its tool is present AND its detected version
+ * (if known) falls in the required range (dependency range overrides the tool
+ * default). Returns the reason token shown in the impact table when not.
  */
-const IMPACT_MATRIX = [
-    { name: 'hmos-spec-generate', kind: 'skill', required: ['gitnexus'], optional: [] },
-    { name: 'hmos-resources-convert', kind: 'skill', required: [], optional: ['java'], note: 'no java -> falls back to source res/' },
-    { name: 'hmos-batch-ui-align', kind: 'skill', required: ['python'], optional: ['adb'], note: 'adb only for page exploration' },
-    { name: 'hmos-incremental-ui-align', kind: 'skill', required: ['deveco', 'python', 'hdc', 'adb'], optional: [] },
-    { name: 'hmos-integration-test', kind: 'skill', required: ['deveco', 'uv', 'hdc'], optional: [] },
-    { name: 'hmos-fix-build-errors', kind: 'skill', required: ['deveco'], optional: [] },
-    { name: 'hmos-convert-pipeline', kind: 'skill', required: ['deveco'], optional: ['uv', 'hdc'], note: 'test stage skippable via skip-test' },
-    { name: 'logic-context-builder', kind: 'agent', required: [], optional: ['python'] },
-    { name: 'logic-coder', kind: 'agent', required: [], optional: ['python'] },
-    { name: 'spec-generator', kind: 'agent', required: ['gitnexus'], optional: [] },
-    { name: 'build-fixer', kind: 'agent', required: ['deveco'], optional: [] },
-    { name: 'code-reviewer', kind: 'agent', required: [], optional: ['deveco'] },
-    { name: 'review-fixer', kind: 'agent', required: [], optional: [] },
-    { name: 'self-tester', kind: 'agent', required: ['uv', 'hdc'], optional: [] },
-    { name: 'self-test-fixer', kind: 'agent', required: [], optional: [] },
-];
+function evaluateDependency(dep, spec, tools) {
+    const st = tools.get(dep.tool);
+    const range = dep.version ?? spec.tools[dep.tool]?.version ?? null;
+    if (!st || !st.found) {
+        return { satisfied: false, reason: dep.tool };
+    }
+    if (st.version && !versionInRange(st.version, range)) {
+        return {
+            satisfied: false,
+            reason: `${dep.tool} ${st.version} (need ${describeRange(range)})`,
+        };
+    }
+    return { satisfied: true, reason: '' };
+}
 /** Print detected tools + the per-skill/agent impact table. */
 export async function runEnvironmentCheck(env) {
     console.log('');
     console.log(chalk.blue('  Environment Check'));
-    const tools = await detectEnvironment(env);
-    const order = ['deveco', 'adb', 'hdc', 'python', 'uv', 'java', 'gitnexus'];
+    const spec = await loadEnvRequirements();
+    if (!spec)
+        return;
+    const tools = await detectEnvironment(spec, env);
+    const order = Object.keys(spec.tools);
     for (const name of order) {
         const st = tools.get(name);
+        const tool = spec.tools[name];
         if (st.found) {
-            const note = st.note ? chalk.gray(`  (${st.note})`) : '';
-            console.log(`    ${chalk.green('+')} ${name.padEnd(9)} ${st.path ?? ''}${note}`);
+            let note = st.note ?? '';
+            if (st.version && tool.version && !versionInRange(st.version, tool.version)) {
+                note += `  (requires ${describeRange(tool.version)})`;
+            }
+            const noteStr = note ? chalk.gray(`  (${note})`) : '';
+            console.log(`    ${chalk.green('+')} ${name.padEnd(9)} ${st.path ?? ''}${noteStr}`);
         }
         else {
-            console.log(`    ${chalk.yellow('!')} ${name.padEnd(9)} ${chalk.yellow('not found')}  ${chalk.gray(TOOL_HINTS[name] ?? '')}`);
+            console.log(`    ${chalk.yellow('!')} ${name.padEnd(9)} ${chalk.yellow('not found')}  ${chalk.gray(tool.hint ?? '')}`);
         }
     }
-    const missing = order.filter((n) => !tools.get(n).found);
     console.log('');
     console.log(chalk.blue('  Impact on skills/agents:'));
     const nameW = 28;
     console.log(chalk.gray(`    ${'Name'.padEnd(nameW)} ${'Kind'.padEnd(6)} ${'Status'.padEnd(8)} Missing`));
-    for (const row of IMPACT_MATRIX) {
-        const missReq = row.required.filter((t) => missing.includes(t));
-        const missOpt = row.optional.filter((t) => missing.includes(t));
+    let allOk = true;
+    for (const row of spec.requirements) {
+        const unmetReq = [];
+        const unmetOpt = [];
+        for (const dep of row.dependencies) {
+            const { satisfied, reason } = evaluateDependency(dep, spec, tools);
+            if (satisfied)
+                continue;
+            if (dep.level === 'required')
+                unmetReq.push(reason);
+            else
+                unmetOpt.push(`${reason}(optional)`);
+        }
         let plain;
         let color;
         let parts;
-        if (missReq.length > 0) {
+        if (unmetReq.length > 0) {
             plain = 'BLOCKED';
             color = chalk.red;
-            parts = [...missReq, ...missOpt.map((t) => `${t}(optional)`)];
+            parts = [...unmetReq, ...unmetOpt];
+            allOk = false;
         }
-        else if (missOpt.length > 0) {
+        else if (unmetOpt.length > 0) {
             plain = 'LIMITED';
             color = chalk.yellow;
-            parts = missOpt.map((t) => `${t}(optional)`);
+            parts = unmetOpt;
+            allOk = false;
         }
         else {
             plain = 'OK';
@@ -456,7 +795,7 @@ export async function runEnvironmentCheck(env) {
         console.log(`    ${row.name.padEnd(nameW)} ${row.kind.padEnd(6)} ${color(plain.padEnd(8))} ${parts.join(', ')}${noteStr}`);
     }
     console.log('');
-    if (missing.length === 0) {
+    if (allOk) {
         console.log(chalk.green('  All environment dependencies found — every skill/agent is fully usable.'));
     }
     else {
@@ -624,6 +963,10 @@ export async function initCommand(options = {}) {
     catch (err) {
         console.log(chalk.yellow(`  ! environment check skipped: ${err.message}`));
     }
+    // Snapshot the currently installed autotest template BEFORE the tools copy
+    // overwrites it — refreshAutotestConfig compares it with the new template
+    // to detect drift and offer a config.yaml regeneration.
+    const prevAutotestExample = await readFileIfExists(path.join(resolveAutotestDir(config.env.TOOL_PATH || getToolsDir()), 'config.yaml.example'));
     // Copy bundled tools/ into ~/.hometrans/tools and record env.TOOL_PATH.
     // Must run before the autotest config step below, which seeds config.yaml
     // into the installed tools dir (the location agents read via env.TOOL_PATH).
@@ -638,13 +981,24 @@ export async function initCommand(options = {}) {
     catch (err) {
         console.log(chalk.red(`  ! tools copy: ${err.message}`));
     }
+    // Copy env-requirements.json into ~/.hometrans, next to config.json, so the
+    // declared environment requirements live alongside the user's config.
+    try {
+        const envReqDest = await installEnvRequirements();
+        if (envReqDest) {
+            console.log(chalk.green(`  + env-requirements.json copied -> ${prettyHome(envReqDest)}`));
+        }
+    }
+    catch (err) {
+        console.log(chalk.red(`  ! env-requirements.json copy: ${err.message}`));
+    }
     // Initialize / refresh autotest config.yaml from the example template,
     // inside the installed tools dir (<TOOL_PATH>/test-tools/autotest).
     try {
         const toolPath = installedToolPath ?? config.env.TOOL_PATH;
         if (toolPath) {
             const autotestDir = resolveAutotestDir(toolPath);
-            const status = await refreshAutotestConfig(autotestDir, config.env.TEST_API_KEY);
+            const status = await refreshAutotestConfig(autotestDir, config.env.TEST_API_KEY, prevAutotestExample);
             if (status) {
                 console.log(chalk.green(`  + ${status}`));
                 console.log(chalk.gray(`    ${path.join(autotestDir, 'config.yaml')}`));