@precisionutilityguild/liquid-shadow 1.0.0

package/dist/logic/domain/embeddings/worker.js

@@ -0,0 +1 @@
+import{parentPort as i,workerData as y}from"worker_threads";import g from"pino";var p={10:"TRACE",20:"DEBUG",30:"INFO",40:"WARN",50:"ERROR",60:"FATAL"},m=g({level:process.env.LOG_LEVEL||"info",base:{service:"liquid-shadow"},formatters:{level(e,r){return{level:e,severity:p[r]??"INFO"}}},transport:{target:"pino-pretty",options:{colorize:!0,translateTime:"HH:MM:ss",destination:2,levelKey:"severity",messageKey:"message"}}}),a=m;var n=null;async function f(){return n||(n=await import("@xenova/transformers"),n.env.cacheDir=y?.cacheDir||"./.cache",n.env.allowLocalModels=!1),n}var c=null;async function M(){let{pipeline:e}=await f();c=await e("feature-extraction","Xenova/all-MiniLM-L6-v2")}async function h(e){if(e.length===0)return[];try{let r=await c(e,{pooling:"mean",normalize:!0}),[t,s]=r.dims,o=[];for(let l=0;l<t;l++){let d=l*s,u=d+s;o.push(Array.from(r.data.slice(d,u)))}return o}catch(r){a.error({err:r,batchSize:e.length},"Vectorized batch embedding failed, falling back to sequential");let t=[];for(let s of e){if(!s||s.trim().length===0){t.push(null);continue}try{let o=await c(s,{pooling:"mean",normalize:!0});t.push(Array.from(o.data))}catch{t.push(null)}}return t}}async function b(e){if(e.type==="shutdown"&&process.exit(0),e.type==="embed")try{let r=await h(e.texts),t={type:"result",id:e.id,embeddings:r};i?.postMessage(t)}catch(r){let t={type:"error",id:e.id,error:r instanceof Error?r.message:String(r)};i?.postMessage(t)}}async function v(){await M();let e={type:"ready"};i?.postMessage(e),i?.on("message",r=>{b(r).catch(t=>{a.error({error:t},"Worker error")})})}v().catch(e=>{a.error({error:e},"Failed to initialize embedding worker"),process.exit(1)});

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@precisionutilityguild/liquid-shadow",
+  "version": "1.0.0",
+  "description": "Tactical Repository Intelligence Operative - Liquid Shadow Ecosystem",
+  "homepage": "https://liquidshadow.pugcorp.online/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PrecisionUtilityGuild/liquid-shadow.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "liquid-shadow": "./dist/entry/cli/index.js",
+    "liquid-shadow-mcp": "./dist/entry/mcp/server.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./mcp": "./dist/entry/mcp/server.js",
+    "./cli": "./dist/entry/cli/index.js"
+  },
+  "imports": {
+    "#src/*.js": [
+      "./src/*.ts",
+      "./dist/*.js"
+    ],
+    "#src/*": [
+      "./src/*",
+      "./dist/*"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "dev": "tsx src/entry/cli/index.ts",
+    "mcp": "tsx src/entry/mcp/server.ts",
+    "start": "node dist/entry/cli/index.js",
+    "start-mcp": "node dist/mcp/server.js",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "format": "prettier --write .",
+    "audit": "npm audit",
+    "audit:fix": "npm audit fix",
+    "benchmark": "tsx src/entry/cli/index.ts benchmark",
+    "migrate:strategies": "tsx src/utility/migrate-strategies.ts",
+    "prepare": "npm run build",
+    "postinstall": "node -e \"console.log('\\nTo enable shell completions:\\n  bash: source <(liquid-shadow completion bash)\\n  zsh:  source <(liquid-shadow completion zsh)\\n')\""
+  },
+  "keywords": [
+    "typescript",
+    "cli",
+    "repo",
+    "summarizer",
+    "LLM",
+    "AI"
+  ],
+  "author": "Precision Utility Guild",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@swc/core": "^1.15.8",
+    "@swc/helpers": "^0.5.18",
+    "@types/node": "^25.0.8",
+    "@xenova/transformers": "^2.17.2",
+    "better-sqlite3": "^12.6.0",
+    "clerc": "^1.3.0-beta.1",
+    "dotenv": "^17.2.3",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "js-yaml": "^4.1.1",
+    "p-limit": "^7.2.0",
+    "pino": "^10.1.1",
+    "pino-pretty": "^13.1.3",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.3",
+    "web-tree-sitter": "^0.26.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "esbuild": "^0.27.2",
+    "prettier": "^3.8.1",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.18"
+  }
+}

package/skills/audit/SKILL.md

@@ -0,0 +1,29 @@
+# Comprehensive health audit using Shadow analyze toolkit.
+
+## Workflow
+
+1. **Architecture baseline**: `shadow_recon_hologram({ repoPath: "..." })` — Topography + gravity only (lighter). Use `shadow_ops_context` when you want hologram + chronicle + briefing in one call.
+2. **Metrics Check**: `ReadMcpResourceTool(server: "lish", uri: "repo://current/metrics")` — Index health, query performance.
+3. **Dead Code Detection**: `shadow_analyze_debt({ limit: 100, includeTests: false, repoPath: "..." })` — Unused exports.
+4. **Circular Dependencies**: `shadow_analyze_debt({ limit: 20, repoPath: "..." })` — Import cycles (debt tool covers circular-deps).
+5. **Layer Integrity**: `shadow_recon_topography({ repoPath: "..." })` — Check separation of concerns.
+6. **Dependency Graph**: `ReadMcpResourceTool(server: "lish", uri: "repo://current/dependency-graph")` — Full import map.
+7. **Log Findings**: `shadow_ops_log({ missionId: ..., type: "discovery", content: "...", repoPath: "..." })`.
+8. **Create Cleanup Mission** (optional): `shadow_ops_plan({ name: "Codebase Cleanup", goal: "...", repoPath: "..." })`.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Audit Target      | Tool Call                                                                                           |
+| :---------------- | :-------------------------------------------------------------------------------------------------- |
+| **Architecture**  | `shadow_recon_hologram({ repoPath })` — baseline only; `shadow_ops_context` for full session bundle |
+| **Metrics**       | `ReadMcpResourceTool(server: "lish", uri: "repo://current/metrics")`                                |
+| **Dead Code**     | `shadow_analyze_debt({ limit: 100, repoPath })`                                                     |
+| **Circular Deps** | `shadow_analyze_debt({ limit: 20, repoPath })`                                                      |
+| **Layers**        | `shadow_recon_topography({ repoPath })`                                                             |
+| **Dep Graph**     | `ReadMcpResourceTool(server: "lish", uri: "repo://current/dependency-graph")`                       |
+
+## Health Criteria
+
+- **Critical Issues**: Circular deps in core logic, >50 dead exports
+- **Warning Signs**: Layer violations (Test → Logic), >20 dead exports
+- **Good Health**: Clean layers, <10 dead exports, no circular deps

package/skills/chronicle/SKILL.md

@@ -0,0 +1,33 @@
+# Retrieve narrative archive from Git-native memory.
+
+## Workflow
+
+1. **Recent History**: `shadow_ops_chronicle({ limit: 10, format: "markdown", repoPath: "..." })` — Last 10 entries.
+2. **Time-Filtered**:
+   - `shadow_ops_chronicle({ since: 1769700000, limit: 20, repoPath: "..." })` — Unix timestamp
+   - `shadow_ops_chronicle({ until: 1769800000, limit: 20, repoPath: "..." })`
+3. **Structured Data**: `shadow_ops_chronicle({ format: "json", limit: 50, repoPath: "..." })` — For processing.
+4. **Paginated**: `shadow_ops_chronicle({ limit: 10, offset: 10, repoPath: "..." })` — Second page.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Chronicle Query       | Tool Call                                                           |
+| :-------------------- | :------------------------------------------------------------------ |
+| **Recent (Markdown)** | `shadow_ops_chronicle({ limit: 10, format: "markdown", repoPath })` |
+| **Time Range**        | `shadow_ops_chronicle({ since: <unix>, until: <unix>, repoPath })`  |
+| **JSON Data**         | `shadow_ops_chronicle({ format: "json", limit: 50, repoPath })`     |
+| **Pagination**        | `shadow_ops_chronicle({ limit: 10, offset: 10, repoPath })`         |
+
+## Output Formats
+
+- **`format: "markdown"`** (default): Human-readable narrative feed with missions grouped as Strategic Initiatives and Standalone Episodes
+- **`format: "json"`**: Structured data for programmatic analysis (includes missionId, steps, timestamps, ADRs)
+
+## Use Cases
+
+- **Onboarding**: Read last 10 entries to catch up
+- **Release Notes**: Get completed missions since last release
+- **ADR Review**: Extract all architectural decisions
+- **Progress Reports**: Show what's been done this week
+
+**Note:** Chronicle reads from Git Notes, so it's persistent across branches and clones. **Context vs this tool:** `shadow_ops_context` returns only the last 5 entries; use **this tool** when you need a different limit, time range (`since`/`until`), pagination (`offset`), or `format: "json"`.

package/skills/continue/SKILL.md

@@ -0,0 +1,44 @@
+# Get briefing (+ optional trace), pick **one mission** from **next_work_candidates**, then work that mission to completion — all remaining steps in one run. Update and log as you go. No status reports; when you're done with that mission, it's done.
+
+---
+
+## 1. Context
+
+- **One call**: `shadow_ops_context({ repoPath: "..." })` → hologram + chronicle(5) + briefing (including **next_work_candidates**). Use when you want full session context.
+- **Briefing only**: `shadow_ops_briefing({ scope: "project", includeGroupedByParent: true, repoPath: "..." })` when you already have context and only need next_work_candidates (lighter than calling context again).
+- `shadow_sync_trace({ repoPath: "..." })` only if you care about external changes. Otherwise skip.
+
+## 2. Pick one mission
+
+- Choose one mission from **next_work_candidates** (no parent-only — they're umbrellas). Prefer in-progress, then planned. That mission is your scope for this run.
+
+## 3. Work the whole mission
+
+- For that mission, run through **all remaining steps** (not just one):
+  - **Surgical Discovery:** `shadow_analyze_flow({ symbolName: "...", filePath: "...", repoPath: "..." })`.
+  - **Execute Step**: Set in-progress → implement → `shadow_ops_track({ missionId: ..., stepId: "...", status: "completed", repoPath: "..." })`.
+  - **Atomic Logging:** At least once per step. `shadow_ops_log({ missionId: ..., type: "decision", content: "...", symbolName: "...", repoPath: "..." })`.
+- When all steps are done: `shadow_ops_track({ missionId: ..., status: "completed", repoPath: "..." })`.
+- **Final Synthesis**: `shadow_ops_synthesize({ missionId: ..., repoPath: "..." })`.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Action          | Tool Call Example                                                                 |
+| :-------------- | :-------------------------------------------------------------------------------- |
+| **Context**     | `shadow_ops_context({ repoPath })` — hologram + chronicle + briefing              |
+| **Briefing**    | `shadow_ops_briefing({ scope: "project", repoPath })` — next_work_candidates only |
+| **Flow Trace**  | `shadow_analyze_flow({ symbolName: "handleRequest", repoPath })`                  |
+| **Step Update** | `shadow_ops_track({ missionId: 4, stepId: "s2", status: "completed", repoPath })` |
+| **Intent Log**  | `shadow_ops_log({ missionId: 4, type: "fix", content: "...", repoPath })`         |
+| **Seal**        | `shadow_ops_synthesize({ missionId: 4, repoPath })`                               |
+
+_Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
+
+## 4. Don't
+
+- Don't do one step and stop — /continue is "finish a mission," not "do one step."
+- Don't long status reports. Don't ask "what should I work on?" unless a real tie. Don't auto-commit.
+
+---
+
+**Tools:** shadow*ops_context (or shadow_ops_briefing), shadow_ops_track, shadow_ops_log, shadow_sync_trace. For discovery: shadow_search*_, shadow*recon*_, shadow*analyze*\*. Server: **user-lish**.

package/skills/mission/SKILL.md

@@ -0,0 +1,35 @@
+# Mission Strategy & Setup
+
+Define the objective, strategy, and success criteria for a new mission. This workflow is for **Strategic Alignment and Planning**.
+
+> **IMPORTANT**: This workflow stops at the "Ready to Execute" state. For implementation and automated execution, use **/continue**.
+
+## Workflow
+
+1. **Session Context** (one call): `shadow_ops_context({ repoPath })` — Briefing (next_work_candidates) + chronicle(5) + hologram. Or use `shadow_ops_briefing` / `shadow_ops_chronicle` alone if you need only one.
+2. **Topological Recon**: `shadow_recon_topography({ repoPath })` — Align the goal with the target architectural layers (Entry/Logic/Data).
+3. **Strategic Plan**: `shadow_ops_plan({ name: "...", goal: "...", outcomeContract: "...", repoPath })`.
+   - **Strategy DAG**: Define logical steps and verification rules.
+   - **Initiative vs Mission**: Decide if this is a parent (Initiative) or a leaf (Mission).
+4. **Alignment**: Present the plan to the user. Do not begin execution until the user approves the strategy.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Setup Action          | Precise Tool Call                                     | Usage                                        |
+| :-------------------- | :---------------------------------------------------- | :------------------------------------------- |
+| **Establish Plan**    | `shadow_ops_plan({ repoPath })`                       | Create the mission and strategy.             |
+| **Architectural Map** | `shadow_recon_topography({ repoPath })`               | Contextualize the target layers.             |
+| **Context**           | `shadow_ops_context({ repoPath })`                    | Briefing + chronicle + hologram in one call. |
+| **Briefing only**     | `shadow_ops_briefing({ scope: "project", repoPath })` | When you need only next_work_candidates.     |
+| **Graph View**        | `shadow_ops_graph({ repoPath })`                      | Visualize the initiative's hierarchy.        |
+
+_Note: Pure Missions are about setting the destination and the route. Ensure the `outcomeContract` is binary and verifiable. Use briefing or chronicle **alone** when you already have context and need only one piece (lighter)._
+
+## Intent Logging (Strategic Quality)
+
+Capture the "Why" and "How" during the planning phase to ensure the final ADR has architectural depth.
+
+- **Decision Logs**: Capture why a specific strategy or library was chosen.
+- **Discovery Logs**: Record insights found during initial reconnaissance.
+
+**Hand-off**: Once the mission is planned and logged, the setup phase is over. Execute via `/continue`.

package/skills/onboard/SKILL.md

@@ -0,0 +1,27 @@
+# Repository Onboarding
+
+Initialize and analyze a new repository for deep intelligence.
+
+## Workflow
+
+1.  **Semantic Init**: `shadow_recon_onboard({ repoPath: "..." })` — First run: full baseline index. **Re-run**: skips heavy indexing when already indexed and up-to-date; only refreshes hologram/summary.
+2.  **Unified Sync**: `shadow_sync_trace({ repoPath: "..." })` — Indexing + ghost analysis + mission re-hydration.
+3.  **Session Context** (one call): `shadow_ops_context({ repoPath: "..." })` — Returns hologram + chronicle (last 5) + briefing (counts, next_work_candidates). No separate holo/chronicle/briefing calls.
+4.  **Optional deep dive**: `shadow_recon_topography({ repoPath })`, `shadow_ops_chronicle({ limit: 10, repoPath })` — Only when you need layers or longer history.
+5.  **Hooks**: `shadow_env_hooks({ action: "install", repoPath })`.
+6.  **Mission**: `shadow_ops_plan({ name: "...", goal: "...", repoPath })`.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Action       | Tool                                                                                    |
+| :----------- | :-------------------------------------------------------------------------------------- |
+| **Index**    | `shadow_recon_onboard({ repoPath })`                                                    |
+| **Sync**     | `shadow_sync_trace({ repoPath })`                                                       |
+| **Context**  | `shadow_ops_context({ repoPath })` — hologram + chronicle + briefing in one call        |
+| **Metrics**  | `fetch_mcp_resource(server: "lish", uri: "repo://current/metrics")`                     |
+| **Layers**   | `shadow_recon_topography({ repoPath })`                                                 |
+| **History**  | `shadow_ops_chronicle({ limit: 10, repoPath })`                                         |
+| **Briefing** | `shadow_ops_briefing({ scope: "project", repoPath })` — only if you need briefing alone |
+| **Hooks**    | `shadow_env_hooks({ action: "install", repoPath })`                                     |
+
+_Use absolute paths for `repoPath`. Default flow: onboard → sync_trace → **context** (one shot). Keep separate tools: use hologram/briefing/chronicle alone when you need **one piece** (lighter) or chronicle with **different params** (limit, since/until, offset, format)._

package/skills/understand/SKILL.md

@@ -0,0 +1,35 @@
+# Architectural Understanding
+
+Find the high-signal path to understanding complex logic.
+
+## Workflow
+
+1. **Session Context** (one call): `shadow_ops_context({ repoPath: "..." })` — Hologram + chronicle (last 5) + briefing. Use when you want "the world" in one shot. For a single piece only: `shadow_recon_hologram` or `shadow_ops_chronicle({ limit: 5 })`.
+2. **Topological Placement (The Where)**:
+   - `shadow_recon_topography({ repoPath: "..." })` — Identify Entry/Logic/Data layers.
+   - `shadow_recon_tree({ subPath: "src/services", maxDepth: 2, repoPath: "..." })` — Focused tree.
+3. **Relational Analysis (The Who)**:
+   - `shadow_analyze_impact({ symbolName: "...", filePath: "...", depth: 3, repoPath: "..." })` — Blast radius.
+   - `shadow_analyze_deps({ filePath: "...", direction: "imported_by", repoPath: "..." })` — Who depends on this?
+   - `shadow_search_concept({ query: "...", includeTests: false, repoPath: "..." })` — Semantic search.
+4. **Mechanics (The How)**:
+   - **For Logic**: `shadow_analyze_flow({ symbolName: "...", filePath: "...", repoPath: "..." })` — Trace execution.
+   - **For Objects**: `shadow_inspect_file({ filePath: "...", detailLevel: "signatures", repoPath: "..." })` — All exports.
+   - **For Symbol Deep Dive**: `shadow_inspect_symbol({ symbolName: "...", filePath: "...", context: "full", repoPath: "..." })` — With deps.
+5. **Synthesis**: `shadow_ops_log({ missionId: ..., type: "discovery", content: "...", symbolName: "...", repoPath: "..." })`.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Discovery Layer   | Precise Tool Call                                                    |
+| :---------------- | :------------------------------------------------------------------- |
+| **Context**       | `shadow_ops_context({ repoPath })` — hologram + chronicle + briefing |
+| **Hologram only** | `shadow_recon_hologram({ repoPath })`                                |
+| **History only**  | `shadow_ops_chronicle({ limit: 5, repoPath })`                       |
+| **Layers**        | `shadow_recon_topography({ repoPath })`                              |
+| **Blast Radius**  | `shadow_analyze_impact({ symbolName: "...", depth: 3, repoPath })`   |
+| **Dependents**    | `shadow_analyze_deps({ direction: "imported_by", repoPath })`        |
+| **Flow Trace**    | `shadow_analyze_flow({ symbolName: "...", repoPath })`               |
+| **Structure**     | `shadow_inspect_file({ detailLevel: "signatures", repoPath })`       |
+| **Deep Dive**     | `shadow_inspect_symbol({ context: "full", repoPath })`               |
+
+_Note: Prefer `shadow_ops_context` for session start (one call). Use hologram or chronicle **alone** when you need one piece (lighter) or chronicle with different params (limit, since/until, format). Use `context: "definition"` in inspect for token-efficient symbol inspection._

package/skills/workspace/SKILL.md

@@ -0,0 +1,25 @@
+# Workspace Orchestration
+
+Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine.
+
+## Workflow
+
+1. **List Workspaces**: `shadow_workspace_list({ repoPaths: ["...", "..."], repoPath: "..." })`.
+2. **Federated Search**: `shadow_workspace_fuse({ repoPaths: [...], repoPath: "..." })`.
+3. **Link Missions**: `shadow_workspace_link({ parentRepoPath: "...", parentMissionId: 1, childRepoPath: "...", childMissionId: 2, relationship: "blocks", repoPath: "..." })`.
+4. **Verify Graph**: `shadow_ops_graph({ missionId: 1, depth: 3, repoPath: "..." })`.
+
+## Precise Tooling (Lish Shadow MCP)
+
+| Action        | Precise Tool Call                                       |
+| :------------ | :------------------------------------------------------ |
+| **List**      | `shadow_workspace_list({ repoPaths: [...], repoPath })` |
+| **Fuse**      | `shadow_workspace_fuse({ repoPaths: [...], repoPath })` |
+| **Link**      | `shadow_workspace_link({ parentMissionId: 1, ... })`    |
+| **Visualize** | `shadow_ops_graph({ missionId: 1, repoPath })`          |
+
+_Note: Use `fused-search` after `fuse` to look up concepts across all repositories simultaneously._
+
+## Tooling Strategy
+
+This skill relies on the **Lish Shadow Engine** (MCP). Use `shadow_workspace_fuse` early in multi-repo sessions to unlock "X-Ray" vision across boundaries.