@buaa_smat/hometrans 0.1.8 → 0.1.9

package/README.md

@@ -37,6 +37,19 @@ After confirming your editor selection, HomeTrans installs all bundled **skills*
 
 ---
 
+## Dependencies
+
+Install GitNexus (code knowledge graph dependency required by the migration agents):
+
+```bash
+npm install -g gitnexus
+gitnexus setup
+```
+
+For more details, see the official GitNexus repository: <https://github.com/abhigyanpatwari/GitNexus>
+
+---
+
 ## HarmonyOS Migration Guide
 
 鸿蒙软件迁移指导，提供完整的 Android 到 HarmonyOS 迁移流程：

package/dist/cli/config-store.js

@@ -0,0 +1,148 @@
+/**
+ * 全局配置存储：~/.hometrans/config.json
+ *
+ * 当前包含 editors 配置（Claude Code / Cursor / OpenCode / Codex），后续可扩展
+ * 其它顶层字段。首次 setup 时若文件不存在则写入默认值；之后用户可手动编辑。
+ * `ht config` 只读不改。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+export function getConfigDir() {
+    return path.join(os.homedir(), '.hometrans');
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), 'config.json');
+}
+/** 工具目录：~/.hometrans/tools，`ht init` 把打包的 tools/ 拷贝到此。 */
+export function getToolsDir() {
+    return path.join(getConfigDir(), 'tools');
+}
+/** 把 ~/foo 展开为 $HOME/foo；非 ~ 开头原样返回。 */
+export function expandHome(p) {
+    if (!p)
+        return p;
+    if (p === '~')
+        return os.homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+export function defaultEditors() {
+    return [
+        {
+            name: 'Claude Code',
+            markerDir: '~/.claude',
+            skillsDir: '~/.claude/skills',
+            agentsDir: '~/.claude/agents',
+            mcp: {
+                format: 'jsonc-object',
+                path: '~/.claude.json',
+                keyPath: ['mcpServers', 'hometrans'],
+            },
+        },
+        {
+            name: 'Cursor',
+            markerDir: '~/.cursor',
+            skillsDir: '~/.cursor/skills',
+            agentsDir: '~/.cursor/agents',
+            mcp: {
+                format: 'jsonc-object',
+                path: '~/.cursor/mcp.json',
+                keyPath: ['mcpServers', 'hometrans'],
+            },
+        },
+        {
+            name: 'OpenCode',
+            markerDir: '~/.config/opencode',
+            skillsDir: '~/.config/opencode/skills',
+            agentsDir: '~/.config/opencode/agents',
+            mcp: {
+                format: 'jsonc-command-array',
+                path: '~/.config/opencode/opencode.json',
+                keyPath: ['mcp', 'hometrans'],
+            },
+        },
+        {
+            name: 'Codex',
+            markerDir: '~/.codex',
+            // Codex 复用 Agent Skills 公共目录，agent 定义独立。
+            skillsDir: '~/.agents/skills',
+            agentsDir: '~/.codex/agents',
+            mcp: {
+                format: 'codex-cli',
+                path: '~/.codex/config.toml',
+                section: 'mcp_servers.hometrans',
+            },
+        },
+    ];
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 加载 editors 配置。文件不存在时写入默认值再返回。
+ * 解析失败时抛错，避免静默覆盖用户手动修改。
+ */
+export function defaultEnv() {
+    return {
+        OHOS_SDK_PATH: '',
+        HMS_SDK_PATH: '',
+        TEST_API_KEY: '',
+        TOOL_PATH: '',
+    };
+}
+export async function loadHomeTransConfig() {
+    const configPath = getConfigPath();
+    if (!(await fileExists(configPath))) {
+        const config = {
+            editors: defaultEditors(),
+            env: defaultEnv(),
+        };
+        await fs.mkdir(getConfigDir(), { recursive: true });
+        await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        return config;
+    }
+    const raw = await fs.readFile(configPath, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${configPath}: ${err.message}. Fix the JSON or delete the file to restore defaults.`);
+    }
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.editors)) {
+        throw new Error(`Invalid config.json shape at ${configPath}: top-level must be { "editors": [...] }.`);
+    }
+    const config = parsed;
+    const anyParsed = parsed;
+    // Migrate legacy fields into `env`:
+    //   - `sdkPaths` / `params` held OHOS_SDK_PATH / HMS_SDK_PATH / TEST_API_KEY.
+    //   - `tool_path` held the tools dir, now env.TOOL_PATH.
+    const legacyParams = (anyParsed.params ?? anyParsed.sdkPaths);
+    const legacyToolPath = typeof anyParsed.tool_path === 'string' ? anyParsed.tool_path : undefined;
+    config.env = {
+        ...defaultEnv(),
+        ...(legacyParams ?? {}),
+        ...(config.env ?? {}),
+    };
+    if (legacyToolPath && !config.env.TOOL_PATH) {
+        config.env.TOOL_PATH = legacyToolPath;
+    }
+    delete anyParsed.sdkPaths;
+    delete anyParsed.params;
+    delete anyParsed.tool_path;
+    return config;
+}
+export async function saveHomeTransConfig(config) {
+    const configPath = getConfigPath();
+    await fs.mkdir(getConfigDir(), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}

package/dist/cli/config.js

@@ -0,0 +1,40 @@
+/**
+ * `ht config` — 打印 editors.json 路径与内容。
+ *
+ * 该命令只读：用户若要修改 editor 配置，直接编辑这个 JSON 文件即可。
+ * 文件不存在时自动写入默认 4 个 editor。
+ */
+import fs from 'node:fs/promises';
+import { getConfigPath, loadHomeTransConfig } from './config-store.js';
+export async function configCommand() {
+    const configPath = getConfigPath();
+    const config = await loadHomeTransConfig();
+    const raw = await fs.readFile(configPath, 'utf-8');
+    console.log('');
+    console.log('  HomeTrans Config');
+    console.log('  ================');
+    console.log('');
+    console.log(`  Path: ${configPath}`);
+    console.log('');
+    // User parameters
+    const maskedKey = config.env.TEST_API_KEY
+        ? config.env.TEST_API_KEY.slice(0, 4) +
+            '***' +
+            config.env.TEST_API_KEY.slice(-4)
+        : '(not set)';
+    console.log('  Parameters:');
+    console.log(`    OHOS_SDK_PATH : ${config.env.OHOS_SDK_PATH || '(not set)'}`);
+    console.log(`    HMS_SDK_PATH  : ${config.env.HMS_SDK_PATH || '(not set)'}`);
+    console.log(`    TEST_API_KEY  : ${maskedKey}`);
+    console.log(`    TOOL_PATH     : ${config.env.TOOL_PATH || '(not set)'}`);
+    console.log('');
+    // Full config content
+    console.log('  Full Content:');
+    console.log('');
+    for (const line of raw.replace(/\r?\n$/, '').split(/\r?\n/)) {
+        console.log(`    ${line}`);
+    }
+    console.log('');
+    console.log('  Edit this file to modify config, then re-run `ht init`.');
+    console.log('');
+}

package/dist/cli/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import { initCommand } from './init.js';
+import { runMcpServer } from './mcp.js';
+import { configCommand } from './config.js';
+import { uninstallCommand } from './uninstall.js';
+const _require = createRequire(import.meta.url);
+const pkg = _require('../../package.json');
+const program = new Command();
+program
+    .name('hometrans')
+    .description('HomeTrans installer — distribute Android-to-HarmonyOS skills and agents into AI editors')
+    .version(pkg.version);
+program
+    .command('init')
+    .description('Initialize HomeTrans — select editors and install skills, agents, and MCP servers')
+    .option('-a, --all', 'Skip interactive selection and configure all editors')
+    .action(async (opts) => {
+    await initCommand(opts);
+});
+program
+    .command('mcp')
+    .description('Run the HomeTrans MCP server (stdio)')
+    .action(async () => {
+    await runMcpServer();
+});
+program
+    .command('config')
+    .description('Show the editors.json path and content (~/.hometrans/editors.json). Edit the file directly to customize editors, then re-run `ht init`.')
+    .action(async () => {
+    await configCommand();
+});
+program
+    .command('uninstall')
+    .description('Remove all hometrans skills, agents, and MCP entries from configured editors')
+    .action(async () => {
+    await uninstallCommand();
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/cli/init.js

@@ -0,0 +1,378 @@
+/**
+ * `ht init` — interactive initialization for HomeTrans.
+ *
+ * Displays the HomeTrans banner, lets the user select which editors to
+ * configure, then copies bundled skills/agents and registers MCP servers
+ * for the chosen editors.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import figlet from 'figlet';
+import inquirer from 'inquirer';
+import { setupMcpForAllEditors } from './mcp-setup.js';
+import { expandHome, getConfigPath, getToolsDir, loadHomeTransConfig, saveHomeTransConfig, } from './config-store.js';
+function ensureChalkColor() {
+    if (process.stdout.isTTY && chalk.level === 0) {
+        chalk.level = 1;
+    }
+}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export async function dirExists(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function copyDirRecursive(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+function resolveSkillsRoot() {
+    return path.resolve(__dirname, '..', '..', 'skills');
+}
+function resolveAgentsRoot() {
+    return path.resolve(__dirname, '..', '..', 'agents');
+}
+function resolveToolsRoot() {
+    return path.resolve(__dirname, '..', '..', 'tools');
+}
+/**
+ * Copy the bundled `tools/` folder into ~/.hometrans/tools and record the
+ * destination in config.env.TOOL_PATH. Returns the destination path, or null if
+ * the package ships no tools/ folder.
+ */
+async function installTools(toolsRoot, config) {
+    if (!(await dirExists(toolsRoot)))
+        return null;
+    const toolsDest = getToolsDir();
+    await copyDirRecursive(toolsRoot, toolsDest);
+    config.env.TOOL_PATH = toolsDest;
+    await saveHomeTransConfig(config);
+    return toolsDest;
+}
+/**
+ * The AutoTest tools live under the installed HomeTrans tools dir
+ * (~/.hometrans/tools/test-tools/autotest) once `installTools` has run.
+ * This is the same location the self-tester agent resolves via config.env.TOOL_PATH.
+ */
+function resolveAutotestDir(toolPath) {
+    return path.join(toolPath, 'test-tools', 'autotest');
+}
+/**
+ * Initialize / refresh `agents/test-tools/autotest/config.yaml`:
+ *   - If config.yaml does not exist, seed it from config.yaml.example.
+ *   - Replace every `api_key: "..."` line with the supplied apiKey.
+ *
+ * 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) {
+    const examplePath = path.join(autotestDir, 'config.yaml.example');
+    const configPath = path.join(autotestDir, 'config.yaml');
+    const hasExample = await fs
+        .access(examplePath)
+        .then(() => true)
+        .catch(() => false);
+    if (!hasExample)
+        return null;
+    let seeded = false;
+    const hasConfig = await fs
+        .access(configPath)
+        .then(() => true)
+        .catch(() => false);
+    if (!hasConfig) {
+        await fs.copyFile(examplePath, configPath);
+        seeded = true;
+    }
+    if (!apiKey) {
+        return seeded
+            ? `autotest config.yaml seeded (api_key left as placeholder)`
+            : null;
+    }
+    const original = await fs.readFile(configPath, 'utf-8');
+    // Match `api_key: <value>` with optional quoting, preserve indent + key.
+    const updated = original.replace(/^(\s*api_key\s*:\s*)(?:"[^"]*"|'[^']*'|\S+)\s*$/gm, (_m, prefix) => `${prefix}"${apiKey}"`);
+    if (updated !== original) {
+        await fs.writeFile(configPath, updated, 'utf-8');
+    }
+    return seeded
+        ? `autotest config.yaml seeded + api_key filled`
+        : `autotest config.yaml api_key refreshed`;
+}
+async function installSkillsTo(skillsRoot, targetDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const installed = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillSrc = path.join(skillsRoot, entry.name);
+        const hasSkillFile = await fs
+            .access(path.join(skillSrc, 'SKILL.md'))
+            .then(() => true)
+            .catch(() => false);
+        if (!hasSkillFile)
+            continue;
+        const skillDest = path.join(targetDir, entry.name);
+        await copyDirRecursive(skillSrc, skillDest);
+        installed.push(entry.name);
+    }
+    return installed;
+}
+async function installAgentsTo(agentsRoot, targetDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(agentsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    await fs.mkdir(targetDir, { recursive: true });
+    const installed = [];
+    for (const entry of entries) {
+        const srcPath = path.join(agentsRoot, entry.name);
+        const destPath = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirRecursive(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            await fs.copyFile(srcPath, destPath);
+            if (entry.name.endsWith('.md')) {
+                installed.push(entry.name.slice(0, -3));
+            }
+        }
+    }
+    return installed;
+}
+async function installForEditor(editor, skillsRoot, agentsRoot, result) {
+    const marker = expandHome(editor.markerDir);
+    if (marker && !(await dirExists(marker))) {
+        result.skipped.push(`${editor.name} (not installed)`);
+        return;
+    }
+    const skillsDir = expandHome(editor.skillsDir);
+    const agentsDir = expandHome(editor.agentsDir);
+    try {
+        const skills = await installSkillsTo(skillsRoot, skillsDir);
+        if (skills.length > 0) {
+            result.configured.push(`${editor.name} skills (${skills.length} -> ${prettyHome(skillsDir)})`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`${editor.name} skills: ${err.message}`);
+    }
+    try {
+        const agents = await installAgentsTo(agentsRoot, agentsDir);
+        if (agents.length > 0) {
+            result.configured.push(`${editor.name} agents (${agents.length} -> ${prettyHome(agentsDir)})`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`${editor.name} agents: ${err.message}`);
+    }
+}
+export function prettyHome(p) {
+    const home = os.homedir();
+    if (p.startsWith(home)) {
+        return '~' + p.slice(home.length).replace(/\\/g, '/');
+    }
+    return p.replace(/\\/g, '/');
+}
+async function detectInstalledEditors(editors) {
+    const status = new Map();
+    for (const editor of editors) {
+        const marker = expandHome(editor.markerDir);
+        if (!marker) {
+            status.set(editor.name, true);
+        }
+        else {
+            status.set(editor.name, await dirExists(marker));
+        }
+    }
+    return status;
+}
+export async function initCommand(options = {}) {
+    ensureChalkColor();
+    const banner = figlet.textSync('HomeTrans', { font: 'Standard' });
+    console.log(chalk.cyan(`\n${banner.trimEnd()}`));
+    console.log(chalk.gray('\n   Android-to-HarmonyOS skill & agent installer for AI editors\n'));
+    const skillsRoot = resolveSkillsRoot();
+    const agentsRoot = resolveAgentsRoot();
+    const toolsRoot = resolveToolsRoot();
+    const hasSkills = await dirExists(skillsRoot);
+    const hasAgents = await dirExists(agentsRoot);
+    if (!hasSkills && !hasAgents) {
+        console.error(chalk.red(`  ! Neither skills/ nor agents/ found at package root.`));
+        console.error(chalk.gray(`    Looked in: ${skillsRoot}`));
+        console.error(chalk.gray(`               ${agentsRoot}`));
+        console.error(chalk.gray('    Reinstall hometrans or run `npm run build` from the package root.'));
+        process.exitCode = 1;
+        return;
+    }
+    const config = await loadHomeTransConfig();
+    const { editors } = config;
+    const installedStatus = await detectInstalledEditors(editors);
+    let selectedEditors;
+    if (options.all) {
+        selectedEditors = editors.map((e) => e.name);
+        console.log(chalk.blue('  --all: selecting all editors.\n'));
+    }
+    else {
+        const choices = editors.map((editor) => {
+            const installed = installedStatus.get(editor.name);
+            const label = installed
+                ? `${editor.name}  ${chalk.green('(detected)')}`
+                : `${editor.name}  ${chalk.gray('(not detected)')}`;
+            return {
+                name: label,
+                value: editor.name,
+                checked: installed,
+            };
+        });
+        try {
+            const answers = await inquirer.prompt([
+                {
+                    type: 'checkbox',
+                    name: 'selectedEditors',
+                    message: 'Select editors to configure (arrow keys + space to toggle, enter to confirm):',
+                    choices,
+                },
+            ]);
+            selectedEditors = answers.selectedEditors;
+        }
+        catch {
+            console.log(chalk.yellow('\n  Interactive selection failed. Auto-selecting all detected editors.'));
+            console.log(chalk.gray('  Tip: use --all to skip interactive selection.\n'));
+            selectedEditors = editors
+                .filter((e) => installedStatus.get(e.name))
+                .map((e) => e.name);
+        }
+    }
+    if (selectedEditors.length === 0) {
+        console.log(chalk.yellow('\n  No editors selected. Nothing to do.\n'));
+        return;
+    }
+    // --- User parameters (SDK paths, test API key) ---
+    console.log('');
+    console.log(chalk.blue('  Parameter Configuration'));
+    console.log(chalk.gray('  (press Enter to keep current value or leave empty)\n'));
+    try {
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'OHOS_SDK_PATH',
+                message: 'OHOS_SDK_PATH:',
+                default: config.env.OHOS_SDK_PATH || undefined,
+            },
+            {
+                type: 'input',
+                name: 'HMS_SDK_PATH',
+                message: 'HMS_SDK_PATH:',
+                default: config.env.HMS_SDK_PATH || undefined,
+            },
+            {
+                type: 'input',
+                name: 'TEST_API_KEY',
+                message: 'TEST_API_KEY (for autotest config.yaml):',
+                default: config.env.TEST_API_KEY || undefined,
+            },
+        ]);
+        config.env.OHOS_SDK_PATH = answers.OHOS_SDK_PATH.trim();
+        config.env.HMS_SDK_PATH = answers.HMS_SDK_PATH.trim();
+        config.env.TEST_API_KEY = answers.TEST_API_KEY.trim();
+        await saveHomeTransConfig(config);
+    }
+    catch {
+        console.log(chalk.yellow('  Parameter prompts skipped (non-interactive mode).'));
+    }
+    // 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).
+    let installedToolPath = null;
+    try {
+        installedToolPath = await installTools(toolsRoot, config);
+        if (installedToolPath) {
+            console.log(chalk.green(`  + tools copied -> ${prettyHome(installedToolPath)}`));
+            console.log(chalk.gray(`    TOOL_PATH set in ${prettyHome(getConfigPath())}`));
+        }
+    }
+    catch (err) {
+        console.log(chalk.red(`  ! tools 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);
+            if (status) {
+                console.log(chalk.green(`  + ${status}`));
+                console.log(chalk.gray(`    ${path.join(autotestDir, 'config.yaml')}`));
+            }
+        }
+    }
+    catch (err) {
+        console.log(chalk.red(`  ! autotest config.yaml: ${err.message}`));
+    }
+    console.log('');
+    const editorsToSetup = editors.filter((e) => selectedEditors.includes(e.name));
+    const result = { configured: [], skipped: [], errors: [] };
+    for (const editor of editorsToSetup) {
+        console.log(chalk.blue(`  Configuring ${editor.name}...`));
+        await installForEditor(editor, skillsRoot, agentsRoot, result);
+    }
+    await setupMcpForAllEditors(editorsToSetup, result);
+    console.log('');
+    if (result.configured.length > 0) {
+        console.log(chalk.green('  Configured:'));
+        for (const name of result.configured)
+            console.log(chalk.green(`    + ${name}`));
+    }
+    if (result.skipped.length > 0) {
+        console.log('');
+        console.log(chalk.yellow('  Skipped:'));
+        for (const name of result.skipped)
+            console.log(chalk.yellow(`    - ${name}`));
+    }
+    if (result.errors.length > 0) {
+        console.log('');
+        console.log(chalk.red('  Errors:'));
+        for (const err of result.errors)
+            console.log(chalk.red(`    ! ${err}`));
+    }
+    console.log('');
+    console.log(chalk.gray(`  Source skills: ${skillsRoot}`));
+    console.log(chalk.gray(`  Source agents: ${agentsRoot}`));
+    console.log('');
+    if (result.configured.length === 0 && result.errors.length === 0) {
+        console.log(chalk.yellow('  No editors were configured. Make sure the selected editors are installed,'));
+        console.log(chalk.yellow('  then re-run `ht init`.'));
+    }
+    else {
+        console.log(chalk.green('  Done. Re-open your editor for the new skills/agents to be picked up.'));
+    }
+    console.log('');
+}