62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# @hive-mind/shim-core
|
|
|
|
Foundation utilities for the [hive-mind-clients](https://github.com/marolinik/hive-mind-clients) cross-IDE silent capture shim portfolio.
|
|
|
|
This package is shared by every per-IDE shim (`@hive-mind/claude-code-hooks`, `@hive-mind/cursor-hooks`, etc.). It exposes typed interfaces, deterministic helpers, and a single CLI bridge to the hive-mind core — so each shim only has to translate IDE-native hook events into a common shape, then hand off to shim-core.
|
|
|
|
**Status**: pre-1.0, Wave 1 in development.
|
|
**Target**: Node >= 20, ESM-only.
|
|
**Peer dependency**: hive-mind-cli >= 0.1.0 (installed via `npm install -g @hive-mind/cli` or a local link).
|
|
|
|
## What's in here
|
|
|
|
| Module | Purpose |
|
|
|---|---|
|
|
| `frame-encoder` | Translate `HookEvent` -> `HookFrame` (the I/P/B-style payload that ships to hive-mind). |
|
|
| `workspace-resolver` | Pick the right `.mind` file: per-project marker if present, else `~/.hive-mind/global.mind`. |
|
|
| `cli-bridge` | The single chokepoint. Spawns `hive-mind-cli mcp call <tool> --args <json> --json` and returns typed results. |
|
|
| `hook-event-types` | Canonical `EventType`, `ShimSource`, `HookEvent` interfaces shared across shims. |
|
|
| `importance-classifier` | Pure-functional rules that map content -> `temporary` / `important` / `critical`. |
|
|
| `prompt-summarizer` | Deterministic extractive summarizer (no LLM call). Used by `Stop`-hook handlers to compress turns. |
|
|
| `retry-bridge` | Exponential backoff with jitter and per-attempt timeout. Wraps every CLI call. |
|
|
| `logger` | Zero-dep structured JSON logger. Writes to stderr so hook stdout stays clean. |
|
|
|
|
## Usage (from a shim)
|
|
|
|
```ts
|
|
import {
|
|
createCliBridge,
|
|
encodeFrame,
|
|
resolveWorkspace,
|
|
type HookEvent,
|
|
} from '@hive-mind/shim-core';
|
|
|
|
const bridge = createCliBridge();
|
|
|
|
const event: HookEvent = {
|
|
eventType: 'user-prompt-submit',
|
|
source: 'claude-code',
|
|
cwd: process.cwd(),
|
|
timestamp_iso: new Date().toISOString(),
|
|
payload: { content: 'How do I X?', session_id: 'abc-123' },
|
|
};
|
|
|
|
const workspace = await resolveWorkspace(event.cwd);
|
|
await bridge.switchWorkspace(workspace.path);
|
|
|
|
const frame = encodeFrame(event);
|
|
await bridge.saveMemory(frame);
|
|
```
|
|
|
|
## Bridge architecture
|
|
|
|
Every operation goes through one transport: `hive-mind-cli mcp call <tool> --args <json> --json --timeout-ms N`. That's a deliberate chokepoint:
|
|
|
|
- New MCP tools added upstream are reachable immediately via `bridge.callMcpTool('<new_tool>', args)`.
|
|
- Schema or arg changes in upstream MCP tools surface in one place, not 6 shims.
|
|
- Failure modes (timeout, exit non-zero, malformed JSON, `isError=true`) are normalized into thrown `Error`s by the bridge.
|
|
|
|
## License
|
|
|
|
Apache-2.0 — see [the repo root](https://github.com/marolinik/hive-mind-clients/blob/main/LICENSE) for the full text.
|