@buaa_smat/hometrans 0.1.8 → 0.1.10

package/README.md

@@ -1,6 +1,6 @@
 # hometrans
 
-> Skill + agent installer for the **HomeTrans** Android-to-HarmonyOS conversion toolkit. One command (`ht init`) distributes **7 skills**, **9 subagents** (with a script bundle + on-device test tooling), and an **MCP server** into Claude Code, Cursor, OpenCode, and Codex.
+> Skill + agent installer for the **HomeTrans** Android-to-HarmonyOS conversion toolkit. One command (`ht init`) distributes **7 skills**, **9 subagents** (with a script bundle + on-device test tooling), and an **MCP server** into Claude Code, Cursor, OpenCode, Codex, and CodeBuddy.
 
 ---
 
@@ -23,7 +23,7 @@ After running `ht init`, follow these steps to complete the installation:
 
 ### Step 1: Choose your target editor
 
-`ht init` automatically detects supported editors (Claude Code, Cursor, OpenCode, Codex) and presents an interactive selection prompt. Use **Space** to toggle and **Enter** to confirm.
+`ht init` automatically detects supported editors (Claude Code, Cursor, OpenCode, Codex, CodeBuddy) and presents an interactive selection prompt. Use **Space** to toggle and **Enter** to confirm.
 
 ![Choose target editor](resource/choose_editor.png)
 
@@ -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 迁移流程：
@@ -154,12 +167,13 @@ After confirming your editor selection, HomeTrans installs all bundled **skills*
 
 ### Target directories
 
-| Editor | Marker | Skills target | Agents target |
-|--------|--------|---------------|---------------|
-| Claude Code | `~/.claude/` | `~/.claude/skills/` | `~/.claude/agents/` |
-| Cursor | `~/.cursor/` | `~/.cursor/skills/` | `~/.cursor/agents/` |
-| OpenCode | `~/.config/opencode/` | `~/.config/opencode/skills/` | `~/.config/opencode/agents/` |
-| Codex | `~/.codex/` | `~/.agents/skills/` | `~/.codex/agents/` |
+| Editor | Marker | Skills target | Agents target | MCP config |
+|--------|--------|---------------|---------------|------------|
+| Claude Code | `~/.claude/` | `~/.claude/skills/` | `~/.claude/agents/` | `~/.claude.json` → `mcpServers.hometrans` |
+| Cursor | `~/.cursor/` | `~/.cursor/skills/` | `~/.cursor/agents/` | `~/.cursor/mcp.json` → `mcpServers.hometrans` |
+| OpenCode | `~/.config/opencode/` | `~/.config/opencode/skills/` | `~/.config/opencode/agents/` | `~/.config/opencode/opencode.json` → `mcp.hometrans` |
+| Codex | `~/.codex/` | `~/.agents/skills/` | `~/.codex/agents/` | `codex mcp add` → `~/.codex/config.toml` `[mcp_servers.hometrans]` |
+| CodeBuddy | `~/.codebuddy/` | `~/.codebuddy/skills/` | `~/.codebuddy/agents/` | `~/.codebuddy/mcp.json` → `mcpServers.hometrans` |
 
 ---
 

package/dist/cli/config-store.js

@@ -0,0 +1,171 @@
+/**
+ * 全局配置存储：~/.hometrans/config.json
+ *
+ * 当前包含 editors 配置（Claude Code / Cursor / OpenCode / Codex / CodeBuddy），后续可扩展
+ * 其它顶层字段。首次 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',
+            },
+        },
+        {
+            // CodeBuddy（腾讯）：与 Claude Code 同构的 .codebuddy/ 目录，
+            // 全局安装映射到 ~/.codebuddy/{skills,agents}，MCP 走 mcpServers JSON。
+            name: 'CodeBuddy',
+            markerDir: '~/.codebuddy',
+            skillsDir: '~/.codebuddy/skills',
+            agentsDir: '~/.codebuddy/agents',
+            mcp: {
+                format: 'jsonc-object',
+                path: '~/.codebuddy/mcp.json',
+                keyPath: ['mcpServers', '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;
+    // Append any default editors that this (older) config predates, matched by
+    // name. Existing entries are never modified, so manual edits are preserved;
+    // we only add editors the user's file is missing (e.g. CodeBuddy shipped
+    // after they first ran `ht init`). Persist so the new editor shows up.
+    const existingNames = new Set(config.editors.map((e) => e.name));
+    const missingEditors = defaultEditors().filter((e) => !existingNames.has(e.name));
+    if (missingEditors.length > 0) {
+        config.editors.push(...missingEditors);
+        await saveHomeTransConfig(config);
+    }
+    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 文件即可。
+ * 文件不存在时自动写入默认 5 个 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,67 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+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');
+/**
+ * Global Ctrl-C safety net.
+ *
+ * inquirer intercepts Ctrl-C as a keypress *inside* a prompt (raw mode) and the
+ * per-command catches print a tailored "Cancelled" notice there. But Ctrl-C
+ * pressed *outside* a prompt — e.g. while `init` is copying files or `uninstall`
+ * is deleting — arrives as an OS SIGINT, which Node would otherwise terminate on
+ * silently. This handler guarantees a cancel notice in that case too.
+ *
+ * The MCP server (`ht mcp`) runs over stdio and must keep its own shutdown
+ * semantics, so it removes this handler on startup.
+ */
+let interrupted = false;
+function onSigint() {
+    if (interrupted)
+        process.exit(130);
+    interrupted = true;
+    console.log(chalk.yellow('\n  Cancelled by Ctrl-C. No further changes will be made.\n'));
+    process.exit(130);
+}
+process.on('SIGINT', onSigint);
+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 () => {
+    // The MCP server owns its own SIGINT/shutdown handling; drop the CLI net.
+    process.off('SIGINT', onSigint);
+    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);
+});