@nockdev/hsa 1.0.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +96 -44
  2. package/dist/hsa-cli.bundle.js +1 -1
  3. package/dist/hsa-daemon.bundle.js +1 -1
  4. package/dist/hsa-http.bundle.js +1 -1
  5. package/dist/hsa-lib.bundle.js +1 -1
  6. package/dist/integrity.json +88 -82
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,67 +1,119 @@
1
- # @nockdev/hsa
1
+ <p align="center">
2
+ <img src="https://capsule-render.vercel.app/api?type=waving&color=0:0F172A,50:059669,100:10B981&height=160&section=header&text=HSA%20MCP%20Server&fontSize=36&fontColor=FFFFFF&animation=fadeIn&fontAlignY=35&desc=Hierarchical%20Semantic%20Analysis%20for%20AI%20Code%20Agents&descAlignY=55&descSize=14" width="100%" />
3
+ </p>
2
4
 
3
- > **HSA — Hierarchical Semantic Analysis** MCP Server for AI Code Agents
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@nockdev/hsa"><img src="https://img.shields.io/npm/v/@nockdev/hsa?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837&color=000000" alt="npm" /></a>
7
+ <img src="https://img.shields.io/badge/MCP%20tools-13-10B981?style=for-the-badge&logo=puzzle&logoColor=white" alt="MCP Tools" />
8
+ <img src="https://img.shields.io/badge/engine-Rust%20Native-EF4444?style=for-the-badge&logo=rust&logoColor=white" alt="Rust" />
9
+ <img src="https://img.shields.io/badge/node-%E2%89%A518-3B82F6?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js" />
10
+ <img src="https://img.shields.io/badge/license-MIT-8B5CF6?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="License" />
11
+ </p>
4
12
 
5
- [![npm version](https://img.shields.io/npm/v/@nockdev/hsa.svg)](https://www.npmjs.com/package/@nockdev/hsa)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
13
+ <p align="center">
14
+ Token-optimized context engine with <b>BM25 search</b>, <b>Merkle tree</b> change detection, <b>semantic caching</b>, and <b>web dashboard</b>.
15
+ </p>
7
16
 
8
- Token-optimized context management with BM25 search, Merkle tree change detection, and semantic caching.
17
+ ---
9
18
 
10
- ## Quick Start
19
+ ## ⚡ Quick Start
11
20
 
12
21
  ```bash
13
- # Run as MCP server (stdio)
22
+ # Via nock-cli (recommended)
23
+ nock awf hsa start
24
+
25
+ # Or run standalone via npx
14
26
  npx -y @nockdev/hsa@latest
15
27
 
16
- # Or install as nock-cli plugin
28
+ # Or install as plugin
17
29
  nock plugins install @nockdev/hsa
18
- nock hsa start
19
30
  ```
20
31
 
21
- ## Features
32
+ ---
33
+
34
+ ## ✨ Features
35
+
36
+ | Feature | Description |
37
+ | :------------------- | :----------------------------------------------------------- |
38
+ | 🔍 **BM25 Search** | Full-text search across project files with ranked results |
39
+ | 🌳 **Merkle Tree** | O(log n) change detection — instant diff for large codebases |
40
+ | 🎯 **Token Budget** | Smart truncation within configurable token limits |
41
+ | 💾 **LRU Cache** | Semantic caching for repeated queries with TTL |
42
+ | 🔒 **Integrity** | SHA-256 tamper detection across 234 files |
43
+ | 🖥️ **Daemon Mode** | Background process with HTTP transport |
44
+ | 🔑 **OAuth 2.1** | JWT/API key authentication for HTTP mode |
45
+ | ⚡ **Native Engine** | Rust-powered via napi-rs (10–100x faster) |
46
+ | 🧠 **Skill Search** | BM25 index across 82 skill patterns |
47
+ | 📊 **Web Dashboard** | Real-time monitoring at `localhost:13100/dashboard` |
48
+
49
+ ---
50
+
51
+ ## 🛠️ MCP Tools (13)
52
+
53
+ | Tool | Description |
54
+ | :----------------------- | :------------------------------------- |
55
+ | `hsa_get_context` | Retrieve optimized context for LLM |
56
+ | `hsa_detect_stack` | Detect project tech stack |
57
+ | `hsa_get_agent_config` | Load commands, personas, rules, skills |
58
+ | `hsa_check_changes` | Check file changes via Merkle diff |
59
+ | `hsa_prefetch` | Prefetch context for predicted queries |
60
+ | `hsa_status` | Engine health and cache stats |
61
+ | `hsa_search_skills` | BM25 search across 82 skill patterns |
62
+ | `hsa_get_snapshot` | Project structure snapshot |
63
+ | `hsa_get_repo_map` | Repository structure map |
64
+ | `hsa_export` | Export context as portable format |
65
+ | `hsa_detect_environment` | Detect runtime environment |
66
+ | `hsa_prepare_handoff` | Prepare context for agent handoff |
67
+ | `hsa_filter_tools` | Filter available tools by context |
68
+
69
+ ---
70
+
71
+ ## ⚙️ Engine Tiers
22
72
 
23
- - 🔍 **BM25 Search** — Full-text search across project files
24
- - 🌳 **Merkle Tree** — O(log n) change detection
25
- - 🎯 **Token Budget** — Smart truncation within token limits
26
- - 💾 **LRU Cache** — Semantic caching for repeated queries
27
- - 🔒 **Integrity** — SHA-256 tamper detection
28
- - 🖥️ **Daemon Mode** — Background process with HTTP transport
29
- - 🔑 **OAuth 2.1** — JWT/API key authentication for HTTP mode
30
- - ⚡ **Native Engine** — Rust-powered via napi-rs (10-100x faster)
73
+ | Tier | Engine | Speed | Requirement |
74
+ | :--: | :-------------------- | :------- | :-------------- |
75
+ | ⚡ 1 | Native (Rust/napi-rs) | 10–100x | Platform binary |
76
+ | 🔄 2 | WASM | 2–5x | WASM runtime |
77
+ | 📋 3 | Pure TypeScript | Baseline | Always works |
31
78
 
32
- ## MCP Tools
79
+ Auto-selects the best available engine with graceful degradation.
33
80
 
34
- | Tool | Description |
35
- | ------------------- | -------------------------------------- |
36
- | `hsa_get_context` | Retrieve optimized context for LLM |
37
- | `hsa_detect_stack` | Detect project tech stack |
38
- | `hsa_check_changes` | Check file changes via Merkle diff |
39
- | `hsa_prefetch` | Prefetch context for predicted queries |
40
- | `hsa_status` | Engine health and cache stats |
81
+ ---
41
82
 
42
- ## Engine Tiers
83
+ ## 🖥️ Web Dashboard
43
84
 
44
- | Tier | Engine | Speed | Requirement |
45
- | ---- | --------------------- | -------- | --------------- |
46
- | ⚡ 1 | Native (Rust/napi-rs) | 10-100x | Platform binary |
47
- | 🔄 2 | WASM | 2-5x | WASM runtime |
48
- | 📋 3 | Pure TS (fallback) | Baseline | Always works |
85
+ ```bash
86
+ nock awf hsa start # Dashboard at http://localhost:13100/dashboard
87
+ ```
49
88
 
50
- Auto-selects the best available engine with graceful degradation.
89
+ | Page | Description |
90
+ | :----------- | :----------------------------------------------------- |
91
+ | `/dashboard` | Real-time project stats, cache metrics, indexed skills |
92
+ | `/logs` | Tool call history, search queries, performance traces |
93
+
94
+ ---
95
+
96
+ ## 🔧 Environment Variables
97
+
98
+ | Variable | Default | Description |
99
+ | :----------------------- | :------ | :------------------------------------------- |
100
+ | `HSA_PROJECT_PATH` | `.` | Project root path |
101
+ | `HSA_MAX_TOKENS` | `8000` | Maximum token budget |
102
+ | `HSA_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
103
+ | `HSA_DAEMON_PORT` | `13100` | HTTP port for daemon mode |
104
+ | `HSA_CACHE_TTL` | `300` | Cache TTL in seconds |
105
+ | `HSA_MAX_INDEXED_SKILLS` | `10` | Maximum concurrent indexed skills |
51
106
 
52
- ## Environment Variables
107
+ ---
53
108
 
54
- | Variable | Default | Description |
55
- | ------------------ | ------- | -------------------- |
56
- | `HSA_PROJECT_PATH` | `.` | Project root path |
57
- | `HSA_MAX_TOKENS` | `8000` | Maximum token budget |
58
- | `HSA_LOG_LEVEL` | `info` | Log level |
59
- | `HSA_DAEMON_PORT` | `13100` | HTTP port for daemon |
109
+ ## 📋 Requirements
60
110
 
61
- ## Requirements
111
+ - **Node.js** ≥ 18.0.0
62
112
 
63
- - Node.js ≥ 18.0.0
113
+ ## 📄 License
64
114
 
65
- ## License
115
+ MIT © [**NockDev**](https://github.com/nockasdd)
66
116
 
67
- MIT © NockDev
117
+ <p align="center">
118
+ <img src="https://capsule-render.vercel.app/api?type=waving&color=0:10B981,50:059669,100:0F172A&height=100&section=footer" width="100%" />
119
+ </p>