homegraph 1.5.3 → 1.5.4

package/CHANGELOG.md

@@ -9,6 +9,30 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+
+## [1.5.4] - 2026-08-19
+
+### Breaking Changes
+
+- Require Node.js **22+** (`engines: >=22`). Node 18–21 are no longer supported; the CLI hard-exits below major 22. Dependencies that were pinned for Node 18 are restored: `commander@^14`, `@clack/prompts@^1.7`, optional `better-sqlite3@^12`. Use `npm run test:node-matrix` (nvm) to exercise majors 22–25 locally.
+
+### New Features
+
+- Docs hub at `docs/README.md` plus a short `docs/RELEASE.md` for publishing [`homegraph`](https://www.npmjs.com/package/homegraph) (Actions), GitCode releases, and mirror checks — without duplicating DEVELOPMENT SDD.
+- Explore better matches common survey shapes (data-source, Event→handler, multi-Type deps, resource/preview, NAPI) with honest **Partial** vs **ANSWER NOW**, so agents get anchors without fake-complete dumps that trigger Grep storms.
+- Startup MCP instructions are a shorter locator playbook: how to write `query`, when to stop after explore, and when to Skip — without long low-salience essays.
+- Repeated or near-duplicate `homegraph_explore` bags are guarded so agents do not spin on the same keyword paraphrase.
+- New `homegraph addon` command group installs and manages pluggable addons (`init`, `install`, `list`, `remove`, `enable`, `disable`, `update`) from npm packages or local paths. Addons extend `homegraph spec mine` with external requirement context — e.g. map commit messages to Jira tickets and inject the fetched details into the spec-generation prompt — without HomeGraph knowing any ticket format. Enrichment runs per commit cluster with per-addon timeouts and failure isolation, so a broken addon never blocks spec generation.
+- `homegraph addon` version policy: re-installing a registered addon refuses **downgrades** (`remove` first), upgrades preserve the previous version and **restore it when the new one fails validation**, and `update --latest` forces the newest published version (registry packages only — local-path installs have no dist-tag). Applies to npm packages and local-path installs alike.
+
+### Fixes
+
+- `homegraph_arkui_migrate` no longer materializes every `class`/`struct` to find `@Observed` types: it walks scope state-var `observed-ref` edges and scoped files only, so large Harmony repos stop timing out on migrate snapshots.
+- Explore default is **universal mid-lean**: **Anchors** (`symbol` → `file:line`) first, ≤2 spine digests (~12K ceiling, ~3K/file), Relationships off. Partial **Next anchor** ranks domain Manager inventory by query-token overlap + CJK→ASCII domain stems (digests prefer that file) — e.g. 通知订阅 → SubscribeManager over screenlock StateManager, 备份 → Extension over EventManager; when inventory + digest are enough, explore **soft-closes** with matching **Coarse locate — ANSWER** header+footer (no Partial/ANSWER contradiction). Session fuse: ≤2 explores; after Partial, follow-ups must name the Next anchor (no novel-Type bypass); callers/callees refused; ≤1 `homegraph_node`. A second Partial appends a hard stop footer. Qualified `Type.member` callers no longer fall back to every bare `member`. ArkTS: synthesize `commonEventManager` publish↔subscribe (literal event) and `taskpool.execute`→named worker. Skip: chained layout literals (`.width('…')`) and pure C-API “which callback” catalogs. Set `HOMEGRAPH_EXPLORE_FULL_SOURCE=1` for the prior body-heavy dump. Cross-Type “如何驱动 / 状态变化” questions no longer collapse into compact hard-ANSWER-NOW; `homegraph_callers` steers Type-wide inventory instead of per-method fan-out.
+- ArkTS indexing no longer `realpathSync`s every ArkAnalyzer path on the hot path: the project root is canonicalized once per batch, then relative paths are string-stripped (with a cached realpath fallback when prefixes disagree) — restoring Storing speed on large Harmony repos while keeping macOS `/var`↔`/private/var` and symlink-root correctness.
+- Multi-term locator bags (e.g. `item` + `service`) are no longer misrouted into light-mechanism just because `service` is a generic noun, so corroboration / full explore ranking can still surface the matching backend file.
+- Renamed the language-verification guide (was `SEARCH_QUALITY_LOOP.md`) and archived settled design notes under `docs/design/archive/` so the docs tree is easier to navigate.
+
 ## [1.5.3] - 2026-08-11
 
 ### New Features
@@ -52,7 +76,6 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Explore **route mutual-exclusion** hardened so inventory/member surveys cannot steal Type×method interaction, Export-fail wiring, or Release↔destructor compares; Manager **状态来源** goes to data-source inventory; repo-wide literal/`text` import hunts defer to Grep (never light); light-mechanism output capped leaner; system-language / hover / kit-deps prefer explore-first. Regression corpus lives under `test/explore-routing/` (`npm run test:explore-routing`; set `HOMEGRAPH_PROBE_ROOT` for live size checks).
 - Light-mechanism **XML howto** seeds `convertxml` / `XmlParseUtil` and caps import/source size so explore stays lean enough that agents need not stack Grep/Read.
 
-
 ## [1.5.2] - 2026-08-05
 
 ### New Features
@@ -125,6 +148,8 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Incremental sync now picks up cross-file relationships that only become resolvable after an edit — for example, when a file gains an export that another, unchanged file was already importing or calling. Previously the reference in the unchanged file was never revisited, so callers, impact, and flow results silently omitted the new edge (while status reported a clean index) until a full re-index. References that can't be resolved yet are now remembered and automatically retried whenever a change introduces a symbol that could satisfy them — this also covers a class gaining a new method that other files already call. Thanks @loadcosmos for the report with a minimal reproduction. (#1240)
 - The reverse case is fixed too: when an edit removes or moves a symbol (or deletes its file), callers in unchanged files now re-resolve during the same sync — rebinding to the symbol's new home when it moved, or waiting to reconnect automatically when it comes back — instead of silently losing their relationship until a full re-index. (#1240)
 
+[1.5.4]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.4
+[1.5.3]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.3
 [1.5.2]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.2
 [1.5.1]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.1
 [1.5.0]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.0

package/README.md

@@ -15,7 +15,7 @@
 
 ### 1. 安装 CLI
 
-需要 **Node.js 18+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5），否则 `better-sqlite3`（11.x，含 Node 18），再不行回退 `node-sqlite3-wasm`。
+需要 **Node.js 22+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5），否则 `better-sqlite3`（12.x），再不行回退 `node-sqlite3-wasm`。
 
 ```bash
 npm install -g homegraph
@@ -149,6 +149,7 @@ homegraph impact <符号>         # 修改该符号的影响范围
 homegraph affected [files...]  # 根据变更文件查找受影响的测试（支持 --stdin）
 homegraph spec build           # 从已有 .spec 目录（或用户指定目录）构建Spec知识图谱（Commit4Spec）
 homegraph spec mine            # 从 Git 历史挖掘设计Spec文档（AST 分析 + LLM 聚类生成）
+homegraph addon ...            # 管理 用户自定义插件（init/install/list/remove/enable/disable/update）
 homegraph spec match <文本>     # 全文搜索相似历史Spec
 homegraph spec find <文件>      # 查找与指定文件关联的Spec
 homegraph spec trace <符号>     # 追溯代码符号关联的Spec
@@ -197,7 +198,31 @@ Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `
 
 **路径 1：`spec build`（已有Spec导入）**
 
-从项目已有的 `.spec` 目录（或用户指定目录）读取Spec文档，解析其中的 Git 引用和变更片段，直接构建知识图谱节点与关系。
+从项目已有的 `.spec` 目录（或用户指定目录）读取 Spec 文档，通过内置的启发式规则将 Git 提交与 Spec 文档配对，解析配对提交的变更片段，直接构建知识图谱节点与关系。
+
+默认规则与文档发现逻辑可通过 `.homegraph/commit4spec/configs.json` 的 `discovery` 与 `commitScope` 段进行用户自定义
+
+```json
+{
+  //Spec 文档发现：
+  // {specId}.md 平铺文件，或 {specId}/ 目录下按 `primaryDocCandidates` 顺序取第一个存在的主文档；
+  // 目录内匹配 `supplementaryGlobs` 的补充 `.md`文档标题并入 Spec 子标题。
+  "discovery": {
+    "primaryDocCandidates": ["plan.md", "README.md", "spec.md", "design.md", "{spec_dir_name}.md", "spec-{spec_dir_name}.md",],
+    "supplementaryGlobs": ["logic/**/*.md", "design/**/*.md"]
+  },
+  //commit-spec匹配：
+  // 优先从 commit message 的第一行提取 conventional-commit scope（如 `feat(spec03): ...`），归一化后若能在磁盘上找到对应 spec 则直接采用、不回退正文；
+  // 若第一行 scope 对应的 spec 在磁盘上不存在（或第一行完全未命中 scope）且配置了 `bodyRegex`，则回退从正文/footer 提取 spec 引用（如 `Spec: spec03` trailer）；
+  // `bodyRegex` 为可选配置，未配置时仅用标题通道；
+  // 默认提取后归一化（`normalize`）：剥 `review/` 前缀 → 转小写 → `spec3` 补零为 `spec03`。
+  "commitScope": {
+    "scopeRegex": "^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\\((?:review\\/)?(spec\\d+)\\)",
+    "bodyRegex": "^Spec:\\s*(spec\\d+)\\s*$",
+    "normalize": { "stripPrefixes": ["review/"], "lowercase": true, "padSpecNumber": true }
+  }
+}
+```
 
 **路径 2：`spec mine`（Spec逆向挖掘）**
 
@@ -205,7 +230,9 @@ Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `
 
 支持增量模式（`meta.json` 记录已处理范围）、commit过滤和聚类输出模式（`--skip-llm`）。
 
-`spec mine`逆向挖掘和`spec evolve process`演化更新涉及到模型访问，优先选择用户本地已有的Agent平台（Claude Code >> Codex >> 用户配置LLM），若未安装Claude Code或Codex，则需用户自主配置模型服务，编辑配置文件`.homegraph/commit4spec/configs.json`
+`spec mine`逆向挖掘和`spec evolve process`演化更新涉及到模型访问，优先选择用户本地已有的Agent平台（Claude Code >> Codex >> DevEco Code >> 用户配置LLM），可用环境变量 `HOMEGRAPH_SPEC_AGENT` 强制指定（取值 `claude-code`、`codex`、`deveco-code`，`none` 表示禁用）。
+
+若未安装Claude Code、Codex或DevEco Code，则需用户自主配置模型服务，编辑配置文件`.homegraph/commit4spec/configs.json`
 
 ```json
 // All available options (fields marked * are required):
@@ -230,6 +257,25 @@ homegraph spec find src/auth.ts   # 哪些Spec涉及该文件
 homegraph spec trace UserService  # 追溯符号关联的设计Spec
 ```
 
+**Addons（插件扩展）：**
+
+`homegraph addon` 管理可插拔扩展包，为 `spec mine` 注入外部需求上下文（如 Jira 工单详情），无需 HomeGraph 认识任何工单格式：
+
+```bash
+homegraph addon init my-jira       # 生成 addon 脚手架（内置示例）
+homegraph addon install ./my-jira  # 安装并登记（记录具体版本号）
+homegraph addon list               # 查看已登记的 addon 及状态
+homegraph addon update my-jira     # 更新（默认按记录 range 内最新；--latest 强制 @latest，仅 registry 包）
+homegraph addon disable my-jira    # 停用（保留安装）
+homegraph addon remove my-jira     # 注销（--purge 同时删除文件）
+```
+
+Addon 实现 `enrich` 钩子：HomeGraph 按 commit 簇传入其已有的 commit 数据（hash / 消息 / 作者 / 时间戳），addon 返回带去重键的需求补充文本，HomeGraph 去重后渲染进生成 prompt 的 `## Supplement` 段。
+
+（可选） `buildPrompt` 钩子：用于整体接管 prompt 组装——HomeGraph 传入簇数据、已去重的补充文本、输出模板与字符预算（软约定），由 addon 自行组装完整 prompt，第一个提供该钩子的 addon 生效，调用失败自动回退到默认组装。
+
+每个 addon 独立超时（15s）且失败不影响生成；包需在 package.json 声明 `"homegraph": { "addon": true, "api": 1 }`；登记表存于 `.homegraph/addons.json`，仅显式登记且启用的 addon 才会被加载。
+
 ---
 
 ## 支持的语言
@@ -248,7 +294,7 @@ TypeScript / JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C / C++
 
 ## 从源码构建
 
-适用于开发或二次修改。协作约定（代码拉取、Commit、PR 清单）见 [DEVELOPMENT.md](./DEVELOPMENT.md)。
+适用于开发或二次修改。协作约定（Spec、Commit、PR）见 [DEVELOPMENT.md](./DEVELOPMENT.md)；文档目录见 [docs/README.md](./docs/README.md)；发包见 [docs/RELEASE.md](./docs/RELEASE.md)；本地 CLI/MCP 见 [docs/local-dev-guide.md](./docs/local-dev-guide.md)。
 
 ```bash
 git clone <your-repo-url>
@@ -301,7 +347,7 @@ Cursor 等项目级配置写入 `./.cursor/mcp.json`，格式相同。推荐使
 
 ## 环境要求
 
-- Node.js **18+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → better-sqlite3 11.x → wasm）
+- Node.js **22+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → better-sqlite3 12.x → wasm）
 - 首次索引时会对项目源码做 AST 解析，大型仓库首次 `init -i` 可能需要数分钟
 - WSL2 下若项目位于 Windows 盘符（`/mnt/c` 等）且 MCP 连接不稳定，可设置 `HOMEGRAPH_NO_DAEMON=1` 跳过共享后台服务，每个会话独立运行
 

package/dist/addons/dynamic-import.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Dynamic ESM import for CJS builds.
+ *
+ * tsc compiles `import()` to `require()` under `module: commonjs`, which
+ * fails for ESM-only addon packages. `new Function` bypasses the transform
+ * and works in the production CLI (plain CJS Node). Some host contexts
+ * (e.g. vitest worker realms) have no dynamic-import callback on
+ * Function-created globals — tests mock this module with a plain
+ * module-scope `import()`, which works there.
+ *
+ * @module addons/dynamic-import
+ */
+/**
+ * Import an ESM module by specifier. For addons the specifier is an
+ * absolute `file://` URL of the resolved entry point.
+ */
+export declare function importESM(specifier: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=dynamic-import.d.ts.map

package/dist/addons/dynamic-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.d.ts","sourceRoot":"","sources":["../../src/addons/dynamic-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE7E"}

package/dist/addons/dynamic-import.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Dynamic ESM import for CJS builds.
+ *
+ * tsc compiles `import()` to `require()` under `module: commonjs`, which
+ * fails for ESM-only addon packages. `new Function` bypasses the transform
+ * and works in the production CLI (plain CJS Node). Some host contexts
+ * (e.g. vitest worker realms) have no dynamic-import callback on
+ * Function-created globals — tests mock this module with a plain
+ * module-scope `import()`, which works there.
+ *
+ * @module addons/dynamic-import
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importESM = importESM;
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const importViaFunction = new Function('specifier', 'return import(specifier)');
+/**
+ * Import an ESM module by specifier. For addons the specifier is an
+ * absolute `file://` URL of the resolved entry point.
+ */
+function importESM(specifier) {
+    return importViaFunction(specifier);
+}
+//# sourceMappingURL=dynamic-import.js.map

package/dist/addons/dynamic-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.js","sourceRoot":"","sources":["../../src/addons/dynamic-import.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAWH,8BAEC;AAXD,8DAA8D;AAC9D,MAAM,iBAAiB,GAAG,IAAI,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAEzC,CAAC;AAEtC;;;GAGG;AACH,SAAgB,SAAS,CAAC,SAAiB;IACzC,OAAO,iBAAiB,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC"}

package/dist/addons/init-template.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Addon scaffold generator (`homegraph addon init`).
+ *
+ * Produces a publishable npm package skeleton with the `homegraph` marker,
+ * an `enrich` stub, and a worked Jira example (parse ticket refs → fetch
+ * details → return supplements).
+ *
+ * @module addons/init-template
+ */
+/**
+ * Create the addon scaffold in `parentDir/<name>`. Returns the paths of the
+ * files created (absolute). Throws when the target directory already exists.
+ */
+export declare function createAddonScaffold(name: string, parentDir: string, lang: 'js' | 'ts'): string[];
+//# sourceMappingURL=init-template.d.ts.map

package/dist/addons/init-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-template.d.ts","sourceRoot":"","sources":["../../src/addons/init-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4OH;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,IAAI,GAAG,IAAI,GAChB,MAAM,EAAE,CA2BV"}

package/dist/addons/init-template.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * Addon scaffold generator (`homegraph addon init`).
+ *
+ * Produces a publishable npm package skeleton with the `homegraph` marker,
+ * an `enrich` stub, and a worked Jira example (parse ticket refs → fetch
+ * details → return supplements).
+ *
+ * @module addons/init-template
+ */
+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.createAddonScaffold = createAddonScaffold;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function packageJson(name, lang) {
+    const entry = lang === 'ts' ? './dist/index.js' : './index.mjs';
+    return JSON.stringify({
+        name,
+        version: '0.1.0',
+        description: 'HomeGraph addon: enrich spec-mine prompts with external requirement data',
+        type: 'module',
+        exports: { '.': entry },
+        files: lang === 'ts' ? ['dist', 'examples'] : ['index.mjs', 'examples'],
+        scripts: lang === 'ts' ? { build: 'tsc' } : undefined,
+        // TypeScript needs the homegraph type declarations to compile.
+        devDependencies: lang === 'ts' ? { homegraph: 'latest' } : undefined,
+        homegraph: { addon: true, api: 1 },
+    }, null, 2) + '\n';
+}
+function tsconfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            outDir: 'dist',
+            declaration: true,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ['index.ts'],
+    }, null, 2) + '\n';
+}
+/** Shared body of the enrich stub — identical for JS and TS. */
+function enrichBody() {
+    return `  const supplements = [];
+  for (const commit of input.commits) {
+    const match = /([A-Z]+-\\d+)/.exec(commit.commitMessage);
+    if (match) {
+      supplements.push({
+        key: match[1],
+        text: \`Requirement \${match[1]}: replace this with fetched details.\`,
+        commitHash: commit.commitHash,
+      });
+    }
+  }
+  return supplements;
+`;
+}
+function indexSource(name, lang) {
+    const head = `/**
+ * ${name} — HomeGraph spec-mine addon.
+ *
+ * Contract (api 1) — implement at least one hook:
+ *   - enrich(input):      add external requirement context (e.g. Jira) as
+ *                         supplements; HomeGraph dedupes by \`key\` and renders
+ *                         them into a "## Supplement" prompt section.
+ *   - buildPrompt(ctx):   optional escape hatch that takes over the whole
+ *                         prompt assembly (see ctx.limits — a soft contract).
+ *
+ * Data shapes (all passed in — you never run git):
+ *
+ *   input                { clusterId, commits }
+ *   input.commits[i]     { commitHash, commitMessage, author, timestamp }
+ *     - commitMessage    first line of the commit message
+ *     - timestamp        unix seconds
+ *
+ *   Supplement           { key?, text, commitHash? }
+ *     - key              opaque dedupe id (e.g. the ticket key); without it,
+ *                        exact-text dedup is used
+ *     - text             required — the requirement description you assembled
+ *     - commitHash       optional — surfaced for traceability
+ *
+ *   buildPrompt ctx      { cluster, supplements, template, limits }
+ *     - cluster          { id, commits, primaryFiles, primarySymbols }
+ *     - supplements      already deduplicated by HomeGraph
+ *     - template         output template (default or user --template)
+ *     - limits           { maxContextChars, maxSupplementChars } — soft
+ *                        contract you are expected to honor
+ *
+ * Return one Supplement per requirement. Both hooks are optional but at
+ * least one must be implemented.
+`;
+    if (lang === 'ts') {
+        return (`import type { EnrichInput, Supplement } from 'homegraph';\n\n` +
+            head +
+            ` */\n\n` +
+            `export async function enrich(input: EnrichInput): Promise<Supplement[]> {\n` +
+            enrichBody() +
+            `}\n`);
+    }
+    return (head +
+        ` * @param {import('homegraph').EnrichInput} input - one commit cluster.
+ * @returns {Promise<import('homegraph').Supplement[]>}
+ */
+
+export async function enrich(input) {
+` +
+        enrichBody() +
+        `}
+`);
+}
+const JIRA_EXAMPLE = `// Worked example: fetch requirement details from Jira and render them as
+// supplements. Standalone — drop this file into any addon's examples/ dir.
+//
+// Data shapes (enrich input / Supplement / buildPrompt ctx): see the
+// contract comment at the top of index.mjs.
+//
+//   const JIRA_BASE = process.env.JIRA_BASE_URL ?? 'https://your-domain.atlassian.net';
+//   const JIRA_EMAIL = process.env.JIRA_EMAIL ?? '';
+//   const JIRA_TOKEN = process.env.JIRA_API_TOKEN ?? '';
+//   const TICKET_RE = /([A-Z]+-\\d+)/g;
+
+export async function enrich(input) {
+  const seen = new Set();
+  const supplements = [];
+  for (const commit of input.commits) {
+    for (const match of commit.commitMessage.matchAll(TICKET_RE)) {
+      const key = match[1];
+      if (seen.has(key)) continue; // dedupe across commits in the cluster
+      seen.add(key);
+      supplements.push({ key, text: await fetchTicket(key), commitHash: commit.commitHash });
+    }
+  }
+  return supplements;
+}
+
+async function fetchTicket(key) {
+  if (!JIRA_TOKEN) return \`\${key}: set JIRA_API_TOKEN to fetch details.\`;
+  const res = await fetch(\`\${JIRA_BASE}/rest/api/3/issue/\${key}\`, {
+    headers: { Authorization: 'Basic ' + btoa(JIRA_EMAIL + ':' + JIRA_TOKEN) },
+  });
+  if (!res.ok) return \`\${key}: fetch failed (\${res.status}).\`;
+  const issue = await res.json();
+  const summary = issue.fields?.summary ?? '(no summary)';
+  const description = issue.fields?.description ?? '';
+  return \`\${key} — \${summary}\\n\${description}\`;
+}
+`;
+const BUILD_PROMPT_EXAMPLE = `// buildPrompt example — the optional escape hatch that takes over the whole
+// prompt assembly. Copy it into index.mjs (or re-export it). When an addon
+// implements both hooks, buildPrompt wins for assembly while enrich still
+// runs first — its supplements reach you via ctx.supplements.
+//
+// Input  ctx: { cluster, supplements, template, limits }
+//   - cluster:     { id, commits, primaryFiles, primarySymbols }
+//   - supplements: already deduplicated by HomeGraph
+//   - template:    output template (default or user --template)
+//   - limits:      { maxContextChars, maxSupplementChars } — soft contract
+// Output: the full user prompt string. Throwing falls back to the default
+// assembler, so you can experiment freely.
+export async function buildPrompt(ctx) {
+  const { cluster, supplements, template } = ctx;
+
+  // Your own section first, then the built-in structure.
+  const supplementLines = supplements.map(
+    (s) => \`- \${s.text}\${s.commitHash ? \` (commit \${s.commitHash.slice(0, 7)})\` : ''}\`,
+  );
+
+  return [
+    supplements.length > 0 ? '## Supplement' : null,
+    ...(supplements.length > 0 ? supplementLines : []),
+    '',
+    \`## Cluster Context — \${cluster.commits.length} commits\`,
+    \`Primary files: \${cluster.primaryFiles.join(', ') || '(none)'}\`,
+    \`Primary symbols: \${cluster.primarySymbols.join(', ') || '(none)'}\`,
+    '',
+    '---',
+    '',
+    'Fill in this template:',
+    '',
+    template,
+  ]
+    .filter(Boolean)
+    .join('\\n');
+}
+`;
+const README = `# HomeGraph Addon
+
+A pluggable extension for \`homegraph spec mine\`: enrich cluster prompts with
+external requirement context (Jira, internal trackers, APIs) without
+HomeGraph knowing any ticket format.
+
+## Contract (api 1)
+
+- \`enrich(input)\` → \`Supplement[]\`
+  - \`input\`: \`{ clusterId, commits }\` — HomeGraph passes every commit it
+    already knows, never re-runs git.
+  - \`input.commits[i]\`: \`{ commitHash, commitMessage, author, timestamp }\`
+    (commitMessage is the first line; timestamp is unix seconds).
+  - Return one \`Supplement\` per requirement:
+    - \`key\` (optional): opaque dedupe id (e.g. the ticket key); without it,
+      exact-text dedup is used.
+    - \`text\` (required): the requirement description you assembled
+      (title / URL / body all fine).
+    - \`commitHash\` (optional): surfaced for traceability.
+  - HomeGraph renders supplements into a \`## Supplement\` prompt section.
+- \`buildPrompt(ctx)\` (optional escape hatch) — takes over prompt assembly
+  entirely. \`ctx\`: \`{ cluster, supplements, template, limits }\`
+  - \`cluster\`: \`{ id, commits, primaryFiles, primarySymbols }\`
+  - \`supplements\`: already deduplicated by HomeGraph.
+  - \`template\`: the output template (default or user \`--template\`).
+  - \`limits\`: \`{ maxContextChars, maxSupplementChars }\` — a soft contract
+    you are expected to honor.
+
+Implement at least one hook. The \`homegraph\` field in package.json must
+declare \`{ "addon": true, "api": 1 }\`.
+
+## Local usage
+
+    homegraph addon install ./path/to/this/addon
+
+See \`examples/jira.mjs\` for enrich and \`examples/build-prompt.mjs\` for prompt assembly.
+`;
+/**
+ * Create the addon scaffold in `parentDir/<name>`. Returns the paths of the
+ * files created (absolute). Throws when the target directory already exists.
+ */
+function createAddonScaffold(name, parentDir, lang) {
+    const addonDir = path.join(parentDir, name);
+    if (fs.existsSync(addonDir)) {
+        throw new Error(`Directory already exists: ${addonDir}`);
+    }
+    const files = {
+        'package.json': packageJson(name, lang),
+        README: README,
+        'examples/jira.mjs': JIRA_EXAMPLE,
+        'examples/build-prompt.mjs': BUILD_PROMPT_EXAMPLE,
+    };
+    if (lang === 'ts') {
+        files['tsconfig.json'] = tsconfig();
+        files['index.ts'] = indexSource(name, lang);
+    }
+    else {
+        files['index.mjs'] = indexSource(name, lang);
+    }
+    const created = [];
+    for (const [rel, content] of Object.entries(files)) {
+        const filePath = path.join(addonDir, rel);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, content, 'utf-8');
+        created.push(filePath);
+    }
+    return created;
+}
+//# sourceMappingURL=init-template.js.map

package/dist/addons/init-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-template.js","sourceRoot":"","sources":["../../src/addons/init-template.ts"],"names":[],"mappings":"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"}

package/dist/addons/loader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime addon loading.
+ *
+ * Deterministic lookup, never a directory scan: read the registry
+ * (`addons.json`), then for each enabled entry resolve its install directory
+ * by name and validate + import it. Missing / invalid / disabled entries are
+ * skipped with a warning — a broken addon must never break the host flow.
+ *
+ * @module addons/loader
+ */
+import { LoadedAddon } from './types';
+/**
+ * Load all enabled, registered addons for a repository, in registry order.
+ * Registry order is the deterministic priority order for consumers that need
+ * one winner (e.g. `buildPrompt`).
+ */
+export declare function loadAddons(repoRoot: string): Promise<LoadedAddon[]>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/addons/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/addons/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAiCzE"}

package/dist/addons/loader.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Runtime addon loading.
+ *
+ * Deterministic lookup, never a directory scan: read the registry
+ * (`addons.json`), then for each enabled entry resolve its install directory
+ * by name and validate + import it. Missing / invalid / disabled entries are
+ * skipped with a warning — a broken addon must never break the host flow.
+ *
+ * @module addons/loader
+ */
+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.loadAddons = loadAddons;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const errors_1 = require("../errors");
+const registry_1 = require("./registry");
+const paths_1 = require("./paths");
+const validate_1 = require("./validate");
+/**
+ * Load all enabled, registered addons for a repository, in registry order.
+ * Registry order is the deterministic priority order for consumers that need
+ * one winner (e.g. `buildPrompt`).
+ */
+async function loadAddons(repoRoot) {
+    const registry = (0, registry_1.readRegistry)(repoRoot);
+    const out = [];
+    for (const entry of registry.addons) {
+        if (!entry.enabled)
+            continue;
+        const pkgDir = (0, paths_1.addonPkgDir)(repoRoot, entry.name);
+        if (!fs.existsSync(path.join(pkgDir, 'package.json'))) {
+            (0, errors_1.logWarn)(`Addon ${entry.name} is registered but not installed — skipping`, {
+                repoRoot,
+                name: entry.name,
+            });
+            continue;
+        }
+        const validation = await (0, validate_1.validateAddonPackage)(pkgDir);
+        if (!validation.ok) {
+            (0, errors_1.logWarn)(`Addon ${entry.name} failed validation — skipping`, {
+                name: entry.name,
+                reason: validation.reason,
+            });
+            continue;
+        }
+        out.push({
+            name: entry.name,
+            version: validation.version ?? entry.version,
+            module: validation.module,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=loader.js.map

package/dist/addons/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/addons/loader.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeH,gCAiCC;AA9CD,uCAAyB;AACzB,2CAA6B;AAC7B,sCAAoC;AACpC,yCAA0C;AAC1C,mCAAsC;AACtC,yCAAkD;AAGlD;;;;GAIG;AACI,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,MAAM,QAAQ,GAAG,IAAA,uBAAY,EAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,GAAG,GAAkB,EAAE,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,SAAS;QAE7B,MAAM,MAAM,GAAG,IAAA,mBAAW,EAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YACtD,IAAA,gBAAO,EAAC,SAAS,KAAK,CAAC,IAAI,6CAA6C,EAAE;gBACxE,QAAQ;gBACR,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,IAAA,+BAAoB,EAAC,MAAM,CAAC,CAAC;QACtD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,IAAA,gBAAO,EAAC,SAAS,KAAK,CAAC,IAAI,+BAA+B,EAAE;gBAC1D,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO;YAC5C,MAAM,EAAE,UAAU,CAAC,MAAO;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}