homegraph 1.0.0 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colby Mchenry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# HomeGraph
+
+本地代码知识图谱工具，面向 AI 编程助手（Claude Code、Cursor、Codex 等）提供 MCP 服务。
+
+在开源知识图谱能力之上，**HomeGraph 新增了对 ArkTS（HarmonyOS）的支持**，通过 [arkanalyzer](https://www.npmjs.com/package/arkanalyzer) 解析 `.ets` / `.ts` 工程中的符号、调用关系与模块结构。
+
+数据全部保存在本机 `.homegraph/` 目录，不上传云端。
+
+[![npm version](https://img.shields.io/npm/v/homegraph.svg)](https://www.npmjs.com/package/homegraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 快速开始
+
+### 1. 安装 CLI
+
+需要 **Node.js 22.5+**（推荐 22 LTS 或 24）。HomeGraph 使用 Node 内置的 `node:sqlite`，22.5 以下无法运行。
+
+```bash
+npm install -g homegraph
+```
+
+若在 Linux/WSL 遇到 `EACCES` 权限错误，可任选其一：
+
+```bash
+# 临时
+sudo npm install -g homegraph
+
+# 或把全局目录改到用户家目录（推荐）
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+npm install -g homegraph
+```
+
+验证：
+
+```bash
+homegraph --version
+```
+
+### 2. 接入 AI 助手
+
+在新终端中运行交互式安装器，自动写入各 Agent 的 MCP 配置：
+
+```bash
+homegraph install
+```
+
+#### 支持的 Agent 与 `--target` 取值
+
+| Agent | `--target` |
+|-------|------------|
+| Claude Code | `claude` |
+| Cursor | `cursor` |
+| Codex CLI | `codex` |
+| opencode | `opencode` |
+| DevEco Code | `deveco` |
+| CodeBuddy | `codebuddy` |
+| Hermes Agent | `hermes` |
+| Gemini CLI | `gemini` |
+| Antigravity IDE | `antigravity` |
+| Kiro | `kiro` |
+
+`--target` 还支持特殊取值：
+
+| 取值 | 说明 |
+|------|------|
+| `auto` | 自动检测本机已安装的 Agent（`--yes` 默认值） |
+| `all` | 写入全部 Agent |
+| `none` | 不写入任何 Agent 配置 |
+
+安装位置 `--location`：
+
+- `global` — 写入用户目录，对所有项目生效（`--yes` 默认值）
+- `local` — 仅写入当前项目目录
+
+> Codex CLI、Hermes Agent、Antigravity IDE **仅支持** `--location=global`；选 `local` 时会被跳过。
+
+#### 非交互式示例
+
+```bash
+# 自动检测已安装 Agent 并全局安装
+homegraph install --yes
+
+# 同时为 Cursor 和 DevEco Code 写入全局 MCP 配置
+homegraph install --target=cursor,deveco --location=global --yes
+
+# 单个 Agent
+homegraph install --target=claude --location=global --yes      # Claude Code
+homegraph install --target=cursor --location=global --yes      # Cursor
+homegraph install --target=codex --location=global --yes       # Codex CLI
+homegraph install --target=opencode --location=global --yes    # opencode
+homegraph install --target=deveco --location=global --yes      # DevEco Code
+homegraph install --target=codebuddy --location=global --yes   # CodeBuddy
+homegraph install --target=hermes --location=global --yes      # Hermes Agent
+homegraph install --target=gemini --location=global --yes      # Gemini CLI
+homegraph install --target=antigravity --location=global --yes # Antigravity IDE
+homegraph install --target=kiro --location=global --yes        # Kiro
+
+# 写入全部 Agent（全局）
+homegraph install --target=all --location=global --yes
+
+# 项目级安装（仅对当前项目生效，如 ./.cursor/mcp.json）
+homegraph install --target=cursor --location=local --yes
+homegraph install --target=claude,cursor --location=local --yes
+```
+
+安装完成后**重启对应 Agent**，使 MCP 配置生效。
+
+### 3. 初始化项目
+
+```bash
+cd your-project
+homegraph init -i
+```
+
+- `homegraph init`：仅创建 `.homegraph/` 索引目录  
+- `homegraph init -i`：创建目录并立即建立索引（推荐）
+
+索引建立后，Agent 可通过 MCP 工具查询符号、调用链、影响范围等。
+
+### 卸载
+
+```bash
+homegraph uninstall          # 从各 Agent 移除 MCP 配置
+homegraph uninit             # 删除当前项目的 .homegraph/ 索引
+```
+
+---
+
+## 常用命令
+
+```bash
+homegraph install            # 配置 AI 助手
+homegraph init -i [path]     # 初始化并索引项目
+homegraph index [path]       # 全量索引（--force 强制重建）
+homegraph sync [path]        # 增量同步变更
+homegraph status [path]      # 查看索引状态
+homegraph query <关键词>      # 搜索符号
+homegraph callers <符号>      # 谁调用了它
+homegraph callees <符号>      # 它调用了谁
+homegraph impact <符号>       # 修改该符号的影响范围
+homegraph serve --mcp         # 启动 MCP 服务（一般由 Agent 自动拉起）
+```
+
+---
+
+## MCP 工具
+
+Agent 侧工具名前缀为 `homegraph_`：
+
+| 工具 | 用途 |
+|------|------|
+| `homegraph_explore` | 主要工具：一次返回相关符号源码与调用关系 |
+| `homegraph_search` | 按名称快速定位符号 |
+| `homegraph_callers` / `homegraph_callees` | 查看调用方 / 被调用方 |
+| `homegraph_impact` | 变更影响分析 |
+| `homegraph_node` | 单个符号的完整源码与上下文 |
+| `homegraph_files` | 已索引的文件结构 |
+| `homegraph_status` | 索引健康状态 |
+
+---
+
+## 支持的语言
+
+继承上游多语言 tree-sitter 解析，包括但不限于：
+
+TypeScript / JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C / C++、Objective-C、Swift、Kotlin、Scala、Dart、Lua、Luau、Svelte、Vue、Liquid、Pascal / Delphi 等。
+
+**HomeGraph 新增：**
+
+| 语言 | 扩展名 | 说明 |
+|------|--------|------|
+| **ArkTS** | `.ets` 等 | 基于 arkanalyzer，支持 HarmonyOS 工程的类、方法、导入与调用关系提取 |
+
+---
+
+## 从源码构建
+
+适用于开发或二次修改：
+
+```bash
+git clone <your-repo-url>
+cd homegraph          # 仓库目录名可仍为 homegraph
+npm install
+npm run build
+npm run cli -- --help # 或直接：node dist/bin/homegraph.js --help
+npm test              # 运行测试
+```
+
+本地调试 CLI：
+
+```bash
+npm run cli
+# 等价于 npm run build && node dist/bin/homegraph.js
+```
+
+---
+
+## 手动配置 MCP（可选）
+
+以 Claude Code 为例，在 `~/.claude.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "homegraph": {
+      "type": "stdio",
+      "command": "homegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
+```
+
+Cursor 等项目级配置写入 `./.cursor/mcp.json`，格式相同。推荐使用 `homegraph install` 自动完成。
+
+---
+
+## 上游同步
+
+| 项目 | 说明 |
+|------|------|
+| 上游 | 持续同步 colbymchenry 开源知识图谱项目 main 分支 |
+| 包名 / CLI | `homegraph`（npm：`npm install -g homegraph`） |
+| 数据目录 | `.homegraph/` |
+| 主要差异 | 新增 **ArkTS** 语言支持与相关索引逻辑 |
+
+---
+
+## 环境要求
+
+- Node.js **22.5+**（推荐 22 LTS 或 24；使用 Node 内置 `node:sqlite`）
+- 首次索引时会对项目源码做 AST 解析，大型仓库首次 `init -i` 可能需要数分钟
+
+---
+
+## 许可证
+
+MIT

package/dist/bin/fatal-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Render an uncaught value for the last-resort log WITHOUT triggering stack
+ * formatting. Pure and total — never throws, never touches `.stack`.
+ */
+export declare function describeFatal(value: unknown): string;
+/** Injectable seams so the wiring is testable without registering real handlers. */
+export interface FatalHandlerDeps {
+    /** Event target to attach to. Defaults to `process`. */
+    target?: NodeJS.EventEmitter;
+    /** How to terminate. Defaults to `process.exit`. */
+    exit?: (code: number) => void;
+    /** How to emit the bounded line. Defaults to a synchronous fd-2 write. */
+    write?: (line: string) => void;
+}
+/**
+ * Install the uncaught-exception / unhandled-rejection handlers. Both log a
+ * bounded line and then exit non-zero (Node's default fatal semantics).
+ */
+export declare function installFatalHandlers(deps?: FatalHandlerDeps): void;
+//# sourceMappingURL=fatal-handler.d.ts.map

package/dist/bin/fatal-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fatal-handler.d.ts","sourceRoot":"","sources":["../../src/bin/fatal-handler.ts"],"names":[],"mappings":"AAmCA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcpD;AAWD,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC;IAC7B,oDAAoD;IACpD,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,gBAAqB,GAAG,IAAI,CActE"}

package/dist/bin/fatal-handler.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeFatal = describeFatal;
+exports.installFatalHandlers = installFatalHandlers;
+/**
+ * Last-resort handlers for uncaught exceptions and unhandled rejections.
+ *
+ * Reaching one of these means a fault escaped every boundary (per-request
+ * try/catch in the MCP transport, the file watcher's own `'error'` handlers,
+ * telemetry's fail-silent contract) — i.e. the process is in an undefined
+ * state. Node's default in that case is to print and exit non-zero. The CLI
+ * previously OVERRODE that to "log the error and keep running", which is the
+ * bug behind two production incidents:
+ *
+ *   - #799 — a stdin socket `'error'` escalated here; the server logged it and
+ *     kept running, orphaning the detached MCP daemon and (on Linux) spinning a
+ *     POLLHUP fd at 100% CPU. Fixed for that one trigger by treating stdin
+ *     failure as shutdown (`src/mcp/stdin-teardown.ts`).
+ *   - #850 — a *different* uncaught exception hit the same handler. Logging it
+ *     forced V8 to lazily format the Error's `.stack`, which entered a
+ *     non-terminating source-position walk and pinned a core. Because the
+ *     handler kept the process alive, the detached daemon was left wedged: its
+ *     PPID watchdog and idle-timer (both `setInterval`s) could no longer fire,
+ *     and nothing respawned it — unrecoverable without a manual `kill`.
+ *
+ * The fix restores the safe default: log a BOUNDED, hang-proof line, then exit
+ * non-zero so a fresh daemon starts on the next connection.
+ *
+ * Two properties are load-bearing and covered by tests:
+ *   1. {@link describeFatal} never reads `error.stack` and never hands the raw
+ *      Error to `console.*`. The lazy stack getter is exactly the step that can
+ *      wedge (#850); since it would run *inside* this handler, touching it could
+ *      block the very `exit()` below. Name + message are plain string
+ *      properties and are always safe.
+ *   2. We write synchronously to fd 2 and then exit, so the message is flushed
+ *      even though `process.exit()` doesn't drain async streams.
+ */
+const fs = __importStar(require("fs"));
+/**
+ * Render an uncaught value for the last-resort log WITHOUT triggering stack
+ * formatting. Pure and total — never throws, never touches `.stack`.
+ */
+function describeFatal(value) {
+    if (value instanceof Error) {
+        const name = typeof value.name === 'string' && value.name ? value.name : 'Error';
+        // `message` is a plain own/proto string property — reading it does NOT
+        // format the stack (which is what can loop forever, #850).
+        const message = typeof value.message === 'string' ? value.message : '';
+        return message ? `${name}: ${message}` : name;
+    }
+    try {
+        return String(value);
+    }
+    catch {
+        // e.g. an object with a throwing `toString` / `Symbol.toPrimitive`.
+        return '<unstringifiable value>';
+    }
+}
+/** Best-effort synchronous stderr write that can never keep a doomed process alive. */
+function writeStderr(line) {
+    try {
+        fs.writeSync(2, line);
+    }
+    catch {
+        /* stderr closed/gone — nothing more we can safely do */
+    }
+}
+/**
+ * Install the uncaught-exception / unhandled-rejection handlers. Both log a
+ * bounded line and then exit non-zero (Node's default fatal semantics).
+ */
+function installFatalHandlers(deps = {}) {
+    const target = deps.target ?? process;
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const write = deps.write ?? writeStderr;
+    target.on('uncaughtException', (error) => {
+        write(`[HomeGraph] Uncaught exception: ${describeFatal(error)}\n`);
+        exit(1);
+    });
+    target.on('unhandledRejection', (reason) => {
+        write(`[HomeGraph] Unhandled rejection: ${describeFatal(reason)}\n`);
+        exit(1);
+    });
+}
+//# sourceMappingURL=fatal-handler.js.map

package/dist/bin/fatal-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fatal-handler.js","sourceRoot":"","sources":["../../src/bin/fatal-handler.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,sCAcC;AAyBD,oDAcC;AA5FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,uCAAyB;AAEzB;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;QACjF,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,OAAO,yBAAyB,CAAC;IACnC,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;AACH,CAAC;AAYD;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,OAAyB,EAAE;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,WAAW,CAAC;IAExC,MAAM,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAc,EAAE,EAAE;QAChD,KAAK,CAAC,mCAAmC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,CAAC,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAe,EAAE,EAAE;QAClD,KAAK,CAAC,oCAAoC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrE,IAAI,CAAC,CAAC,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/bin/homegraph.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * HomeGraph CLI
+ *
+ * Command-line interface for HomeGraph code intelligence.
+ *
+ * Usage:
+ *   homegraph                    Run interactive installer (when no args)
+ *   homegraph install            Run interactive installer
+ *   homegraph uninstall          Remove HomeGraph from your agents
+ *   homegraph init [path]        Initialize HomeGraph in a project
+ *   homegraph uninit [path]      Remove HomeGraph from a project
+ *   homegraph index [path]       Index all files in the project
+ *   homegraph sync [path]        Sync changes since last index
+ *   homegraph status [path]      Show index status
+ *   homegraph query <search>     Search for symbols
+ *   homegraph files [options]    Show project file structure
+ *   homegraph context <task>     Build context for a task
+ *   homegraph callers <symbol>   Find what calls a function/method
+ *   homegraph callees <symbol>   Find what a function/method calls
+ *   homegraph impact <symbol>    Analyze what code is affected by changing a symbol
+ *   homegraph affected [files]   Find test files affected by changes
+ *   homegraph upgrade [version]  Update HomeGraph to the latest release
+ */
+export {};
+//# sourceMappingURL=homegraph.d.ts.map

package/dist/bin/homegraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"homegraph.d.ts","sourceRoot":"","sources":["../../src/bin/homegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}