@precisionutilityguild/liquid-shadow 1.0.2 → 1.0.3
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.
- package/README.md +69 -144
- package/dist/data/migrations/008_crystallization.sql +13 -0
- package/dist/data/migrations/009_intent_vectors.sql +8 -0
- package/dist/entry/cli/index.js +485 -200
- package/dist/entry/mcp/server.js +194 -166
- package/dist/index.js +60 -48
- package/dist/logic/domain/embeddings/worker.js +1 -1
- package/dist/logic/parser/index.js +36 -0
- package/dist/logic/parser/worker.js +1 -0
- package/dist/web-manifest.json +29 -23
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,194 +1,119 @@
|
|
|
1
1
|
# 🌑 Liquid Shadow
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<b>Tactical Repository Intelligence Operative - The AI-First Intelligence Layer</b><br>
|
|
5
|
+
<i>Transform your codebase into a high-signal knowledge graph built for reasoning.</i>
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<img src="https://img.shields.io/badge/version-1.0.3-blue.svg" alt="Version">
|
|
10
|
+
<img src="https://img.shields.io/badge/License-Proprietary-red.svg" alt="License">
|
|
11
|
+
<img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build">
|
|
12
|
+
<img src="https://img.shields.io/badge/MCP-First-6D28D9.svg" alt="MCP First">
|
|
13
|
+
</p>
|
|
10
14
|
|
|
11
15
|
---
|
|
12
16
|
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
Liquid Shadow is primarily an **MCP (Model Context Protocol) Server**. It is the bridge between your reasoning engine and the raw filesystem.
|
|
17
|
+
## The AI-Native Intelligence OS
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
**Liquid Shadow** is the primary bridge between your reasoning engine and the raw filesystem. It doesn't just "index" code; it builds a **Relational Intelligence Graph** that allows AI agents to navigate, reason about, and modify large-scale repositories with surgical precision and extreme token efficiency.
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
# General use (CLI)
|
|
23
|
-
npx @precisionutilityguild/liquid-shadow [command]
|
|
24
|
-
```
|
|
21
|
+
Stop forcing your agents to grep through files. Give them the ability to "feel" the architecture through topological maps and execution flows.
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
---
|
|
27
24
|
|
|
28
|
-
|
|
25
|
+
## Product Pillars
|
|
29
26
|
|
|
30
|
-
|
|
31
|
-
{
|
|
32
|
-
"mcpServers": {
|
|
33
|
-
"liquid-shadow": {
|
|
34
|
-
"command": "npx",
|
|
35
|
-
"args": ["-y", "@precisionutilityguild/liquid-shadow", "liquid-shadow-mcp"]
|
|
36
|
-
}
|
|
37
|
-
}
|
|
38
|
-
}
|
|
39
|
-
```
|
|
27
|
+
### Semantic Sieve & Token Efficiency
|
|
40
28
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Once connected, your agent should follow the **Intelligence Lifecycle**:
|
|
44
|
-
|
|
45
|
-
```typescript
|
|
46
|
-
// 🛡️ RECON: Initialize the intelligence index
|
|
47
|
-
shadow_recon_onboard({ repoPath: '.' });
|
|
48
|
-
shadow_sync_trace({ repoPath: '.' });
|
|
49
|
-
|
|
50
|
-
// 📦 SESSION CONTEXT (one call): hologram + chronicle(5) + briefing
|
|
51
|
-
shadow_ops_context({ repoPath: '.' });
|
|
52
|
-
|
|
53
|
-
// PLAN: Establish the tactical mission
|
|
54
|
-
shadow_ops_plan({
|
|
55
|
-
repoPath: '.',
|
|
56
|
-
name: 'Auth Refactor',
|
|
57
|
-
goal: 'Migrate JWT logic to Session-based auth',
|
|
58
|
-
});
|
|
59
|
-
|
|
60
|
-
// ANALYZE: Trace the execution flow
|
|
61
|
-
shadow_analyze_flow({
|
|
62
|
-
repoPath: '.',
|
|
63
|
-
filePath: 'src/auth/handler.ts',
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
// LOG: Save architectural decisions (SIGINT)
|
|
67
|
-
shadow_ops_log({
|
|
68
|
-
missionId: 1,
|
|
69
|
-
repoPath: '.',
|
|
70
|
-
type: 'decision',
|
|
71
|
-
content: 'Selected Redis for session storage due to latency requirements',
|
|
72
|
-
});
|
|
73
|
-
```
|
|
29
|
+
Context is the most expensive resource. Our **Semantic Sieve** intelligently folds implementation details, revealing only the signatures and intent your agent needs. With **Briefing Zoom Levels** (`Orbit`, `Atmosphere`, `Ground`), you control exactly how many tokens are consumed based on the task's altitude.
|
|
74
30
|
|
|
75
|
-
|
|
31
|
+
### Nano-Repair & Structural Stability
|
|
76
32
|
|
|
77
|
-
|
|
33
|
+
Repositories are liquid. Code moves, files are renamed, and dependencies shift. **Nano-Repair** auto-heals your intelligence index in real-time, ensuring that "intent links" and architectural context survive even the most aggressive refactors.
|
|
78
34
|
|
|
79
|
-
|
|
35
|
+
### Mission-Driven Development
|
|
80
36
|
|
|
81
|
-
|
|
82
|
-
| :--------------- | :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
|
|
83
|
-
| **Ops Control** | `shadow_ops_plan`, `_track`, `_briefing`, `_context`, `_log`, `_synthesize`, `_chronicle`, `_health`, `_graph` | Mission management, ADR synthesis; **`_context`** = session start (hologram + chronicle + briefing in one call). |
|
|
84
|
-
| **Intelligence** | `shadow_analyze_impact`, `_flow`, `_deps`, `_debt` | Deep architectural reasoning and dependency tracing. |
|
|
85
|
-
| **Discovery** | `shadow_search_concept`, `_symbol`, `_config`, `_path` | Semantic and lexical search across the entire graph. |
|
|
86
|
-
| **Recon** | `shadow_recon_onboard`, `_tree`, `_hologram`, `_topography`, `_scout` | Structural analysis and layer classification. |
|
|
87
|
-
| **Inspection** | `shadow_inspect_symbol`, `_file` | Dense code retrieval with semantic folding. |
|
|
88
|
-
| **Maintenance** | `shadow_sync_trace`, `_index`, `_repair` | Intelligence synchronization and Nano-Repair. |
|
|
89
|
-
| **Workspace** | `shadow_workspace_list`, `_link`, `_fuse` | Multi-repository mission linking and index fusion. |
|
|
90
|
-
| **Environment** | `shadow_env_hooks`, `_diagnose` | Git hook automation and system health diagnostics. |
|
|
37
|
+
We treat development as a series of tactical **Missions**. Liquid Shadow records every architectural decision (ADR), discovery, and blocker as it happens, creating a persistent "Chronome" of project narrative that persists across sessions.
|
|
91
38
|
|
|
92
|
-
###
|
|
39
|
+
### Relational Impact Analysis
|
|
93
40
|
|
|
94
|
-
|
|
95
|
-
| -------------------------------------------------- | -------- | ------------- | ------------------------ |
|
|
96
|
-
| See**ALL exports** from a file | `file` | `detailLevel` | `"signatures"` (default) |
|
|
97
|
-
| See**ONE specific symbol** (truncated) | `symbol` | `context` | `"definition"` (default) |
|
|
98
|
-
| See**ONE specific symbol** + dependencies + usages | `symbol` | `context` | `"full"` |
|
|
99
|
-
| Just export names (minimal tokens) | `file` | `detailLevel` | `"structure"` |
|
|
41
|
+
Change one function, see the ripple. Trace execution flows and predict the **Blast Radius** of any modification across repository boundaries using our cross-repo fusion engine.
|
|
100
42
|
|
|
101
43
|
---
|
|
102
44
|
|
|
103
|
-
##
|
|
104
|
-
|
|
105
|
-
Liquid Shadow is optimized for ultra-fast indexing and semantic retrieval. Performance is benchmarked against enterprise-grade repositories.
|
|
45
|
+
## The Tactical Suite (31 Atomic Tools)
|
|
106
46
|
|
|
107
|
-
|
|
47
|
+
Organized into specialized intelligence suites for the modern agent:
|
|
108
48
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
49
|
+
| Suite | Tactical Purpose | Key Tools |
|
|
50
|
+
| :--------------- | :------------------------------ | :------------------------------------------------- |
|
|
51
|
+
| **Ops Control** | Mission & context management | `shadow_ops_context`, `shadow_ops_briefing` |
|
|
52
|
+
| **Intelligence** | Deep architectural reasoning | `shadow_analyze_impact`, `shadow_analyze_flow` |
|
|
53
|
+
| **Discovery** | Semantic & config retrieval | `shadow_search_concept`, `shadow_search_config` |
|
|
54
|
+
| **Recon** | Structural layer classification | `shadow_recon_topography`, `shadow_recon_hologram` |
|
|
55
|
+
| **Inspection** | Token-optimized code folding | `shadow_inspect_symbol`, `shadow_inspect_file` |
|
|
56
|
+
| **Maintenance** | Intelligence synchronization | `shadow_sync_trace`, `shadow_sync_repair` |
|
|
115
57
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- **Total Files**: 6,196 files
|
|
119
|
-
- **Symbols Extracted**: 109,997 symbols (with deep closure indexing)
|
|
120
|
-
- **Index Time**: 116.6s (Fresh start)
|
|
121
|
-
- **Throughput**: ~53 files/sec
|
|
122
|
-
- **Symbols/sec**: ~943 symbols/sec
|
|
123
|
-
- **Scalability**: Verified 100k+ symbol graph support
|
|
124
|
-
|
|
125
|
-
### High-Volume Benchmark (Next.js)
|
|
58
|
+
---
|
|
126
59
|
|
|
127
|
-
|
|
128
|
-
- **Symbols Extracted**: 20,701 symbols (with deep closure indexing)
|
|
129
|
-
- **Index Time**: 24.2s (Fresh start)
|
|
130
|
-
- **Throughput**: ~404 files/sec
|
|
131
|
-
- **Symbols/sec**: ~855 symbols/sec
|
|
60
|
+
## The Intelligence Lifecycle
|
|
132
61
|
|
|
133
|
-
|
|
62
|
+
Liquid Shadow is designed to be the first point of contact for any agent entering a workspace.
|
|
134
63
|
|
|
135
|
-
|
|
64
|
+
### 1. Installation (Safe Init)
|
|
136
65
|
|
|
137
66
|
```bash
|
|
138
|
-
|
|
67
|
+
npm install -g @precisionutilityguild/liquid-shadow
|
|
68
|
+
liquid-shadow init # Interactive security confirmation
|
|
139
69
|
```
|
|
140
70
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
## Configuration
|
|
144
|
-
|
|
145
|
-
### Indexing Concurrency
|
|
71
|
+
### 2. Operational Dashboard (TUI)
|
|
146
72
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
**Environment Variable** (Global):
|
|
73
|
+
Keep a finger on the pulse of your repository's intelligence. Liquid Shadow provides a high-signal Terminal UI for a bird's-eye view of your mapping density and performance.
|
|
150
74
|
|
|
151
75
|
```bash
|
|
152
|
-
|
|
76
|
+
liquid-shadow dashboard
|
|
153
77
|
```
|
|
154
78
|
|
|
155
|
-
|
|
156
|
-
Add to `.liquid-shadow.yaml`:
|
|
79
|
+
> **Scouting Report**: Need a quick status instead? Run `liquid-shadow status`.
|
|
157
80
|
|
|
158
|
-
|
|
159
|
-
concurrency: 10 # Overrides INDEX_CONCURRENCY for this repo
|
|
160
|
-
```
|
|
81
|
+
### 3. The Skills-First Loop
|
|
161
82
|
|
|
162
|
-
**
|
|
83
|
+
Liquid Shadow is designed for **Autonomy**. While it provides 31 atomic tools, the primary interface for an agent is the **Skills** system. Running `liquid-shadow init` automatically injects these high-level workflows into the agent's environment.
|
|
163
84
|
|
|
164
|
-
|
|
165
|
-
- **Standard systems**: 5-10
|
|
166
|
-
- **High-memory systems**: 10-20
|
|
167
|
-
- **Very large repos**: Monitor memory usage and adjust accordingly
|
|
85
|
+
#### High-Signal Workflows
|
|
168
86
|
|
|
169
|
-
|
|
87
|
+
Instead of guessing which tools to call, agents follow optimized **Tactical Skills**:
|
|
170
88
|
|
|
171
|
-
|
|
89
|
+
- **/onboard**: Build the baseline index and topography.
|
|
90
|
+
- **/understand**: Concept-to-code mapping and execution tracing.
|
|
91
|
+
- **/mission**: Strategic planning and automated ADR synthesis.
|
|
92
|
+
- **/trace-impact**: Predict blast radius and dependency ripple effects.
|
|
93
|
+
- **/audit**: Detect technical debt, circular deps, and dead code.
|
|
172
94
|
|
|
173
|
-
|
|
95
|
+
#### Example: Agent Strategy Flow
|
|
174
96
|
|
|
175
|
-
|
|
97
|
+
```markdown
|
|
98
|
+
// 1. RECON: The agent reads the Skill definition
|
|
99
|
+
view_file({ path: '.agent/skills/onboard/SKILL.md' });
|
|
176
100
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
101
|
+
// 2. ACT: Following the Skill, the agent orchestrates the tools
|
|
102
|
+
shadow_recon_onboard({ repoPath: '/abs/path' });
|
|
103
|
+
shadow_ops_context({ repoPath: '/abs/path' });
|
|
104
|
+
shadow_env_hooks({ action: 'install', repoPath: '/abs/path' });
|
|
105
|
+
```
|
|
180
106
|
|
|
181
107
|
---
|
|
182
108
|
|
|
183
|
-
##
|
|
109
|
+
## Enterprise-Grade Performance
|
|
110
|
+
|
|
111
|
+
Optimized for speed. Scalable for large codebases.
|
|
184
112
|
|
|
185
|
-
- **
|
|
186
|
-
- **
|
|
187
|
-
- **Polyglot Unity**: Unified symbol graph across TypeScript, PHP, Python, Go, and more.
|
|
188
|
-
- **Situational Awareness**: Persistent state via missions and intent logs, allowing for seamless context transitions.
|
|
189
|
-
- **Session-Start Bundle**: `shadow_ops_context` returns hologram + chronicle (last 5) + briefing in one call—ideal for "new chat, give me the world."
|
|
113
|
+
- **VS Code Core (6.1k files)**: Indexed in **110.6s** (109k+ symbols)
|
|
114
|
+
- **Next.js (9.7k files)**: Indexed in **24.2s** (~404 files/sec)
|
|
190
115
|
|
|
191
116
|
---
|
|
192
117
|
|
|
193
|
-
|
|
194
|
-
|
|
118
|
+
<p align="center">
|
|
119
|
+
<i>Powered by <b>SQLite FTS5</b>, <b>SWC</b>, and <b>Precision Intelligence</b>.</i><br>
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
-- Crystallization support for intent_logs compression
|
|
2
|
+
-- Adds fields to support summarized "crystal" nodes that replace verbose raw logs
|
|
3
|
+
|
|
4
|
+
ALTER TABLE intent_logs ADD COLUMN is_crystallized INTEGER DEFAULT 0;
|
|
5
|
+
ALTER TABLE intent_logs ADD COLUMN crystal_id INTEGER REFERENCES intent_logs(id) ON DELETE SET NULL;
|
|
6
|
+
|
|
7
|
+
CREATE INDEX IF NOT EXISTS idx_intent_crystal ON intent_logs(crystal_id);
|
|
8
|
+
CREATE INDEX IF NOT EXISTS idx_intent_crystallized ON intent_logs(is_crystallized);
|
|
9
|
+
|
|
10
|
+
-- DOWN
|
|
11
|
+
DROP INDEX IF EXISTS idx_intent_crystallized;
|
|
12
|
+
DROP INDEX IF EXISTS idx_intent_crystal;
|
|
13
|
+
-- SQLite does not support DROP COLUMN; columns remain but are unused after rollback
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
-- Intent Vectors: Add embedding support to intent_logs for semantic search
|
|
2
|
+
|
|
3
|
+
ALTER TABLE intent_logs ADD COLUMN embedding TEXT DEFAULT NULL;
|
|
4
|
+
|
|
5
|
+
CREATE INDEX IF NOT EXISTS idx_intent_embedding ON intent_logs(id) WHERE embedding IS NOT NULL;
|
|
6
|
+
|
|
7
|
+
-- DOWN
|
|
8
|
+
DROP INDEX IF EXISTS idx_intent_embedding;
|