@buaa_smat/hometrans 0.1.10 → 0.1.12

package/dist/cli/init.js

@@ -7,13 +7,14 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import os from 'node:os';
+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 { 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;
@@ -89,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.
@@ -97,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
@@ -107,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)
@@ -115,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;
@@ -126,11 +204,115 @@ 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`;
 }
-async function installSkillsTo(skillsRoot, targetDir) {
+const UI_ALIGN_SKILL = 'hmos-incremental-ui-align';
+/**
+ * Initialize / refresh `<skillsDir>/hmos-incremental-ui-align/config.json`
+ * in an editor's installed skills dir — same semantics as the autotest
+ * config.yaml handling:
+ *   - If config.json does not exist, seed it from config-example.json.
+ *   - If it exists, surgically overwrite ONLY the `glm_api_key` and
+ *     `hmos_sdk_dir` values (via jsonc edits), preserving every other
+ *     field the user has set. `hmos_sdk_dir` = `<DEVECO_SDK_HOME>/default`.
+ *
+ * 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, 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');
+    const hasExample = await fs
+        .access(examplePath)
+        .then(() => true)
+        .catch(() => false);
+    if (!hasExample)
+        return null;
+    let seeded = false;
+    let backupName = null;
+    let templateBackupName = null;
+    const hasConfig = await fs
+        .access(configPath)
+        .then(() => true)
+        .catch(() => false);
+    if (!hasConfig) {
+        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;
+    }
+    let raw = await fs.readFile(configPath, 'utf-8');
+    const parseErrors = [];
+    const tree = parseTree(raw, parseErrors);
+    if (!tree || tree.type !== 'object' || parseErrors.length > 0) {
+        // Corrupt config — never regenerate over user content; just report.
+        return `${UI_ALIGN_SKILL}/config.json NOT updated (file is not valid JSON — fix it manually)`;
+    }
+    const original = raw;
+    for (const [key, value] of updates) {
+        const edits = modify(raw, [key], value, {
+            formattingOptions: { tabSize: 2, insertSpaces: true },
+        });
+        raw = applyEdits(raw, edits);
+    }
+    if (raw !== original) {
+        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, skipNames = new Set()) {
     let entries;
     try {
         entries = await fs.readdir(skillsRoot, { withFileTypes: true });
@@ -142,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'))
@@ -155,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 });
@@ -166,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()) {
@@ -180,7 +366,79 @@ async function installAgentsTo(agentsRoot, targetDir) {
     }
     return installed;
 }
-async function installForEditor(editor, skillsRoot, agentsRoot, result) {
+/** 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))) {
         result.skipped.push(`${editor.name} (not installed)`);
@@ -188,8 +446,30 @@ async function installForEditor(editor, skillsRoot, agentsRoot, result) {
     }
     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)})`);
         }
@@ -197,8 +477,23 @@ async function installForEditor(editor, skillsRoot, agentsRoot, result) {
     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). Runs regardless of the overwrite decision above.
     try {
-        const agents = await installAgentsTo(agentsRoot, agentsDir);
+        const status = await refreshUiAlignConfig(skillsDir, glmApiKey, hmosSdkDir, prevUiAlignExample);
+        if (status) {
+            result.configured.push(`${editor.name} ${status}`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`${editor.name} ${UI_ALIGN_SKILL}/config.json: ${err.message}`);
+    }
+    try {
+        const agents = await installAgentsTo(agentsRoot, agentsDir, skipAgents);
         if (agents.length > 0) {
             result.configured.push(`${editor.name} agents (${agents.length} -> ${prettyHome(agentsDir)})`);
         }
@@ -207,12 +502,305 @@ async function installForEditor(editor, skillsRoot, agentsRoot, result) {
         result.errors.push(`${editor.name} agents: ${err.message}`);
     }
 }
+/**
+ * Display paths as full absolute OS-native paths (e.g. on Windows:
+ * `C:\Users\<you>\.claude\skills`) — no `~` abbreviation, no separator
+ * rewriting, so output matches what the user can copy into their shell.
+ */
 export function prettyHome(p) {
-    const home = os.homedir();
-    if (p.startsWith(home)) {
-        return '~' + p.slice(home.length).replace(/\\/g, '/');
+    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';
+    try {
+        const out = execFileSync(isWin ? 'where' : 'which', [cmd], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+        return lines[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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 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(spec, env) {
+    const status = new Map();
+    const isWin = process.platform === 'win32';
+    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;
+                }
+            }
+        }
+        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);
+    }
+    return status;
+}
+/**
+ * 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.
+ */
+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 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) {
+            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.hint ?? '')}`);
+        }
+    }
+    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`));
+    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 (unmetReq.length > 0) {
+            plain = 'BLOCKED';
+            color = chalk.red;
+            parts = [...unmetReq, ...unmetOpt];
+            allOk = false;
+        }
+        else if (unmetOpt.length > 0) {
+            plain = 'LIMITED';
+            color = chalk.yellow;
+            parts = unmetOpt;
+            allOk = false;
+        }
+        else {
+            plain = 'OK';
+            color = chalk.green;
+            parts = [];
+        }
+        const noteStr = parts.length > 0 && row.note ? chalk.gray(`  — ${row.note}`) : '';
+        console.log(`    ${row.name.padEnd(nameW)} ${row.kind.padEnd(6)} ${color(plain.padEnd(8))} ${parts.join(', ')}${noteStr}`);
+    }
+    console.log('');
+    if (allOk) {
+        console.log(chalk.green('  All environment dependencies found — every skill/agent is fully usable.'));
+    }
+    else {
+        console.log(chalk.gray('  Install the missing tools above and re-run `ht init` to clear the impact list.'));
     }
-    return p.replace(/\\/g, '/');
 }
 async function detectInstalledEditors(editors) {
     const status = new Map();
@@ -309,33 +897,76 @@ export async function initCommand(options = {}) {
         const answers = await inquirer.prompt([
             {
                 type: 'input',
-                name: 'OHOS_SDK_PATH',
-                message: 'OHOS_SDK_PATH:',
-                default: config.env.OHOS_SDK_PATH || undefined,
+                name: 'DEVECO_SDK_HOME',
+                message: 'DEVECO_SDK_HOME (DevEco Studio SDK dir):',
+                default: config.env.DEVECO_SDK_HOME || undefined,
             },
             {
                 type: 'input',
-                name: 'HMS_SDK_PATH',
-                message: 'HMS_SDK_PATH:',
-                default: config.env.HMS_SDK_PATH || undefined,
+                name: 'TEST_API_KEY',
+                message: 'TEST_API_KEY (LLM API key used by the integration-test agent to run test cases):',
+                default: config.env.TEST_API_KEY || undefined,
             },
             {
                 type: 'input',
-                name: 'TEST_API_KEY',
-                message: 'TEST_API_KEY (for autotest config.yaml):',
-                default: config.env.TEST_API_KEY || undefined,
+                name: 'GLM_API_KEY',
+                message: 'GLM_API_KEY (LLM API key for the GLM phone-agent used in UI alignment):',
+                default: config.env.GLM_API_KEY || undefined,
             },
         ]);
-        config.env.OHOS_SDK_PATH = answers.OHOS_SDK_PATH.trim();
-        config.env.HMS_SDK_PATH = answers.HMS_SDK_PATH.trim();
+        const sdk = deriveSdkPaths(answers.DEVECO_SDK_HOME);
+        config.env.DEVECO_SDK_HOME = sdk.DEVECO_SDK_HOME;
+        config.env.DEVECO_PATH = sdk.DEVECO_PATH;
+        config.env.OHOS_SDK_PATH = sdk.OHOS_SDK_PATH;
+        config.env.HMS_SDK_PATH = sdk.HMS_SDK_PATH;
         config.env.TEST_API_KEY = answers.TEST_API_KEY.trim();
+        config.env.GLM_API_KEY = answers.GLM_API_KEY.trim();
         await saveHomeTransConfig(config);
+        // Echo the derived paths and validate each exists on disk; missing ones are
+        // a strong signal of a typo'd DEVECO_SDK_HOME or a broken DevEco install.
+        if (sdk.DEVECO_SDK_HOME) {
+            const checks = [
+                ['DEVECO_SDK_HOME', sdk.DEVECO_SDK_HOME],
+                ['DEVECO_PATH', sdk.DEVECO_PATH],
+                ['OHOS_SDK_PATH', sdk.OHOS_SDK_PATH],
+                ['HMS_SDK_PATH', sdk.HMS_SDK_PATH],
+            ];
+            console.log('');
+            console.log(chalk.blue('  Derived from DEVECO_SDK_HOME:'));
+            let missingCount = 0;
+            for (const [name, p] of checks) {
+                const exists = await dirExists(p);
+                if (!exists)
+                    missingCount++;
+                const mark = exists ? chalk.green('+') : chalk.yellow('!');
+                const note = exists ? '' : chalk.yellow('  (not found on disk)');
+                console.log(`    ${mark} ${name.padEnd(15)} : ${p}${note}`);
+            }
+            if (missingCount > 0) {
+                console.log('');
+                console.log(chalk.yellow('  ! Check DEVECO_SDK_HOME (it should be the "sdk" folder inside your DevEco Studio install)'));
+                console.log(chalk.yellow('    and re-run `ht init` after fixing it. Skills that build or'));
+                console.log(chalk.yellow('    review code will not work until these paths resolve.'));
+            }
+        }
     }
     catch (err) {
         if (isPromptAbort(err))
             abortInit();
         console.log(chalk.yellow('  Parameter prompts skipped (non-interactive mode).'));
     }
+    // Detect external tools (adb / hdc / python / uv / java / gitnexus + DevEco)
+    // and report which skills/agents are impacted by anything missing.
+    try {
+        await runEnvironmentCheck(config.env);
+    }
+    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).
@@ -350,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')}`));
@@ -369,9 +1011,13 @@ export async function initCommand(options = {}) {
     console.log('');
     const editorsToSetup = editors.filter((e) => selectedEditors.includes(e.name));
     const result = { configured: [], skipped: [], errors: [] };
+    // hmos_sdk_dir consumed by incremental-ui-align = <DEVECO_SDK_HOME>/default.
+    const hmosSdkDir = config.env.DEVECO_SDK_HOME
+        ? path.join(config.env.DEVECO_SDK_HOME, 'default')
+        : '';
     for (const editor of editorsToSetup) {
         console.log(chalk.blue(`  Configuring ${editor.name}...`));
-        await installForEditor(editor, skillsRoot, agentsRoot, result);
+        await installForEditor(editor, skillsRoot, agentsRoot, config.env.GLM_API_KEY, hmosSdkDir, result);
     }
     await setupMcpForAllEditors(editorsToSetup, result);
     console.log('');