Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Rearchitect into a .context/ markdown graph with init/check

anirudhkumar-nanonets5f38fb569314
diff --git a/.context/ai-model-integration.md b/.context/ai-model-integration.md
new file mode 100644
index 00000000..7ed26adf
--- /dev/null
+++ b/.context/ai-model-integration.md
@@ -0,0 +1,32 @@
+---
+name: AI Model Integration
+slug: ai-model-integration
+type: system
+sources:
+ - path: src/ai/providers.ts
+ hash: 8d4258cf8990f2fb6ac4664221fe96b5385edf8428f5f5b8a75958b8447c2cb0
+ - path: src/ai/summarize.ts
+ hash: c207e3e66f7386f7baff659cf00a3d87901e86d33ad1c0b04e4bb7943f5b5c21
+ - path: src/ai/synthesize.ts
+ hash: 2455b828410429e13cb029b6d9d4ee00532808bb63deec658445aeabb1323db0
+sources_digest: 22e2c0a1bc0211ff99916ab816560b79484d4b9f608ea978eeecd3c5f4116637
+links:
+ - to: benchmarking-system
+ relation: part_of
+ description: Supports the benchmarking system by providing AI model capabilities.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This system manages the integration of AI models for summarization and synthesis tasks, allowing for both local and remote processing through configurable settings.
+
+## Related
+
+- part of [[benchmarking-system]] — Supports the benchmarking system by providing AI model capabilities.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/benchmarking-metrics.md b/.context/benchmarking-metrics.md
new file mode 100644
index 00000000..9fad783f
--- /dev/null
+++ b/.context/benchmarking-metrics.md
@@ -0,0 +1,32 @@
+---
+name: Benchmarking Metrics
+slug: benchmarking-metrics
+type: concept
+sources:
+ - path: bench/agent.ts
+ hash: e10d64f913c9517cef84cce58ea042d71bed3e94182c791245170eca54060e31
+ - path: bench/judge.ts
+ hash: 94c222341b066e4f3134b3d9d3f30f31b9ffe7b92967086b07c58f297d349936
+ - path: bench/report.ts
+ hash: 775be8c40a8e4172521bba8f6a1f026fa23c4d24b9b5225da3ed5b745077a5b0
+sources_digest: 1a67b360c8323619bb19a61d96bfa51c43becce2db8f6422cc49ad32c0ef8fa6
+links:
+ - to: benchmarking-system
+ relation: defines
+ description: Establishes the metrics used for performance evaluation.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This concept defines the key performance metrics used in benchmarking, including token usage, latency, correctness, and cost, which are critical for evaluating AI model performance.
+
+## Related
+
+- defines [[benchmarking-system]] — Establishes the metrics used for performance evaluation.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/benchmarking-results-reporting.md b/.context/benchmarking-results-reporting.md
new file mode 100644
index 00000000..c1e394c2
--- /dev/null
+++ b/.context/benchmarking-results-reporting.md
@@ -0,0 +1,28 @@
+---
+name: Benchmarking Results Reporting
+slug: benchmarking-results-reporting
+type: system
+sources:
+ - path: bench/report.ts
+ hash: 775be8c40a8e4172521bba8f6a1f026fa23c4d24b9b5225da3ed5b745077a5b0
+sources_digest: f7b46f3036503f43413cb48d25fa6ce54585514fb19e9b4e923c0c5628ce8aed
+links:
+ - to: benchmarking-system
+ relation: depends_on
+ description: Relies on benchmarking data for generating reports.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This system aggregates and formats benchmarking results into a human-readable report, providing insights into performance metrics and cost evaluations.
+
+## Related
+
+- depends on [[benchmarking-system]] — Relies on benchmarking data for generating reports.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/benchmarking-system.md b/.context/benchmarking-system.md
new file mode 100644
index 00000000..9359f3a9
--- /dev/null
+++ b/.context/benchmarking-system.md
@@ -0,0 +1,44 @@
+---
+name: Benchmarking System
+slug: benchmarking-system
+type: system
+sources:
+ - path: bench/agent.ts
+ hash: e10d64f913c9517cef84cce58ea042d71bed3e94182c791245170eca54060e31
+ - path: bench/judge.ts
+ hash: 94c222341b066e4f3134b3d9d3f30f31b9ffe7b92967086b07c58f297d349936
+ - path: bench/llm.ts
+ hash: 6c0d2a02ac6aa86de94f779355020700a4d9016e2f4b431bf75560e1d3c51229
+ - path: bench/report.ts
+ hash: 775be8c40a8e4172521bba8f6a1f026fa23c4d24b9b5225da3ed5b745077a5b0
+ - path: bench/run.ts
+ hash: f9d9235f3661e03b721564a786cc80cbd50584cedb6a80f0bbb5f7757ccd724b
+ - path: bench/selfcheck.ts
+ hash: 0eaf577938e20fa27d9cd0157bc8843fdc37165d85696789334b8605138f4bb4
+ - path: bench/tasks.ts
+ hash: d21168797f40d193a914aca0c438409d29d300441bc0a6a518c93869240b3b69
+sources_digest: b82fc41740c1a096a0fd5c3f20776231e57194958bef6c87a28a6975ff3d9142
+links:
+ - to: ai-model-integration
+ relation: uses
+ description: Utilizes AI models for benchmarking tasks.
+ - to: benchmarking-results-reporting
+ relation: produces
+ description: Generates reports summarizing benchmarking results.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This system orchestrates the benchmarking of AI models, facilitating the evaluation of performance metrics such as token usage, latency, and correctness through various components including agents, judges, and reporting mechanisms.
+
+## Related
+
+- uses [[ai-model-integration]] — Utilizes AI models for benchmarking tasks.
+- produces [[benchmarking-results-reporting]] — Generates reports summarizing benchmarking results.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/configuration-management.md b/.context/configuration-management.md
new file mode 100644
index 00000000..28f3db63
--- /dev/null
+++ b/.context/configuration-management.md
@@ -0,0 +1,28 @@
+---
+name: Configuration Management
+slug: configuration-management
+type: concept
+sources:
+ - path: src/ai/providers.ts
+ hash: 8d4258cf8990f2fb6ac4664221fe96b5385edf8428f5f5b8a75958b8447c2cb0
+sources_digest: 12e8fd63a512b486816eb62cb8cb53f9e8f7f3b5306eeb5d0bc2b30042178bf9
+links:
+ - to: ai-model-integration
+ relation: influences
+ description: Affects how AI models are integrated and utilized.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This concept encompasses the management of configuration settings for AI engines, allowing for flexible integration of local and remote processing options based on user-defined parameters and environment variables.
+
+## Related
+
+- influences [[ai-model-integration]] — Affects how AI models are integrated and utilized.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/context-graph-management.md b/.context/context-graph-management.md
new file mode 100644
index 00000000..3a0f7b95
--- /dev/null
+++ b/.context/context-graph-management.md
@@ -0,0 +1,36 @@
+---
+name: Context Graph Management
+slug: context-graph-management
+type: system
+sources:
+ - path: src/context/build.ts
+ hash: cfe11ecfeab1f69aad383db3a0a282a45033b61dc8b0af1ae80dc3d41687f0cb
+ - path: src/context/check.ts
+ hash: df6c8cb642ea53f533c4deeb1143932d74b36fa5eb424c3bac73f46aca95a312
+ - path: src/context/node-file.ts
+ hash: 32e046ecd962e8709c5795fc42e3934064da5f3acc5eb5df584188b37cbfd5b9
+ - path: src/engine.ts
+ hash: 9ce688dafb10d7d3acbad361c36f7b13be33a104721779d3d8bfcb431ca6e2e9
+ - path: src/index.ts
+ hash: 5e3bfb88d938f9fbfbcefd4917e15fa32fb09ab3bd06e9de5739d248416b054a
+sources_digest: 2f4644c3979157085af4d66d5e6435e8e37100d180d5dd2b3519dbd7e01b96e2
+links:
+ - to: benchmarking-system
+ relation: part_of
+ description: Provides context management capabilities for benchmarking.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This system is responsible for building and maintaining a context graph from a codebase, ensuring that the generated content remains in sync with the underlying source files through initialization and verification processes.
+
+## Related
+
+- part of [[benchmarking-system]] — Provides context management capabilities for benchmarking.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/error-handling-and-validation.md b/.context/error-handling-and-validation.md
new file mode 100644
index 00000000..ea318666
--- /dev/null
+++ b/.context/error-handling-and-validation.md
@@ -0,0 +1,34 @@
+---
+name: Error Handling and Validation
+slug: error-handling-and-validation
+type: concept
+sources:
+ - path: bench/run.ts
+ hash: f9d9235f3661e03b721564a786cc80cbd50584cedb6a80f0bbb5f7757ccd724b
+ - path: src/context/check.ts
+ hash: df6c8cb642ea53f533c4deeb1143932d74b36fa5eb424c3bac73f46aca95a312
+ - path: test/context.test.ts
+ hash: 977ca7f64b4b9e3f5661be18ea3710399b976cb989aa5d17af3c6ee4692aed33
+sources_digest: e957e54820d8650507a9ff640ca697db275bf5cc32a1452e76c5e7fc2c302048
+links:
+ - to: benchmarking-system
+ relation: supports
+ description: >-
+ Enhances the reliability of the benchmarking system through validation
+ mechanisms.
+generator:
+ version: 1
+---
+<!-- context:generated:start -->
+## Summary
+
+This concept addresses the strategies employed for error handling and validation throughout the benchmarking and context management processes, ensuring robustness and reliability in operations.
+
+## Related
+
+- supports [[benchmarking-system]] — Enhances the reliability of the benchmarking system through validation mechanisms.
+<!-- context:generated:end -->
+
+## Notes
+
+_Anything written below the generated block is preserved when the graph is regenerated._
diff --git a/.context/manifest.json b/.context/manifest.json
new file mode 100644
index 00000000..b4931992
--- /dev/null
+++ b/.context/manifest.json
@@ -0,0 +1,172 @@
+{
+ "version": 1,
+ "model": "openrouter:openai/gpt-4o-mini",
+ "repoDigest": "83e9219d224cc08f493579beca8812a8f7cc05ac76ecc206b055bfc033f85830",
+ "files": [
+ {
+ "path": "bench/agent.ts",
+ "hash": "e10d64f913c9517cef84cce58ea042d71bed3e94182c791245170eca54060e31"
+ },
+ {
+ "path": "bench/judge.ts",
+ "hash": "94c222341b066e4f3134b3d9d3f30f31b9ffe7b92967086b07c58f297d349936"
+ },
+ {
+ "path": "bench/llm.ts",
+ "hash": "6c0d2a02ac6aa86de94f779355020700a4d9016e2f4b431bf75560e1d3c51229"
+ },
+ {
+ "path": "bench/report.ts",
+ "hash": "775be8c40a8e4172521bba8f6a1f026fa23c4d24b9b5225da3ed5b745077a5b0"
+ },
+ {
+ "path": "bench/run.ts",
+ "hash": "f9d9235f3661e03b721564a786cc80cbd50584cedb6a80f0bbb5f7757ccd724b"
+ },
+ {
+ "path": "bench/selfcheck.ts",
+ "hash": "0eaf577938e20fa27d9cd0157bc8843fdc37165d85696789334b8605138f4bb4"
+ },
+ {
+ "path": "bench/tasks.ts",
+ "hash": "d21168797f40d193a914aca0c438409d29d300441bc0a6a518c93869240b3b69"
+ },
+ {
+ "path": "install.sh",
+ "hash": "01ca60d495dca47e9831b5fe2f0c80bdbe8405a944124d758b951ae263639ac2"
+ },
+ {
+ "path": "src/ai/providers.ts",
+ "hash": "8d4258cf8990f2fb6ac4664221fe96b5385edf8428f5f5b8a75958b8447c2cb0"
+ },
+ {
+ "path": "src/ai/summarize.ts",
+ "hash": "c207e3e66f7386f7baff659cf00a3d87901e86d33ad1c0b04e4bb7943f5b5c21"
+ },
+ {
+ "path": "src/ai/synthesize.ts",
+ "hash": "2455b828410429e13cb029b6d9d4ee00532808bb63deec658445aeabb1323db0"
+ },
+ {
+ "path": "src/cli.ts",
+ "hash": "b61374af84daa862309aef1b92fb43082be4021d4d19f2a14fb1b8378beb58bb"
+ },
+ {
+ "path": "src/context/build.ts",
+ "hash": "cfe11ecfeab1f69aad383db3a0a282a45033b61dc8b0af1ae80dc3d41687f0cb"
+ },
+ {
+ "path": "src/context/check.ts",
+ "hash": "df6c8cb642ea53f533c4deeb1143932d74b36fa5eb424c3bac73f46aca95a312"
+ },
+ {
+ "path": "src/context/node-file.ts",
+ "hash": "32e046ecd962e8709c5795fc42e3934064da5f3acc5eb5df584188b37cbfd5b9"
+ },
+ {
+ "path": "src/engine.ts",
+ "hash": "9ce688dafb10d7d3acbad361c36f7b13be33a104721779d3d8bfcb431ca6e2e9"
+ },
+ {
+ "path": "src/index.ts",
+ "hash": "5e3bfb88d938f9fbfbcefd4917e15fa32fb09ab3bd06e9de5739d248416b054a"
+ },
+ {
+ "path": "src/ingest/fs.ts",
+ "hash": "a8339532da34b44d35eb9ad16e7106adb1262d73d9895b1bd94574337fb2019f"
+ },
+ {
+ "path": "src/util/id.ts",
+ "hash": "5fabc8ddcc3abc907ce69f04ad2ebe51933262cf44aa2dfd40589f71f1926e8a"
+ },
+ {
+ "path": "test/context.test.ts",
+ "hash": "977ca7f64b4b9e3f5661be18ea3710399b976cb989aa5d17af3c6ee4692aed33"
+ },
+ {
+ "path": "test/helpers.ts",
+ "hash": "e45af1d38d7c6d4abc804fc74e9ae4c3373cf78769c17b16b185c3ee0e2c3228"
+ }
+ ],
+ "nodes": [
+ {
+ "slug": "ai-model-integration",
+ "name": "AI Model Integration",
+ "type": "system",
+ "sources": [
+ "src/ai/providers.ts",
+ "src/ai/summarize.ts",
+ "src/ai/synthesize.ts"
+ ],
+ "sourcesDigest": "22e2c0a1bc0211ff99916ab816560b79484d4b9f608ea978eeecd3c5f4116637"
+ },
+ {
+ "slug": "benchmarking-metrics",
+ "name": "Benchmarking Metrics",
+ "type": "concept",
+ "sources": [
+ "bench/agent.ts",
+ "bench/judge.ts",
+ "bench/report.ts"
+ ],
+ "sourcesDigest": "1a67b360c8323619bb19a61d96bfa51c43becce2db8f6422cc49ad32c0ef8fa6"
+ },
+ {
+ "slug": "benchmarking-results-reporting",
+ "name": "Benchmarking Results Reporting",
+ "type": "system",
+ "sources": [
+ "bench/report.ts"
+ ],
+ "sourcesDigest": "f7b46f3036503f43413cb48d25fa6ce54585514fb19e9b4e923c0c5628ce8aed"
+ },
+ {
+ "slug": "benchmarking-system",
+ "name": "Benchmarking System",
+ "type": "system",
+ "sources": [
+ "bench/agent.ts",
+ "bench/judge.ts",
+ "bench/llm.ts",
+ "bench/report.ts",
+ "bench/run.ts",
+ "bench/selfcheck.ts",
+ "bench/tasks.ts"
+ ],
+ "sourcesDigest": "b82fc41740c1a096a0fd5c3f20776231e57194958bef6c87a28a6975ff3d9142"
+ },
+ {
+ "slug": "configuration-management",
+ "name": "Configuration Management",
+ "type": "concept",
+ "sources": [
+ "src/ai/providers.ts"
+ ],
+ "sourcesDigest": "12e8fd63a512b486816eb62cb8cb53f9e8f7f3b5306eeb5d0bc2b30042178bf9"
+ },
+ {
+ "slug": "context-graph-management",
+ "name": "Context Graph Management",
+ "type": "system",
+ "sources": [
+ "src/context/build.ts",
+ "src/context/check.ts",
+ "src/context/node-file.ts",
+ "src/engine.ts",
+ "src/index.ts"
+ ],
+ "sourcesDigest": "2f4644c3979157085af4d66d5e6435e8e37100d180d5dd2b3519dbd7e01b96e2"
+ },
+ {
+ "slug": "error-handling-and-validation",
+ "name": "Error Handling and Validation",
+ "type": "concept",
+ "sources": [
+ "bench/run.ts",
+ "src/context/check.ts",
+ "test/context.test.ts"
+ ],
+ "sourcesDigest": "e957e54820d8650507a9ff640ca697db275bf5cc32a1452e76c5e7fc2c302048"
+ }
+ ]
+}
diff --git a/.dockerignore b/.dockerignore
deleted file mode 100644
index e2eb8f14..00000000
--- a/.dockerignore
+++ /dev/null
@@ -1,16 +0,0 @@
-node_modules
-dist
-.git
-.env
-.env.*
-.context-graph
-*.db
-*.db-shm
-*.db-wal
-*.log
-*.png
-*.html
-sample-docs
-test
-examples
-.mcp.json
diff --git a/.env.example b/.env.example
index 7e439840..107f4386 100644
--- a/.env.example
+++ b/.env.example
@@ -1,35 +1,25 @@
-# Context Graph Engine configuration
+# Context Graph Engine — configuration
#
-# The engine runs FULLY LOCALLY by default — no keys required:
-# • Embeddings run in-process (transformers.js), model cached on first use.
-# • Extraction uses a local Ollama model (install: https://ollama.com).
-# Set the cloud keys below only if you want higher-quality cloud models; they
-# are picked up automatically when present.
+# Runs fully locally by default (no keys): extraction and summaries use a local
+# Ollama model. Install Ollama (https://ollama.com) and pull a model:
+# ollama pull llama3.2
+#
+# Set an OpenRouter key for higher-quality cloud summaries/extraction — it's
+# picked up automatically when present.
# --- Cloud (optional) ---------------------------------------------------------
-# Entity/relationship extraction via OpenRouter (https://openrouter.ai).
-# OpenRouter fronts many models with one key; pick any tool-calling model.
# OPENROUTER_API_KEY=sk-or-...
-# Optional: override the extraction model (default: openai/gpt-4o-mini)
+# Optional: override the model (default: openai/gpt-4o-mini)
# CONTEXT_GRAPH_OPENROUTER_MODEL=openai/gpt-4o-mini
# Optional: override the API base URL (default: https://openrouter.ai/api/v1)
# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
-# Embeddings on OpenAI (optional — OpenRouter has no embeddings endpoint, so
-# embeddings run locally unless this key is set).
-# OPENAI_API_KEY=sk-...
-# Optional: override the embedding model (default: text-embedding-3-small)
-# CONTEXT_GRAPH_EMBEDDING_MODEL=text-embedding-3-small
-
-# --- Local (defaults; used when the keys above are absent) --------------------
-# Force local even when cloud keys are set.
+# --- Local (defaults; used when the key above is absent) ----------------------
+# Force local even when a cloud key is set.
# CONTEXT_GRAPH_LOCAL=1
-# In-process embedding model (default: Xenova/all-MiniLM-L6-v2)
-# CONTEXT_GRAPH_LOCAL_EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
-# Local extraction via Ollama (default model: llama3.2)
# CONTEXT_GRAPH_OLLAMA_MODEL=llama3.2
# CONTEXT_GRAPH_OLLAMA_URL=http://localhost:11434
-# --- Storage ------------------------------------------------------------------
-# Where the graph database lives (default: ./.context-graph/graph.db)
-# CONTEXT_GRAPH_DB=./.context-graph/graph.db
+# --- Graph location -----------------------------------------------------------
+# Where the graph lives (default: <repo>/.context)
+# CONTEXT_GRAPH_DIR=.context
diff --git a/.gitignore b/.gitignore
index 844a9347..670e1d83 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,20 +2,11 @@ node_modules/
dist/
*.log
-# Local graph databases
-*.db
-*.db-shm
-*.db-wal
+# The context graph's local LLM-call cache — regenerated, never committed.
+# The graph itself (.context/*.md + manifest.json) IS committed.
+.context/.cache/
-# Docker runtime volume — holds the graph db and the generated access token
-# (.web-token / share-link.txt). Never commit; the token would leak.
-data/
-# Ignore the local graph dir's contents (the SQLite replica) but keep the
-# committable, git-native team-sync file (Mode A).
-.context-graph/*
-!.context-graph/graph.jsonl
-
-# Benchmark run artifacts (raw rows + summaries are regenerated per run)
+# Benchmark run artifacts (regenerated per run)
bench/results/
# Env
diff --git a/.mcp.json b/.mcp.json
deleted file mode 100644
index 3c7cf8d9..00000000
--- a/.mcp.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
- "mcpServers": {
- "context-graph": {
- "type": "stdio",
- "command": "node",
- "args": [
- "/Users/anirudh/Documents/context-engine/dist/mcp.js"
- ],
- "env": {
- "CONTEXT_GRAPH_DB": "/Users/anirudh/Documents/context-engine/.context-graph/demo.db"
- }
- }
- }
-}
\ No newline at end of file
diff --git a/BUSINESS-CASE.md b/BUSINESS-CASE.md
deleted file mode 100644
index d944aada..00000000
--- a/BUSINESS-CASE.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# Business Case: Context Graph — the self-hosted team brain
-
-**Decision:** Of the five candidate products in PRODUCT-DESIGNS.md, we are launching
-**Idea 2 — a self-hosted "team brain":** point it at a folder of team documents and get a
-searchable knowledge graph that answers questions with citations, shows its confidence,
-and gets smarter every time someone uses it. Open source, local-first, one process,
-one SQLite file.
-
-This document records why — the market logic, the evidence, and the risks — so the
-reasoning survives past the launch week.
-
----
-
-## 1. The problem is real, universal, and unsolved at our price point
-
-Every team past ~10 people develops the same disease: the answers exist, but they live
-in a retired engineer's head, a two-year-old Slack thread, page 41 of a runbook PDF,
-and a Notion workspace nobody can search. The symptom is the **repeated question** —
-"how do we deploy staging?", "who owns billing escalations?" — asked again every time
-someone joins or forgets.
-
-The category answer is enterprise search ("Glean for your company"), and it is sold as
-**enterprise SaaS**: per-seat pricing, sales calls, and — the part small teams actually
-refuse — *shipping every internal document to a third party's cloud*. A 15-person
-agency, clinic, lab, or startup has exactly the same disease and none of the budget,
-procurement patience, or willingness to exfiltrate its documents.
-
-That gap — **teams of 10–100 who want their knowledge searchable without giving it to
-anyone** — is the market. It is precisely the audience that self-hosts Nextcloud
-instead of Dropbox and Chatwoot instead of Zendesk, and it congregates in reachable,
-free channels (r/selfhosted, Hacker News, awesome-selfhosted lists).
-
-## 2. Why this idea beat the other candidates
-
-We deep-researched the three viable candidates (the two dev-oriented ideas were
-excluded by constraint). The finding that decided it: **no candidate wins on empty
-whitespace — every category is occupied — so the deciding axis is speed to real
-users**, and the candidates differ by an order of magnitude:
-
-| | A: Team brain | B: Slack onboarding bot | C: Support graph |
-|---|---|---|---|
-| Incumbent | Onyx (30.7k★) — heavyweight | Various SaaS Q&A bots | Chatwoot (34.1k★) + paywalled "Captain AI" |
-| Gatekeeper between us and users | **None** | Slack Marketplace | Helpdesk marketplaces |
-| Structural friction | Show HN / r/selfhosted post | **5 active workspaces required *before submission*, up to 10 weeks of manual review**, mandatory public HTTPS hosting, scrutiny on message-reading scopes | Zendesk/Intercom connector + 1–3 weeks marketplace review |
-| Realistic time to first 10–100 users | **Days** | Months | Weeks |
-
-For a project whose explicit goal is *the first 10–100 users, fast, with a demo today*,
-B is disqualified by Slack's own rules and C by connector-plus-review lead time. A is
-the only candidate where the entire acquisition loop — build, post, install — is
-**permissionless**. Post-launch data for comparable OSS AI tools shows a competent
-Show HN averaging ~121 GitHub stars in the first 24 hours; that is the top of exactly
-the funnel we need, available on day one, at zero cost.
-
-B and C are not discarded ideas — they are **future surfaces on the same engine**. A
-Slack bot and a support-desk integration are distribution channels for a knowledge
-graph that already exists. Building A first means B and C later inherit a graph, a
-user base, and public proof.
-
-## 3. Why we can win the shelf we're stepping onto
-
-The obvious objection: Onyx already owns "open-source enterprise search" with 30.7k
-stars. Why will anyone install ours?
-
-Because Onyx's dominance is also its verified weakness. It is an **enterprise-shaped
-deployment**: multiple containers, Postgres, a Vespa search cluster — infrastructure
-that assumes a platform team. The r/selfhosted user with a NAS and the 20-person
-company with no DevOps function bounce off it. The market leader structurally cannot
-serve the low end without abandoning its architecture. That is a classic
-low-end-disruption opening:
-
-- **Their install:** a container fleet and a search cluster.
-- **Ours:** one process, one SQLite file, embeddings computed in-process, no accounts,
- no API keys required. Your team's entire brain is a file you can copy.
-
-The second differentiator is the product's actual thesis, and it is one the incumbents
-don't have: **the graph is alive and it shows receipts.** Every fact carries how many
-times it has been observed, a confidence score, and the exact source passages behind
-it. Answers cite their evidence. When a teammate contributes a correction, you *watch*
-the graph reinforce. Enterprise search treats knowledge as a static index to be
-re-crawled; we treat it as a living ledger that compounds with use. For a small team,
-that maps to the real fear — "can I trust this answer?" — and answers it visibly.
-
-## 4. Why we built the demo as a local web app with the graph on screen
-
-This was a deliberate GTM decision, and the research forced it:
-
-1. **The differentiation must be visible or it doesn't exist.** The strongest caution
- from the research is that graph-based retrieval is *not* an automatic quality win —
- published benchmarks (arXiv 2502.11371) show GraphRAG failing to beat plain RAG on
- simple single-hop questions. If we demoed a chat box that answers questions, we
- would be indistinguishable from every RAG wrapper of the last three years and would
- read as "Onyx but smaller" — the single biggest identified risk of this launch. So
- the demo's design puts the mechanism on screen: the living graph is permanently
- visible, asking a question lights up the exact facts consulted, every fact wears a
- monospace provenance receipt (`68% · ×2 · 2 sources`), and teaching it something
- makes the reinforced nodes pulse. The moat is the epistemics; the UI exists to make
- the epistemics undeniable in a 30-second screen recording.
-
-2. **A web UI is the product for this buyer, not a veneer.** The constraint was a
- non-developer-oriented standalone product. Our audience's operations manager will
- never run a CLI; "open localhost:4680 and ask" is the whole onboarding. The same
- interface doubles as every marketing asset the launch needs — the Show HN GIF, the
- README screenshot, the hosted demo.
-
-3. **Distribution research dictated the shape of the install.** The channel analysis
- was unambiguous for self-hosted tools in 2026: Docker-first (a single `docker run`
- as the headline), hosted read-only demo as the week-two amplifier, and *not*
- npm-first — native-module installs (SQLite bindings, ONNX runtime) fail behind
- corporate proxies and node-gyp toolchains often enough to burn first-run trust;
- Anthropic itself abandoned npm distribution for Claude Code over exactly this
- failure mode. A self-contained local web server is the artifact that Dockerizes
- into that one-liner without change.
-
-4. **Local-first is the positioning, so the demo must run with zero cloud.** The
- pitch — "your documents never leave your machine" — is falsified by a demo that
- requires an API key. Retrieval, the graph, and provenance all work fully offline;
- a cloud key only upgrades the experience (written answers, richer extraction).
- That graceful degradation is the trust story, demonstrated rather than claimed.
-
-## 5. What winning looks like
-
-The goal is deliberately not a million users; it is **10–100 real installs, fast**,
-because for an OSS product that is the flywheel's first turn: installs → GitHub stars
-→ list inclusion (awesome-selfhosted) → organic search → more installs.
-
-- **Week 1:** Show HN + r/selfhosted launch. Success: ~100 stars, 10+ confirmed
- installs, 3 users who ask for something (a connector, a feature) — proof of pull.
-- **Week 2–4:** hosted read-only demo, Docker image on a registry, README GIF.
- Success: first users we didn't personally cause; first inbound issue from a
- non-developer team.
-- **After proof:** B (Slack surface) and C (support surface) become roadmap items
- built on a graph users already trust — entering those markets with evidence instead
- of cold.
-
-## 6. Risks, stated honestly
-
-- **"Onyx but smaller."** The kill risk. Mitigation is the entire demo design
- (visible graph, receipts, reinforcement) plus positioning discipline: we are not
- "enterprise search, lighter" — we are a *living knowledge ledger* for teams that
- will never deploy enterprise search.
-- **Graph quality skepticism.** GraphRAG's benchmark record means we must not
- over-claim answer quality. We claim *provenance, confidence, and compounding* —
- properties plain RAG genuinely lacks — and let answer quality be table stakes.
-- **Category churn.** The AI-tool graveyard is large; distribution moats are
- temporary. Our durable asset is the graph data users accumulate — the longer a team
- runs it, the more expensive leaving becomes. That is also why the write path
- (contribute/teach) shipped in v1 rather than later: retention is the moat, and
- retention starts at the first contributed fact.
diff --git a/DEMO.md b/DEMO.md
deleted file mode 100644
index 442ae887..00000000
--- a/DEMO.md
+++ /dev/null
@@ -1,205 +0,0 @@
-# Context Graph Engine — Demo Guide
-
-> Read this to understand what's been built and to run a clean demo today.
-
----
-
-## 1. What this is, in one sentence
-
-An **open-source library** that turns any pile of docs into a **structured context graph** — entities + typed relationships grounded in the source text — that AI agents **read from before doing work** and **write learnings back into**, so the shared knowledge compounds over time.
-
-Think "durable, structured memory for a team of agents" — the same integration shape as ByteRover, but self-hosted, embedded, and runnable with a single `curl`.
-
----
-
-## 2. What's been built (status)
-
-| Piece | What it does | Status |
-|-------|--------------|--------|
-| **Core engine** (`src/engine.ts`) | `ingest` → `read` → `contribute` over a graph | ✅ Done |
-| **Knowledge graph model** (`src/graph/`) | Nodes (entities), edges (typed relations), chunks (evidence), each with `confidence` + `observation` counts | ✅ Done |
-| **Dedup + reinforcement** (`src/graph/merge.ts`) | New knowledge is matched to existing nodes by name/alias **and** embedding similarity; matches are merged & reinforced, not duplicated | ✅ Done |
-| **Retrieval** (`src/retrieval/`) | Semantic match on entities → one-hop graph expansion → supporting passages → a ready-to-inject prompt block | ✅ Done |
-| **Storage** (`src/graph/sqlite-store.ts`) | Embedded SQLite (`better-sqlite3`), zero infra; swappable behind a `GraphStore` interface | ✅ Done |
-| **Local-first providers** (`src/ai/local.ts`) | In-process embeddings (transformers.js) + local extraction (Ollama) — **runs with no API keys** | ✅ Done |
-| **Cloud auto-upgrade** (`src/engine.ts`) | If `OPENROUTER_API_KEY` is set, uses OpenRouter for extraction automatically (any tool-calling model) for higher quality | ✅ Done |
-| **PDF + directory ingestion** (`src/ingest/pdf.ts`) | `.pdf` parsed automatically (pure-JS `unpdf`, no native deps); `ingest-dir` walks a folder of mixed docs (PDF/MD/TXT) | ✅ Done |
-| **Graph visualization** (`src/graph/export.ts`) | Export the whole graph to a self-contained interactive HTML page (also JSON / Mermaid) | ✅ Done |
-| **Three access modes** | Library, `context-graph` CLI, and `context-graph-mcp` MCP server (7 tools) for any agent | ✅ Done |
-| **Demo docs** (`examples/demo-docs/`) | 3 detail-rich PDFs + 1 Markdown glossary + a PDF generator script | ✅ Done |
-| **One-line installer** (`install.sh`) | `curl … | sh` clones, builds, and puts both commands on PATH | ✅ Done |
-| Update modes (silent vs. flagged) | Deferred per your call — needs discussion | ⏸ Deferred |
-| Delete / decay of stale nodes | In the spec, not yet built | ⬜ Not started |
-
-**The whole codebase is commented** — every module has a doc comment explaining its role, and the non-obvious logic (dedup matching, reinforcement, chunk overlap, one-hop expansion) is annotated inline.
-
----
-
-## 3. ⚠️ Before you demo: pick a provider
-
-The engine needs a model for **extraction** (pulling entities/relationships out of text). Embeddings run locally with no setup, but extraction needs one of:
-
-**Right now this machine has neither Ollama nor any API key set**, so pick one path first:
-
-### Path A — Cloud via OpenRouter (fastest to a clean demo, best quality) ✅ recommended for a live demo
-```bash
-export OPENROUTER_API_KEY=sk-or-... # extraction (default model: openai/gpt-4o-mini)
-export OPENAI_API_KEY=sk-... # embeddings (optional; embeddings stay local otherwise)
-```
-Reliable, fast, produces the richest graph. One OpenRouter key covers extraction — embeddings run locally unless you also set an OpenAI key. Best if you want the demo to look sharp.
-
-### Path B — Fully local (the "no keys" story your manager asked for)
-```bash
-# install Ollama from https://ollama.com, then:
-ollama pull llama3.2
-```
-No accounts, nothing leaves the machine. Slightly coarser graph and a one-time model download — this is the story to *tell*, but Path A is smoother to *show* live if you're short on time.
-
-> Tip: you can do both — run the demo on cloud for polish, then flip `CONTEXT_GRAPH_LOCAL=1` and re-run one command to prove it also works with zero keys.
-
----
-
-## 4. The MCP demo (the main event)
-
-This is the flow to show: **install → point Claude Code at a folder → "build a context graph" → Claude Code does it via MCP → open the visual graph → ask questions.** Verified end-to-end (OpenRouter extraction + local embeddings).
-
-There are 4 demo docs already in `examples/demo-docs/` — a fictional "Northwind" company: 3 PDFs (architecture, billing runbook, onboarding) + 1 Markdown glossary. Regenerate the PDFs any time with `node scripts/make-demo-pdfs.mjs`.
-
-### The 7 MCP tools Claude Code gets
-| Tool | What Claude Code uses it for |
-|------|------------------------------|
-| `context_ingest_dir` | **Point at a folder → build the whole graph in one call** |
-| `context_ingest_file` | Ingest specific files (incl. PDFs) by path |
-| `context_ingest` | Ingest raw text |
-| `context_read` | Answer a question from the graph |
-| `context_contribute` | Write a new learning back into the graph |
-| `context_export` | Write the graph to an interactive HTML file to show |
-| `context_stats` | Report entity/relationship counts |
-
-### Step 1 — Install
-```bash
-git clone [email protected]:NanoNets/context-graph-engine.git
-cd context-graph-engine && ./install.sh
-```
-That builds and puts `context-graph` + `context-graph-mcp` on your PATH. (One command — no manual npm steps.)
-
-### Step 2 — Point Claude Code at it
-Add this to your Claude Code MCP config (`.mcp.json` in your project, or `claude mcp add`). Set a DB path for the demo graph and your OpenRouter key:
-
-```json
-{
- "mcpServers": {
- "context-graph": {
- "command": "context-graph-mcp",
- "env": {
- "CONTEXT_GRAPH_DB": "/absolute/path/to/northwind-demo.db",
- "OPENROUTER_API_KEY": "sk-or-..."
- }
- }
- }
-}
-```
-Restart Claude Code so it picks up the server and its 7 tools.
-
-Alternatively, run one process for the web UI + MCP together with `context-graph serve` and point Claude Code at the HTTP endpoint (no per-session process to spawn):
-
-```json
-{
- "mcpServers": {
- "context-graph": { "type": "http", "url": "http://localhost:4680/mcp" }
- }
-}
-```
-
-### Step 3 — Ask Claude Code to build the graph (just say this)
-> "Use the context-graph tools to build a context graph from the folder
-> `/abs/path/context-graph-engine/examples/demo-docs`, then show me the stats."
-
-Claude Code calls **`context_ingest_dir`** on the folder. All 4 docs are parsed (PDFs included), chunked, embedded, and extracted into the graph — you'll watch the progress tick file-by-file. Result: **~62 entities and ~71 relationships** across 4 documents. (Progress notifications keep the call alive past the default 60s MCP timeout — a multi-file cloud ingest takes ~1–2 min.)
-
-### Step 4 — Show the graph (the visual)
-> "Export the context graph to `/tmp/northwind-graph.html` and tell me the path."
-
-Claude Code calls **`context_export`**. Open the file:
-```bash
-open /tmp/northwind-graph.html
-```
-You get an **interactive, force-directed graph** — nodes colored by type (service, person, policy, metric…), sized by how often they were observed, draggable/zoomable, with hover tooltips showing each entity's summary and confidence. This is the "show the created context graph" moment.
-
-### Step 5 — Ask questions (the payoff)
-Ask Claude Code things that only live inside those docs. It calls `context_read` and answers — structured entities/relationships **and** the exact source passages:
-
-- *"How are failed charges retried, and when does an account get suspended?"*
- → 3 retries with exponential backoff (1h / 6h / 24h) → `past_due` → suspended after 7 days.
-- *"How long do access tokens last and what backs the Auth Service?"*
- → access tokens expire after 15 minutes; Auth Service is backed by Redis for token revocation.
-- *"Who do I escalate a Stripe outage to?"*
- → Dana Whitfield (Payments team lead), post in `#billing-incidents`, page PagerDuty service `northwind-billing`.
-
-**The point to land:** these facts came from separate PDFs + a Markdown file, and the agent gets a *structured, cross-referenced* answer with the source text as evidence — not a blind vector-snippet dump.
-
-### Step 6 (optional) — Show it getting smarter
-Tell Claude Code: *"Contribute this learning to the graph: the Dunning Worker also posts to #billing-alerts after the final retry."* It calls `context_contribute`. Ask the billing question again — the new fact is merged in, and re-stated facts reinforce (bump confidence) rather than duplicate.
-
-### Fallback (no MCP client handy) — same thing via CLI
-```bash
-context-graph --db ./northwind-demo.db ingest-dir examples/demo-docs
-context-graph --db ./northwind-demo.db export --out northwind-graph.html && open northwind-graph.html
-context-graph --db ./northwind-demo.db query "how are failed charges retried?"
-```
-(Delete `northwind-demo.db*` to reset.)
-
----
-
-## 5. Talking points (what to say while it runs)
-
-- **"It's a graph, not a bag of chunks."** A vector store gives you similar snippets. This gives an agent *structure* it can reason over — what things are, and how they connect — plus the source passages as evidence.
-- **"Agents write back."** Most RAG is read-only. Here an agent contributes a learning and it's merged into shared knowledge with provenance, so the next agent benefits.
-- **"It compounds."** Confidence + observation counts mean the tenth confirmation of a fact strengthens it; one-off noise stays low-confidence. The graph curates itself.
-- **"Zero infrastructure, one command."** Embedded SQLite, in-process embeddings, `curl | sh`. No database to stand up, no keys required to start. Cloud is an *upgrade*, not a requirement.
-- **"TypeScript & MCP-native."** Most comparable OSS (Graphiti, GraphRAG, Cognee, mem0) is Python and/or server/cloud-oriented. This slots directly into a JS/TS agent stack and speaks MCP out of the box.
-
----
-
-## 6. Repository & install
-
-Published to **`github.com/NanoNets/context-graph-engine`** (private, branch `main`).
-
-```bash
-git clone [email protected]:NanoNets/context-graph-engine.git
-cd context-graph-engine && ./install.sh # build + link the local checkout
-```
-
-> ⚠️ The `curl … | sh` one-liner in the README fetches `install.sh` over an
-> anonymous URL, which only works once the repo is **public** (or with a token).
-> While the repo is private, use the clone + `./install.sh` path above. Flip the
-> repo to public when you're ready and the curl one-liner goes live as-is.
-
----
-
-## 7. Where to look in the code
-
-```
-src/
- engine.ts ← start here: ingest / read / contribute, provider selection
- ai/
- providers.ts ← config resolution (constructor → env → defaults) + interfaces
- local.ts ← key-free LocalEmbedder + OllamaExtractor
- openrouter.ts ← cloud extraction via OpenRouter (tool-calling)
- openai.ts ← OpenAI embeddings (optional)
- graph/
- types.ts ← the data model (nodes, edges, chunks) — read this to grok the domain
- merge.ts ← dedup + reinforcement (the "gets smarter" logic)
- sqlite-store.ts ← the embedded storage backend
- export.ts ← graph → interactive HTML / JSON / Mermaid
- ingest/
- chunker.ts ← paragraph-aware chunking with overlap
- pdf.ts ← PDF → text extraction (unpdf)
- retrieval/retriever.ts ← semantic match + one-hop expansion + prompt rendering
- cli.ts ← the CLI (ingest / ingest-dir / query / contribute / export / stats)
- mcp.ts ← the MCP server (7 tools incl. _ingest_dir and _export)
-examples/
- quickstart.ts ← library quickstart
- demo-docs/*.pdf ← the 3 demo PDFs used in §4
-scripts/make-demo-pdfs.mjs ← regenerates the demo PDFs
-```
diff --git a/Dockerfile b/Dockerfile
deleted file mode 100644
index 6808f5f0..00000000
--- a/Dockerfile
+++ /dev/null
@@ -1,40 +0,0 @@
-# Context Graph — the whole engine in one container.
-#
-# docker compose up → web UI at http://localhost:4680
-# MCP (HTTP) at http://localhost:4680/mcp
-#
-# Runs `context-graph serve`: the web UI, the MCP server (over HTTP), and the
-# folder watcher share one engine and one port. The graph persists to the /data
-# volume as a single SQLite file. The server binds 0.0.0.0 inside the container
-# and requires the access token printed in the container logs on first start
-# (or set CONTEXT_GRAPH_WEB_TOKEN); the token also gates /mcp.
-
-FROM node:22-slim AS build
-WORKDIR /app
-COPY package.json package-lock.json ./
-# `prepare` would try to compile before src is copied; native-module install
-# scripts (better-sqlite3) must still run, so drop only the prepare hook.
-RUN npm pkg delete scripts.prepare && npm ci
-COPY tsconfig.json ./
-COPY src ./src
-RUN npx tsc -p tsconfig.json \
- && mkdir -p dist/web && cp src/web/ui.html dist/web/ui.html \
- && npm prune --omit=dev
-
-FROM node:22-slim
-WORKDIR /app
-ENV NODE_ENV=production \
- HOST=0.0.0.0 \
- PORT=4680 \
- CONTEXT_GRAPH_DB=/data/graph.db \
- CONTEXT_GRAPH_MODEL_CACHE=/data/.model-cache
-COPY --from=build /app/node_modules ./node_modules
-COPY --from=build /app/dist ./dist
-COPY package.json ./
-RUN mkdir -p /data && chown node:node /data
-USER node
-EXPOSE 4680
-VOLUME /data
-# Resumes any registered watch folders; mount them and register via the UI or
-# `context-graph watch <dir>` so they persist in the /data volume.
-CMD ["node", "dist/serve.js"]
diff --git a/GTM-AND-PRODUCT-SPEC.md b/GTM-AND-PRODUCT-SPEC.md
deleted file mode 100644
index 31266e71..00000000
--- a/GTM-AND-PRODUCT-SPEC.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# Context Graph Engine — Product Spec & GTM Strategy
-
-> **Internal only — gitignored.** Working draft for management review.
-> Companion docs: `BUSINESS-CASE.md` (why this idea), `PRODUCT-DESIGNS.md` (design sketches).
-> Last updated: 2026-07-09
-
----
-
-## 1. One-paragraph summary (the elevator answer)
-
-A self-hosted engine that turns a team's documents into a living knowledge graph that AI agents read before doing work and write learnings back to — so context compounds instead of being re-discovered every session. Bring your own LLM API key (OpenRouter/OpenAI) for high-quality extraction; everything else — the graph, embeddings, retrieval — runs on your own machine, and a fully local mode (Ollama) exists for teams that can't send data to a cloud model. Plugs into any agent via MCP.
-
-**Positioning note:** the recommended path is API-key-first (quality), with local models as the privacy/air-gapped fallback — not the other way around.
-
-## 2. Problem & who has it
-
-**The agent problem (primary, why now):** an AI agent session starts from zero. Claude Code / Cursor re-discovers the same architecture, conventions, and gotchas on every task — burning tokens and latency re-reading files — and throws the learning away when the session ends. Vector RAG gives agents a bag of chunks, not structure they can reason over, and no write path to contribute learnings back.
-
-**The staleness problem (why existing fixes fail):** any knowledge base built once is wrong within days. Repos and folders change daily; nobody re-runs ingestion. The harder problem than indexing is *keeping the index alive*: knowing when a file change actually warrants re-extraction, pruning facts that no longer hold, and doing it in the background without anyone babysitting it.
-
-**Our scope (v1):** local repos and folders — the material closest to where agents work and where changes are detectable. Connectors to Slack, Notion, Drive etc. are a later addition, not v1. Users can also explicitly add files/facts via the web UI to a team or personal graph.
-
-**The payoff:** agents get a compact, fresh context bundle instead of re-exploring , lower latency, fewer tokens per task; humans get a readable, citable map of their own repos and folders.
-
-**Who feels it most:** teams (and individuals) using coding agents daily on real codebases, who prefer self-hosted tooling and won't ship their source to a vendor's cloud index.
-
-## 3. What the product is (spec)
-
-### 3.1 Core capabilities
-
-The engine is a loop, not a one-shot indexer:
-
-1. **Ingest** — point it at repos and folders (plus drag-and-drop of individual files in the web UI). Prose is chunked and extracted into entities + typed relationships, grounded in source passages. Code repos go through a per-file summarization pass first, then extraction over the summaries.
-2. **Stay fresh (the differentiator)** — watched folders and repos keep syncing into the graph through background processes. The engine decides *when* a file change actually warrants re-extraction (not every save does), *what* to update incrementally, and *what to prune* — facts whose source files were deleted or contradicted decay and drop out. Nobody babysits the index; the graph is as current as the filesystem.
-3. **Read** — an agent (or human) queries before a task and gets a compact context bundle: relevant entities, relationships, and cited source passages, sized to drop into a prompt. Reading the bundle instead of re-exploring the repo is where the latency and token savings come from.
-4. **Contribute** — agents and humans write learnings back. New facts are deduplicated against existing knowledge; repeated observations reinforce confidence instead of duplicating. Every fact carries a provenance receipt: observation count, confidence, sources.
-
-### 3.2 Surfaces
-
-- **Graph-as-files (zero-dependency surface)** — the graph materializes *into the tracked repo/folder itself*, in a format and location the user picks per repo: a single compact `CONTEXT.md`, a directory of interlinked markdown files (one per entity/module), or machine-readable JSONL; committed or gitignored. Any agent can read it natively — no MCP call, no server running — and it's grep-able, git-versioned, and PR-reviewable. Agents can even contribute back by writing to a designated learnings file that the watcher ingests. The background sync keeps these files current; the graph database remains the source of truth.
-- **MCP server** — the richer agent surface for targeted queries: compact context bundles sized for a prompt, plus structured contribute. Works with Claude Code, Cursor, and anything MCP-speaking, including Claude Code hooks and PR ingestion.
-- **Web UI** — the human surface: drop files, browse a readable map of your repos and folders, ask cited questions, add facts by hand to a team or personal graph.
-- **CLI & library** — for scripting and embedding in other tools.
-- **Team sync** — a git-native graph file (merge-safe under concurrent edits) or a shared Docker deployment at one URL.
-
-### 3.3 What we optimize for
-
-- **Freshness** — the graph tracks the filesystem without human effort; stale facts get pruned, not accumulated.
-- **Latency & token savings** — a task that costs an agent minutes of cold file exploration costs one graph read instead: on a real 344-file repo, benchmarks showed 31% fewer tool calls, −23% cost, and −17% latency. Measured, not promised — see `bench/`.
-- **Human readability** — the graph doubles as living documentation: a new teammate can browse it and understand a repo's structure, owners, and gotchas.
-
-### 3.4 Explicitly out of scope for v1
-
-- Cloud connectors (Slack, Notion, Drive) — local repos and folders first; connectors come later.
-- Hosted/SaaS offering — self-hosted only for now.
-- Fine-grained access control within a graph — a graph is shared wholesale or personal.
-
-## 4. Target users & ICP
-
-**1. The individual power-user of coding agents (beachhead).** A developer running Claude Code / Cursor daily on a handful of repos. They already maintain a CLAUDE.md by hand and feel it decaying; they want their agent to stop re-exploring the same codebase every session. Zero-friction adoption: one install, point at a repo, no team buy-in needed. Value lands in the first session.
-
-**2. Teams of 5–50 engineers using agents on a shared codebase.** The individual's graph becomes the team's when it's committed to the repo or served from one Docker URL. The motion: one champion adopts, the committed `.context/` files make it visible to everyone who clones, teammates onboard by browsing the graph. This is where shared agent memory and human-readable living documentation compound.
-
-**3. Knowledge-heavy teams and individuals beyond code.** Folders of PDFs, notes, research, runbooks, contracts — the same engine, pointed at documents instead of repos: watched folders stay fresh, answers come back cited, and the graph is a browsable map of what the team knows. Same self-hosted, local-first appeal (r/selfhosted, HN crowd) for people who won't ship their documents to a vendor's cloud.
-
-All three run on the same product — no separate editions. The segments differ only in what they point the engine at.
-
-## 5. Positioning & competition
-
-**One-liner:** *the self-maintaining context graph for your repos and folders — agents read it, write back to it, and it never goes stale.*
-
-How we differ, by neighbor:
-
-- **Context files (CLAUDE.md, AGENTS.md, .cursor/rules)** — today's default, generated and appended to by agents themselves. But nothing *manages* them: no change detection when the codebase moves underneath, no dedup or pruning (they bloat and drift), no provenance on any line, and the whole flat file is loaded every session regardless of the task. We are the management layer this pattern is missing — a structured graph behind it that stays fresh, with the context file as one generated, always-current output rather than an append-only scratchpad.
-- **Vector RAG stacks (LlamaIndex-style pipelines, codebase embeddings in Cursor)** — retrieval over chunks. No structure to reason over, no relationships, no confidence/provenance, no contribute path, and re-indexing is on you. We're a graph with typed relationships and a reinforcement loop, kept fresh automatically.
-- **Agent memory layers (mem0, Zep, Letta)** — memory of *conversations*, usually cloud-hosted, per-agent. We're memory of *your filesystem and codebase*, self-hosted, shared across every agent and human on the team. Complementary more than competitive.
-- **GraphRAG (Microsoft) and knowledge-graph research tools** — batch, one-shot, expensive to rebuild, no freshness story. Our whole thesis is the maintenance loop they lack.
-- **Enterprise search (Glean)** — per-seat SaaS, connector catalog, your documents in their cloud. We're self-hosted, free to start, repos-and-folders first. When we're compared to Glean, the answer is: different buyer, different trust model.
-
-**The moat we're building:** not extraction (everyone has an LLM) — the *maintenance intelligence*: knowing when to update, what to prune, and how confidence should evolve. That's accumulated product logic, and the graph itself compounds — the longer a team runs it, the more contributed learnings it holds that exist nowhere else.
-
-## 6. Open source strategy & licensing
-
-**Yes — the engine is open source, MIT-licensed, deliberately.**
-
-**Why OSS is the distribution strategy:** our target users (agent power-users, self-hosters) adopt from GitHub, HN, and word-of-mouth, and they specifically distrust closed tools that touch their source code. Open source is what earns the "your data never leaves your machine" claim credibility — anyone can verify it. It's also how a two-person project gets a connector/integration ecosystem it could never build alone.
-
-**The open-core line (when monetization starts):** the engine — ingest, freshness loop, graph, MCP, web UI, CLI — stays MIT forever; that's the promise that makes adoption safe. What can be proprietary later: the **hosted cloud version** (we run it for you), and **team/enterprise features** around the core (auth, roles, SSO, audit, central admin). This is the standard open-core playbook (GitLab, Supabase, PostHog) and it doesn't require relicensing anything we shipped.
-
-## 7. Teams & multi-user support
-
-_Current state (Docker single-URL sharing, git-native graph sync), what real "teams" means — auth, roles, permissions, hosted option — and when we'd build it. TODO._
-
-## 8. Release plan & milestones
-
-**Phase 0 — Harden the wedge.** Ship the things the pitch depends on: pruning/decay so the freshness claim is fully true, graph-as-files output, and a token/latency benchmark on 2–3 real repos. Exit criterion: a stranger can install, point at a repo, and get value in under 5 minutes without us in the room.
-
-**Phase 1 — Private alpha.** 10–20 hand-picked internal Nanonets users from segment 1 (coding-agent power-users). Goal is watching where onboarding breaks and whether people *keep* the watcher running after week one. Exit criterion: users still active after 10 days without prompting.
-
-**Phase 2 — Public OSS launch.** "Released" means: public repo, one-line install, docs good enough that issues are feature requests rather than confusion. Plan in §8.1.
-
-**Phase 3 — Team features.** Driven by what alpha/launch users actually ask for.
-
-### 8.1 Public launch plan
-
-**Assets:** README with a demo GIF + benchmark table, 2-min demo video, launch blog post, tested 5-min quickstart.
-
-**Channels:**
-- **Show HN** — *"Show HN: A context graph for your repos that AI agents read and keep fresh"*
-- **MCP directories** — official registry, Smithery, PulseMCP, mcp.so, Glama. Targeted, compounds over time.
-- **Awesome lists** — awesome-mcp-servers, awesome-selfhosted, awesome-claude-code.
-- **Reddit** — r/selfhosted, r/LocalLLaMA, r/ClaudeAI, r/cursor — each with its own angle.
-- **Communities & creators** — Claude Code/Cursor/MCP Discords, TLDR/Console.dev newsletters, a few agent-tooling YouTubers.
-
-## 9. Business model & monetization path
-
-_Free OSS core → what we could charge for (hosted, team/enterprise features, support). When monetization becomes relevant. TODO._
-
-## 10. Metrics & what winning looks like
-
-_Stars/installs/weekly active graphs, contribution-loop engagement, and the 6-month success criteria. TODO._
-
-## 11. Risks & open questions
-
-_Honest list: adoption risk, moat, model-cost dependency, and questions we want management input on. TODO._
diff --git a/PRODUCT-DESIGNS.md b/PRODUCT-DESIGNS.md
deleted file mode 100644
index e82b438b..00000000
--- a/PRODUCT-DESIGNS.md
+++ /dev/null
@@ -1,348 +0,0 @@
-# Context Graph Engine — Design Sketches for the Top 5 Product Ideas
-
-> **Purpose:** design sketches for the five candidate products, written to a
-> common template so they can be reviewed and scored side by side. Grounded in
-> the current codebase (`src/engine.ts`, `src/graph/*`, `src/ai/*`, `src/mcp.ts`).
->
-> **Frame (decided):** standalone, open-source, local-first, download-and-run,
-> aimed at **small teams / companies**, **pure OSS / grow-first**.
->
-> **Reviewer:** each idea uses the same 11 headings. Section 0 describes the
-> shared primitives (team sync, scoping, embedding consistency) that most ideas
-> depend on — read it first, it's referenced throughout.
-
----
-
-## What already exists (the substrate)
-
-The engine is real and most of a product already:
-
-- **Core API** (`ContextGraphEngine`): `ingest` / `ingestFile` / `ingestDir` / `read` / `contribute` / `exportGraph` / `stats`.
-- **Data model** (`graph/types.ts`): `GraphNode` and `GraphEdge` each carry `confidence`, `observations`, `provenance[]`, timestamps; `Chunk`s ground them in source text.
-- **Merge/reinforce** (`graph/merge.ts`): incoming entities are matched to existing nodes by exact normalized name/alias **and** embedding cosine ≥ `mergeThreshold`; matches reinforce (`observations += 1`, confidence → 1, provenance union), non-matches are created. Edges dedupe on `(source, target, relation)`.
-- **Storage** (`graph/store.ts` → `SqliteStore`): the engine talks to a **`GraphStore` interface**, so the backend is swappable (this is the single most important fact for the team ideas).
-- **Providers** (`ai/*`): local-first — in-process embeddings (transformers.js `all-MiniLM-L6-v2`, 384-dim) + Ollama extraction; auto-upgrades to OpenRouter/OpenAI when keys are present.
-- **Access modes**: library, `context-graph` CLI, `context-graph-mcp` MCP server (7 tools).
-- **Retrieval** (`retrieval/retriever.ts`): semantic match on nodes → one-hop expansion → supporting chunks → rendered prompt.
-- **Export** (`graph/export.ts`): interactive HTML / JSON / Mermaid.
-
-### Known gaps every idea must reckon with
-
-1. **Single graph per DB.** No namespaces/collections — one `.db` file = one graph. Multi-project scoping = separate DB files today, or a new `scope` column.
-2. **No team sync.** The graph is local to one machine. → **Section 0.1**.
-3. **Embedding provider must be consistent across a shared graph.** Vectors from different models aren't comparable; dedup/retrieval break if two members use different embedders. → **Section 0.3**.
-4. **In-memory vector search.** `allEmbeddedNodes()` loads all nodes to score. Fine for small-team scale (thousands of nodes); a ceiling to note, not fix now.
-5. **No delete / decay / temporal.** Facts don't expire or track "when true." Deferred features; matters for some ideas more than others.
-6. **No auth / access control.** Acceptable for local single-user; needs a story the moment a graph is shared over a network.
-
----
-
-## Section 0 — Shared primitives (referenced by ideas 1–4)
-
-### 0.1 Team sync — the one real new engineering task
-
-Most ideas reduce to "the same engine, but the graph is shared across a small
-team." Two modes, both leaning on the existing `GraphStore` interface and the
-fact that **merge is near-idempotent** (re-applying a contribution reinforces
-rather than corrupts).
-
-**Mode A — Git-native (zero infra, best for coding teams).**
-- Serialize the graph to a committed, human-diffable file: `.context-graph/graph.jsonl` (one node/edge/chunk per line) or a small directory of shards to reduce merge churn.
-- `pull` → import + **re-merge** remote records into the local graph using the *existing* `mergeExtraction`-style union (dedup by name/embedding, reinforce, union provenance). Because merge is commutative-ish, two people's additions combine without a central server.
-- `push` → re-serialize and commit. Conflicts resolve by union, not overwrite (take max `observations`, reinforced `confidence`, union `provenance`, newer `updatedAt` for `summary`).
-- Pros: zero infra, versioned, offline-friendly, code never leaves the repo. Cons: not real-time; embeddings bloat the file (store quantized or recompute on import).
-
-**Mode B — Shared store (near-real-time, best for non-code teams).**
-- Implement `GraphStore` against a shared backend. Recommended: **libSQL / Turso embedded replica** — a local SQLite file that syncs to a shared remote. This preserves *local-first* (reads/writes hit local) while giving *team-shared* state. Alternative: `PostgresStore` (+ pgvector) for a self-hosted server.
-- Pros: real-time, scales past git-file limits. Cons: someone runs the sync target (a Turso DB or a Postgres container).
-
-**Recommendation:** ship **Mode A first** (it's the differentiator and needs no infra), offer **Mode B** as an opt-in for larger/non-code teams. Both are additive — the engine core is untouched.
-
-### 0.2 Scoping / namespaces
-
-Teams have multiple projects. Minimal design: add an optional `scope` (a.k.a.
-`collection`) string to documents/nodes/edges, default `"default"`, filterable
-at read time. Cheaper interim: one DB file per project (already supported via
-`--db` / `CONTEXT_GRAPH_DB`). Recommend interim for v1, `scope` column when a
-single shared store hosts many projects (Mode B).
-
-### 0.3 Embedding consistency (a hard constraint, not a nice-to-have)
-
-A shared graph **must** pin one embedding model for all members, recorded in
-graph metadata; the engine should refuse (or warn + re-embed) on mismatch. For
-local-first teams, standardize on the in-process `all-MiniLM-L6-v2` so there are
-no keys and no drift. Cloud embeddings become a per-graph, all-or-nothing choice.
-
-### 0.4 Provenance & trust (already have the bones)
-
-`provenance[]` + `observations` + `confidence` already exist per node/edge. Every
-idea should surface these in its UX (who/what contributed a fact, how many times
-confirmed) — it's the built-in trust and "gets smarter" story.
-
----
-
-## Idea 1 — Shared memory for a team's coding agents ⭐ recommended beachhead
-
-**1. Positioning.** One self-hosted graph every developer's Claude Code / Cursor
-reads before working and writes learnings back to — so the team's agents stop
-re-learning the codebase, conventions, and the reasons behind past decisions.
-
-**2. Target user & JTBD.** Small eng teams (2–20). *"My AI agent doesn't know how
-**we** do things, so I re-explain our patterns every session and it repeats
-mistakes we already solved."*
-
-**3. Primary flows.**
-- *Bootstrap:* `context-graph ingest-dir ./` over the repo + docs → initial graph committed to `.context-graph/`.
-- *Before work (automatic):* agent calls `context_read` via MCP → gets conventions, gotchas, ownership, past decisions relevant to the task, with source lines.
-- *After work (automatic):* agent calls `context_contribute` with what it learned ("the retry helper lives in `net/backoff.ts`, not `util`"); merged + reinforced.
-- *Sync:* `git pull` merges teammates' contributions (Mode A); the graph rides the repo.
-
-**4. Architecture.** Reuses the engine wholesale. New: **Team Sync Mode A**
-(§0.1), a `context-graph sync` command + a git hook / CI step, and MCP tool
-polish. Optional: a "session recap" that batches an agent's session into one
-contribution.
-
-**5. Data model changes.** Add a `kind`/`type` vocabulary for code entities
-(`module`, `function`, `convention`, `decision`, `pitfall`, `owner`). Add
-`scope` = repo path if multi-repo (§0.2). Serialization format for git sync.
-
-**6. Hero feature.** **Write-back that survives `git pull`** — the graph is
-shared, versioned, and compounds across the whole team, and it visibly improves
-(confidence/observation counts) as everyone's agents use it.
-
-**7. MVP scope.**
-- *In:* repo ingest, MCP read/contribute (exists), Mode A git sync, code-aware entity types, a `sync`/merge command, README quickstart, the HTML graph view.
-- *Out:* web UI, real-time sync, access control, decay.
-
-**8. Effort.** **Low–Med.** The engine + MCP exist; the real work is sync + serialization + code-entity tuning. ~2–3 weeks to a launchable v1.
-
-**9. Distribution / GTM.** MCP directory listing, Show HN, `curl | sh`, a README
-demo GIF of the graph. Coding-agent devs are the most OSS-viral audience in 2026.
-Dogfood on this very repo (it's already an MCP server).
-
-**10. Success metrics.** GitHub stars, MCP installs, weekly-active graphs,
-**contributions-back per active graph per week** (the "is it compounding?" metric),
-% of teams with >1 contributor to a graph.
-
-**11. Risks / open questions for the reviewer.**
-- Does git-file sync stay clean once embeddings are in the file? (Quantize? Recompute on import? Separate embedding cache out of git?)
-- Contribution quality/noise: do we need a confidence floor or a review gate before a learning becomes readable?
-- Is "one graph per repo" the right unit, or per-monorepo-package?
-- Overlap with ByteRover — is "team-shared + reinforcing" a strong enough wedge vs their individual file-tree?
-
----
-
-## Idea 2 — Self-hosted "team brain" (the small-team Glean, but OSS)
-
-**1. Positioning.** Point it at a team's docs (Notion/Drive export, PDFs,
-markdown) → a self-improving knowledge graph both people and agents query, via a
-web UI to explore/ask and an MCP server so any agent taps in.
-
-**2. Target user & JTBD.** Small companies (10–100) where knowledge is scattered
-and Glean/Guru are too pricey/enterprise. *"Nobody can find the current answer,
-and the wiki is stale."*
-
-**3. Primary flows.**
-- *Ingest:* connect a source or drop a folder → graph builds (progress UI).
-- *Ask (human):* web search box → structured answer + source passages + a graph view of related entities.
-- *Ask (agent):* MCP `context_read`.
-- *Curate:* the graph self-reinforces; humans can confirm/flag a fact (bumps/curbs confidence).
-
-**4. Architecture.** Engine + **a new web app** (the big lift) + **Mode B shared
-store** (§0.1) so multiple users hit one graph + **connectors** (start with
-folder + Notion/Drive export). Auth needed once networked (§0 gap 6).
-
-**5. Data model changes.** `scope`/workspace column (§0.2); user identity for
-contributions; a `verified`/`flagged` state on nodes/edges layered over
-confidence; source-connector metadata on documents.
-
-**6. Hero feature.** **A living knowledge base that doesn't rot** — write-back +
-reinforcement keep it current, and humans + agents share exactly one source of
-truth, with the graph as a navigable map.
-
-**7. MVP scope.**
-- *In:* folder + one connector, Mode B store, web UI (search + answer + graph view + admin), basic auth, MCP read.
-- *Out:* fine-grained permissions, SSO, real-time collab, mobile.
-
-**8. Effort.** **Med–High.** The web UI + connectors + auth are net-new and are
-the bulk of the work. ~6–10 weeks to a credible v1.
-
-**9. Distribution / GTM.** Self-host via Docker; OSS repo; "the open, local Glean"
-narrative. Slower-burning than Idea 1 (not developer-viral by default).
-
-**10. Success metrics.** Deployed instances, weekly-active askers, queries/week,
-answer thumbs-up rate, fraction of answers with a cited source.
-
-**11. Risks / open questions.**
-- Scope creep: this competes with mature tools; UI quality bar is high.
-- Retrieval quality on heterogeneous docs — is one-hop + chunks enough, or do we need multi-hop / reranking?
-- In-memory vector search ceiling (§0 gap 4) arrives sooner here.
-- This is the **natural expansion of Idea 1**, not a cold start — is it premature to build before Idea 1 shows pull?
-
----
-
-## Idea 3 — Onboarding & tribal-knowledge brain (+ Slack bot)
-
-**1. Positioning.** Capture how your systems work, who owns what, and the answers
-that clog Slack — into a graph a bot answers from and learns from every thread.
-
-**2. Target user & JTBD.** Small teams with painful new-hire ramp and
-repeated questions. *"We answer the same onboarding questions every week."*
-
-**3. Primary flows.**
-- *Seed:* ingest onboarding docs, runbooks, an org/ownership sheet.
-- *Ask:* `@brain how do we deploy staging?` in Slack → answer + sources.
-- *Learn:* the bot ingests resolved threads (opt-in) via `contribute`, so answered questions strengthen the graph.
-- *Escalate:* if confidence is low, route to the owner entity in the graph.
-
-**4. Architecture.** Engine + **a Slack app** (events API, slash command, thread
-reader) + Mode B store (bot is a shared service). Reuses read/contribute directly.
-
-**5. Data model changes.** `owner`/`team` entity types + `owns`/`escalates_to`
-relations; thread/message provenance; confidence threshold config for
-"answer vs escalate."
-
-**6. Hero feature.** **The contribute/reinforce loop is a perfect fit** — every
-answered question makes the next answer better; low-confidence gaps auto-route to
-a human owner.
-
-**7. MVP scope.**
-- *In:* Slack bot (Q&A + thread ingest), doc ingest, owner/escalation entities, confidence-gated escalation.
-- *Out:* other chat platforms, analytics dashboard, auto-summarized weekly digests.
-
-**8. Effort.** **Med.** Self-contained; the Slack integration is the main new
-surface. ~4–6 weeks.
-
-**9. Distribution / GTM.** Slack App Directory + OSS self-host. Narrow, concrete,
-easy to explain; less developer-viral than Idea 1.
-
-**10. Success metrics.** Questions answered/week, % answered without escalation,
-median time-to-answer, new-hire "time to first useful answer," contributions from
-resolved threads.
-
-**11. Risks / open questions.**
-- Answer quality/hallucination on thin graphs — need a hard confidence floor + "I don't know, ask @owner."
-- Privacy: ingesting Slack threads needs clear opt-in and redaction.
-- Is a Slack bot the right first surface, or a thinner CLI/MCP bot to validate value faster?
-
----
-
-## Idea 4 — Support graph that learns from resolved tickets
-
-**1. Positioning.** A graph over help docs + resolved tickets; an agent drafts
-answers and every resolution reinforces what's actually true — support that
-compounds.
-
-**2. Target user & JTBD.** Small support/CS teams. *"We keep re-solving the same
-issues; our macros and docs drift from reality."*
-
-**3. Primary flows.**
-- *Seed:* ingest help center + historical resolved tickets.
-- *Draft:* on a new ticket, `read` → agent drafts a grounded reply with sources.
-- *Learn:* on resolution, `contribute` the accepted answer → reinforces the graph.
-- *Surface gaps:* low-confidence/frequent-miss topics flagged for a doc update.
-
-**4. Architecture.** Engine + **helpdesk connectors** (Zendesk/Intercom/email) +
-an answer-draft flow + Mode B store. Reuses read/contribute.
-
-**5. Data model changes.** `issue`/`product`/`resolution` entity types;
-ticket provenance; a "gap report" query over low-confidence high-frequency nodes.
-
-**6. Hero feature.** **Reinforcement is the native mechanic of support** — answers
-measurably improve as tickets close, and the system tells you which docs to write.
-
-**7. MVP scope.**
-- *In:* one helpdesk connector, doc ingest, draft-answer flow, resolution → contribute, gap report.
-- *Out:* full agent autopilot, multi-brand, SLA analytics.
-
-**8. Effort.** **Med.** Connectors + draft flow are the new work; furthest from
-current dogfooding, so slower to a credible internal demo.
-
-**9. Distribution / GTM.** Helpdesk marketplaces + OSS self-host. Clear ROI story;
-**most naturally monetizable later** (per-seat / per-resolution), but that's a
-later, post-grow question given the OSS-first frame.
-
-**10. Success metrics.** Draft-acceptance rate, deflection rate, handle-time
-reduction, docs created from gap reports, reinforcement events/week.
-
-**11. Risks / open questions.**
-- Wrong answers are costly in support — needs strong grounding + human-in-the-loop before send.
-- Connector maintenance burden (helpdesk APIs).
-- Weakest fit with "small **team**" if it drifts toward enterprise CS — keep it small-team scoped.
-
----
-
-## Idea 5 — The local-first memory layer (horizontal primitive)
-
-**1. Positioning.** "mem0, but local-first & TypeScript/MCP-native" — a drop-in
-memory any builder adds to any agent in one install, no keys, no database to
-stand up.
-
-**2. Target user & JTBD.** Developers building agents who want memory without
-cloud lock-in or a Python dependency. *"I want durable agent memory I can `npm i`
-and run offline."*
-
-**3. Primary flows.**
-- `npm i` / `curl | sh` → `read` / `contribute` in library, CLI, or MCP form.
-- Bring-your-own store via the `GraphStore` interface; local by default.
-
-**4. Architecture.** **Almost exactly what exists today.** The work is packaging:
-crisp API surface, docs, examples, a **published benchmark**, and framework
-adapters (LangChain.js, Vercel AI SDK, Mastra).
-
-**5. Data model changes.** Minimal. Maybe stabilize the public types and add
-memory "scopes" (user/session/agent) to match how the category is framed.
-
-**6. Hero feature.** **Zero-infra, TS/MCP-native, self-reinforcing memory** — the
-combination none of the Python/cloud incumbents offer by default.
-
-**7. MVP scope.**
-- *In:* API/docs hardening, adapters for 2–3 JS agent frameworks, a benchmark writeup, examples.
-- *Out:* everything vertical (no UI, no connectors, no team features).
-
-**8. Effort.** **Low.** Mostly docs, examples, benchmark, adapters. ~1–2 weeks to
-a stronger OSS release.
-
-**9. Distribution / GTM.** Pure GitHub-star play: benchmark blog post, framework
-adapter announcements, MCP directory, Show HN. Highest ceiling for stars, hardest
-to differentiate on story alone.
-
-**10. Success metrics.** Stars, npm weekly downloads, adapter installs, benchmark
-ranking, inbound "who's using it."
-
-**11. Risks / open questions.**
-- **Most crowded shelf** — "generic memory" without a sharp use case rarely wins attention; this is why it's framed as the *engine underneath Idea 1*, not the headline.
-- Benchmarking honestly against mem0/Zep (LongMemEval) may expose gaps (no temporal graph).
-- Positioning risk: "yet another memory lib" fatigue.
-
----
-
-## Cross-idea summary (for scoring)
-
-| # | Idea | Effort | Risk | New surface to build | OSS virality | Fit w/ current code |
-|---|------|--------|------|----------------------|--------------|---------------------|
-| 1 | Coding-agent team memory ⭐ | Low–Med | Med | Git sync + code entities | High | Highest (dogfooded) |
-| 2 | Team brain (OSS Glean) | Med–High | Med | Web UI + connectors + auth | Med | Med |
-| 3 | Onboarding + Slack bot | Med | Low–Med | Slack app | Med | Med |
-| 4 | Support graph | Med | Med | Helpdesk connectors + draft flow | Low | Med |
-| 5 | Memory primitive | Low | High | Docs/adapters/benchmark | High | Highest (as-is) |
-
-**Recommended path (unchanged):** ship **Idea 5's engine, packaged as Idea 1**,
-grow it OSS through developers, and let real-world usage pull toward **Idea 2**.
-Ideas 3 and 4 are strong standalone verticals if a specific design partner /
-pain shows up first.
-
-### The single sentence to defend
-> **Local-first + team-shared + TypeScript/MCP-native + self-reinforcing** —
-> the square of the memory market that no current player occupies.
-
----
-
-## Questions the reviewing model should pressure-test
-
-1. Is **team sync via git (Mode A)** genuinely robust given embeddings live in the graph, or does it force Mode B (a server) sooner than claimed?
-2. Is "coding-agent team memory" (Idea 1) a **strong enough wedge vs ByteRover**, or is the differentiation too thin?
-3. Does the **near-idempotent merge** actually hold under concurrent multi-writer merges, or are there conflict cases (e.g., two different summaries, contradictory facts) that need explicit resolution / a temporal layer?
-4. For pure-OSS grow-first, is Idea 1 or Idea 5 the better **top-of-funnel**, given 1 has a sharper story but 5 is closer to shippable today?
-5. Which idea best withstands the **"generic memory is commoditizing"** risk over a 12-month horizon?
-6. What's the **smallest possible v1** that proves the "gets smarter with team use" claim to real users?
diff --git a/docker-compose.yml b/docker-compose.yml
deleted file mode 100644
index 746ec3ec..00000000
--- a/docker-compose.yml
+++ /dev/null
@@ -1,24 +0,0 @@
-# Context Graph — one shared team-brain server (web UI + MCP-over-HTTP + watcher).
-#
-# docker compose up -d
-# cat ./data/share-link.txt # grab the access/share link
-#
-# The graph lives in ./data as a single SQLite file. Put documents you want to
-# ingest into ./docs and type /docs in the UI's "Ingest a folder" box.
-# Agents connect over MCP at http://<host>:4680/mcp (Bearer = the access token).
-services:
- context-graph:
- build: .
- ports:
- - "4680:4680"
- volumes:
- - ./data:/data
- - ./docs:/docs:ro
- environment:
- # Optional: cloud extraction + written answers. Without it the graph and
- # retrieval still work; extraction needs this key or a reachable Ollama.
- OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}
- # Optional: pin the access token. Otherwise one is generated once and
- # saved to ./data/share-link.txt (stable across restarts).
- CONTEXT_GRAPH_WEB_TOKEN: ${CONTEXT_GRAPH_WEB_TOKEN:-}
- restart: unless-stopped
diff --git a/examples/demo-docs/northwind-architecture.pdf b/examples/demo-docs/northwind-architecture.pdf
deleted file mode 100644
index a3ef16af..00000000
Binary files a/examples/demo-docs/northwind-architecture.pdf and /dev/null differ
diff --git a/examples/demo-docs/northwind-billing-runbook.pdf b/examples/demo-docs/northwind-billing-runbook.pdf
deleted file mode 100644
index 6a16122c..00000000
Binary files a/examples/demo-docs/northwind-billing-runbook.pdf and /dev/null differ
diff --git a/examples/demo-docs/northwind-glossary.md b/examples/demo-docs/northwind-glossary.md
deleted file mode 100644
index 41750f08..00000000
--- a/examples/demo-docs/northwind-glossary.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Northwind Glossary
-
-**Dunning**: The automated process of retrying failed payments and notifying
-customers before suspending an account. Owned by the Payments team.
-
-**past_due**: The subscription state entered after three failed charge retries.
-An account in past_due for 7 days is automatically suspended.
-
-**SLO**: Northwind's charge success rate service-level objective is 97%. The
-error budget is exhausted if the rate drops below 95% for 30 minutes.
-
-**Blue-green deploy**: The Platform team's deployment strategy. New versions are
-rolled out to a green environment on Kubernetes before traffic is switched over.
-
-**On-call**: Each team runs a weekly PagerDuty rotation. The billing rotation is
-`northwind-billing`; the platform rotation is `northwind-platform`.
diff --git a/examples/demo-docs/northwind-onboarding.pdf b/examples/demo-docs/northwind-onboarding.pdf
deleted file mode 100644
index 87ed7150..00000000
Binary files a/examples/demo-docs/northwind-onboarding.pdf and /dev/null differ
diff --git a/examples/quickstart.ts b/examples/quickstart.ts
deleted file mode 100644
index dbe3765b..00000000
--- a/examples/quickstart.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-/**
- * Quickstart. Runs with either cloud or fully-local providers:
- *
- * # Cloud extraction via OpenRouter (embeddings stay local unless OPENAI_API_KEY is set):
- * export OPENROUTER_API_KEY=sk-or-...
- * npm run example
- *
- * # Or fully local — no keys — with a running Ollama (`ollama pull llama3.2`).
- *
- * Uses an in-memory graph so it leaves nothing behind.
- */
-import "dotenv/config";
-import { ContextGraphEngine } from "../src/index.js";
-
-const DOCS = `
-# Payments Platform
-
-The Billing Service charges customers monthly. It calls the Payments Gateway,
-which integrates with Stripe. Failed charges are retried by the Dunning Worker
-up to three times before the subscription is marked past_due.
-
-Invoices are generated by the Invoicing Service and stored in Postgres. The
-Billing Service reads customer plans from the Catalog Service.
-`;
-
-async function main() {
- const engine = new ContextGraphEngine({ dbPath: ":memory:" });
-
- console.log("Ingesting docs…");
- const ing = await engine.ingest(DOCS, { title: "Payments Platform" });
- console.log(
- ` ${ing.chunks} chunks -> +${ing.nodesCreated} entities, +${ing.edgesCreated} relationships\n`,
- );
-
- console.log("Reading context for an agent task:");
- const bundle = await engine.read("what happens when a charge fails?");
- console.log(bundle.prompt);
-
- console.log("\nAn agent contributes a learning back:");
- const c = await engine.contribute(
- "The Dunning Worker sends a Slack alert to #billing after the final failed retry.",
- { agentId: "oncall-agent" },
- );
- console.log(` +${c.nodesCreated} entities, ${c.nodesUpdated} reinforced\n`);
-
- console.log("Reading again — the new learning is now part of the graph:");
- const after = await engine.read("how is the team notified about failed charges?");
- console.log(after.prompt);
-
- console.log("\nFinal graph:", await engine.stats());
- await engine.close();
-}
-
-main().catch((err) => {
- console.error(err);
- process.exit(1);
-});
diff --git a/install.sh b/install.sh
index 8509e16e..c3b262e5 100755
--- a/install.sh
+++ b/install.sh
@@ -5,9 +5,8 @@
# 1. From a checkout: ./install.sh (builds THIS directory — no re-clone)
# 2. Over the network: curl -fsSL https://raw.githubusercontent.com/NanoNets/context-graph-engine/main/install.sh | sh
#
-# Either way it builds the project and puts the `context-graph`,
-# `context-graph-mcp`, and `context-graph-web` commands on your PATH.
-# Requires git, Node >= 20, and npm.
+# Either way it builds the project and puts the `context-graph` command on your
+# PATH. Requires git, Node >= 20, and npm.
#
# Environment overrides:
# CGE_REPO git URL to clone from (default: the NanoNets repo below)
@@ -67,28 +66,24 @@ info "Installing dependencies"
info "Building"
( cd "$INSTALL_DIR" && npm run build --silent )
-info "Linking the 'context-graph', 'context-graph-mcp', and 'context-graph-web' commands"
+info "Linking the 'context-graph' command"
( cd "$INSTALL_DIR" && npm link >/dev/null 2>&1 )
echo
-info "Installed. Try: context-graph-web"
+info "Installed. Try it in any repo:"
cat <<'NEXT'
- The web UI is the fastest way in:
- context-graph-web
- # → open http://localhost:4680, ingest a folder of docs, ask questions
+ Build the graph, then commit it:
+ cd your-repo
+ context-graph init # writes .context/*.md from your code
+ git add .context && git commit -m "add context graph"
- Runs locally out of the box:
- • Embeddings run in-process (no key, no server — model downloads on first use).
- • Extraction defaults to a local Ollama model. Install Ollama and pull one:
- https://ollama.com then ollama pull llama3.2
-
- Prefer higher-quality cloud extraction? Set a key and it's used automatically:
- export OPENROUTER_API_KEY=sk-or-... # extraction via OpenRouter
- export OPENAI_API_KEY=sk-... # embeddings (optional)
+ Keep it honest in CI:
+ context-graph check # exits non-zero if the graph is stale
- Quick start:
- echo "Our billing worker retries failed charges 3x then marks past_due." \
- | context-graph ingest-text --title "Billing"
- context-graph query "how are failed charges handled?"
+ Runs locally out of the box:
+ • Extraction/summaries default to a local Ollama model. Install Ollama and
+ pull one: https://ollama.com then ollama pull llama3.2
+ • Prefer cloud quality? Set a key and it's used automatically:
+ export OPENROUTER_API_KEY=sk-or-...
NEXT
diff --git a/package-lock.json b/package-lock.json
index 62ed6d78..5046e710 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,26 +9,16 @@
"version": "0.1.0",
"license": "MIT",
"dependencies": {
- "@huggingface/transformers": "^3.8.1",
- "@modelcontextprotocol/sdk": "^1.29.0",
- "better-sqlite3": "^12.11.1",
- "chokidar": "^4.0.3",
"commander": "^15.0.0",
"dotenv": "^17.4.2",
- "openai": "^6.45.0",
- "unpdf": "^1.6.2",
- "zod": "^4.4.3"
+ "gray-matter": "^4.0.3",
+ "openai": "^6.45.0"
},
"bin": {
- "context-graph": "dist/cli.js",
- "context-graph-mcp": "dist/mcp.js",
- "context-graph-serve": "dist/serve.js",
- "context-graph-web": "dist/web.js"
+ "context-graph": "dist/cli.js"
},
"devDependencies": {
- "@types/better-sqlite3": "^7.6.13",
"@types/node": "^26.1.0",
- "pdfkit": "^0.17.2",
"tsx": "^4.22.4",
"typescript": "^6.0.3"
},
@@ -36,16 +26,6 @@
"node": ">=20"
}
},
- "node_modules/@emnapi/runtime": {
- "version": "1.11.2",
- "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.2.tgz",
- "integrity": "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==",
- "license": "MIT",
- "optional": true,
- "dependencies": {
- "tslib": "^2.4.0"
- }
- },
"node_modules/@esbuild/aix-ppc64": {
"version": "0.28.1",
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
@@ -488,2712 +468,232 @@
"node": ">=18"
}
},
- "node_modules/@hono/node-server": {
- "version": "1.19.14",
- "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
- "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
+ "node_modules/@types/node": {
+ "version": "26.1.0",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-26.1.0.tgz",
+ "integrity": "sha512-O0A1G3xPGy4w7AgQdAQYUlQ+BKk2Oovw8eRpofyp5KdBZULnbe+WqaOVNrm705SHphCiG4XHsACrSmPu1f+Kgw==",
+ "dev": true,
"license": "MIT",
- "engines": {
- "node": ">=18.14.1"
- },
- "peerDependencies": {
- "hono": "^4"
+ "dependencies": {
+ "undici-types": "~8.3.0"
}
},
- "node_modules/@huggingface/jinja": {
- "version": "0.5.9",
- "resolved": "https://registry.npmjs.org/@huggingface/jinja/-/jinja-0.5.9.tgz",
- "integrity": "sha512-uWTG+l3VJRsl7EXxYizuL3P+cCPoc3cRqbWWRcQN0FhejRfbdq0RNhCmbY/YDtnTcz9icdLYuLDjsnz4d8JMuw==",
+ "node_modules/argparse": {
+ "version": "1.0.10",
+ "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
+ "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
"license": "MIT",
- "engines": {
- "node": ">=18"
- }
- },
- "node_modules/@huggingface/transformers": {
- "version": "3.8.1",
- "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-3.8.1.tgz",
- "integrity": "sha512-tsTk4zVjImqdqjS8/AOZg2yNLd1z9S5v+7oUPpXaasDRwEDhB+xnglK1k5cad26lL5/ZIaeREgWWy0bs9y9pPA==",
- "license": "Apache-2.0",
"dependencies": {
- "@huggingface/jinja": "^0.5.3",
- "onnxruntime-node": "1.21.0",
- "onnxruntime-web": "1.22.0-dev.20250409-89f8206ba4",
- "sharp": "^0.34.1"
+ "sprintf-js": "~1.0.2"
}
},
- "node_modules/@img/colour": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz",
- "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==",
+ "node_modules/argparse/node_modules/sprintf-js": {
+ "version": "1.0.3",
+ "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
+ "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/commander": {
+ "version": "15.0.0",
+ "resolved": "https://registry.npmjs.org/commander/-/commander-15.0.0.tgz",
+ "integrity": "sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==",
"license": "MIT",
"engines": {
- "node": ">=18"
+ "node": ">=22.12.0"
}
},
- "node_modules/@img/sharp-darwin-arm64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
- "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
- "cpu": [
- "arm64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "darwin"
- ],
+ "node_modules/dotenv": {
+ "version": "17.4.2",
+ "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.4.2.tgz",
+ "integrity": "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==",
+ "license": "BSD-2-Clause",
"engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+ "node": ">=12"
},
"funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-darwin-arm64": "1.2.4"
+ "url": "https://dotenvx.com"
}
},
- "node_modules/@img/sharp-darwin-x64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
- "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
- "cpu": [
- "x64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "darwin"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+ "node_modules/esbuild": {
+ "version": "0.28.1",
+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
+ "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "bin": {
+ "esbuild": "bin/esbuild"
},
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "engines": {
+ "node": ">=18"
},
"optionalDependencies": {
- "@img/sharp-libvips-darwin-x64": "1.2.4"
+ "@esbuild/aix-ppc64": "0.28.1",
+ "@esbuild/android-arm": "0.28.1",
+ "@esbuild/android-arm64": "0.28.1",
+ "@esbuild/android-x64": "0.28.1",
+ "@esbuild/darwin-arm64": "0.28.1",
+ "@esbuild/darwin-x64": "0.28.1",
+ "@esbuild/freebsd-arm64": "0.28.1",
+ "@esbuild/freebsd-x64": "0.28.1",
+ "@esbuild/linux-arm": "0.28.1",
+ "@esbuild/linux-arm64": "0.28.1",
+ "@esbuild/linux-ia32": "0.28.1",
+ "@esbuild/linux-loong64": "0.28.1",
+ "@esbuild/linux-mips64el": "0.28.1",
+ "@esbuild/linux-ppc64": "0.28.1",
+ "@esbuild/linux-riscv64": "0.28.1",
+ "@esbuild/linux-s390x": "0.28.1",
+ "@esbuild/linux-x64": "0.28.1",
+ "@esbuild/netbsd-arm64": "0.28.1",
+ "@esbuild/netbsd-x64": "0.28.1",
+ "@esbuild/openbsd-arm64": "0.28.1",
+ "@esbuild/openbsd-x64": "0.28.1",
+ "@esbuild/openharmony-arm64": "0.28.1",
+ "@esbuild/sunos-x64": "0.28.1",
+ "@esbuild/win32-arm64": "0.28.1",
+ "@esbuild/win32-ia32": "0.28.1",
+ "@esbuild/win32-x64": "0.28.1"
}
},
- "node_modules/@img/sharp-libvips-darwin-arm64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
- "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
- "cpu": [
- "arm64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "darwin"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/esprima": {
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
+ "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
+ "license": "BSD-2-Clause",
+ "bin": {
+ "esparse": "bin/esparse.js",
+ "esvalidate": "bin/esvalidate.js"
+ },
+ "engines": {
+ "node": ">=4"
}
},
- "node_modules/@img/sharp-libvips-darwin-x64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
- "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
- "cpu": [
- "x64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "darwin"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/extend-shallow": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+ "integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==",
+ "license": "MIT",
+ "dependencies": {
+ "is-extendable": "^0.1.0"
+ },
+ "engines": {
+ "node": ">=0.10.0"
}
},
- "node_modules/@img/sharp-libvips-linux-arm": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
- "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
- "cpu": [
- "arm"
- ],
- "license": "LGPL-3.0-or-later",
+ "node_modules/fsevents": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+ "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
"optional": true,
"os": [
- "linux"
+ "darwin"
],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
}
},
- "node_modules/@img/sharp-libvips-linux-arm64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
- "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
- "cpu": [
- "arm64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/gray-matter": {
+ "version": "4.0.3",
+ "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz",
+ "integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==",
+ "license": "MIT",
+ "dependencies": {
+ "js-yaml": "^3.13.1",
+ "kind-of": "^6.0.2",
+ "section-matter": "^1.0.0",
+ "strip-bom-string": "^1.0.0"
+ },
+ "engines": {
+ "node": ">=6.0"
}
},
- "node_modules/@img/sharp-libvips-linux-ppc64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
- "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
- "cpu": [
- "ppc64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/is-extendable": {
+ "version": "0.1.1",
+ "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
+ "integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
}
},
- "node_modules/@img/sharp-libvips-linux-riscv64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
- "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
- "cpu": [
- "riscv64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/js-yaml": {
+ "version": "3.15.0",
+ "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz",
+ "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==",
+ "license": "MIT",
+ "dependencies": {
+ "argparse": "^1.0.7",
+ "esprima": "^4.0.0"
+ },
+ "bin": {
+ "js-yaml": "bin/js-yaml.js"
}
},
- "node_modules/@img/sharp-libvips-linux-s390x": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
- "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
- "cpu": [
- "s390x"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/kind-of": {
+ "version": "6.0.3",
+ "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
+ "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
}
},
- "node_modules/@img/sharp-libvips-linux-x64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
- "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
- "cpu": [
- "x64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/openai": {
+ "version": "6.45.0",
+ "resolved": "https://registry.npmjs.org/openai/-/openai-6.45.0.tgz",
+ "integrity": "sha512-5DQVNErssk0afNpTTHUm/qZPU4iKR9OYdNid8Ib4puq4gHNNvGWZht2zY4h9a8JMF949Ik6m8gQutllVPbjdnw==",
+ "license": "Apache-2.0",
+ "peerDependencies": {
+ "@aws-sdk/credential-provider-node": ">=3.972.0 <4",
+ "@smithy/hash-node": ">=4.3.0 <5",
+ "@smithy/signature-v4": ">=5.4.0 <6",
+ "ws": "^8.18.0",
+ "zod": "^3.25 || ^4.0"
+ },
+ "peerDependenciesMeta": {
+ "@aws-sdk/credential-provider-node": {
+ "optional": true
+ },
+ "@smithy/hash-node": {
+ "optional": true
+ },
+ "@smithy/signature-v4": {
+ "optional": true
+ },
+ "ws": {
+ "optional": true
+ },
+ "zod": {
+ "optional": true
+ }
}
},
- "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
- "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
- "cpu": [
- "arm64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/section-matter": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
+ "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
+ "license": "MIT",
+ "dependencies": {
+ "extend-shallow": "^2.0.1",
+ "kind-of": "^6.0.0"
+ },
+ "engines": {
+ "node": ">=4"
}
},
- "node_modules/@img/sharp-libvips-linuxmusl-x64": {
- "version": "1.2.4",
- "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
- "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
- "cpu": [
- "x64"
- ],
- "license": "LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "linux"
- ],
- "funding": {
- "url": "https://opencollective.com/libvips"
+ "node_modules/strip-bom-string": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
+ "integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
}
},
- "node_modules/@img/sharp-linux-arm": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
- "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
- "cpu": [
- "arm"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linux-arm": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linux-arm64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
- "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
- "cpu": [
- "arm64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linux-arm64": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linux-ppc64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
- "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
- "cpu": [
- "ppc64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linux-ppc64": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linux-riscv64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
- "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
- "cpu": [
- "riscv64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linux-riscv64": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linux-s390x": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
- "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
- "cpu": [
- "s390x"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linux-s390x": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linux-x64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
- "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
- "cpu": [
- "x64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linux-x64": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linuxmusl-arm64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
- "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
- "cpu": [
- "arm64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
- }
- },
- "node_modules/@img/sharp-linuxmusl-x64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
- "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
- "cpu": [
- "x64"
- ],
- "license": "Apache-2.0",
- "optional": true,
- "os": [
- "linux"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
- }
- },
- "node_modules/@img/sharp-wasm32": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
- "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
- "cpu": [
- "wasm32"
- ],
- "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
- "optional": true,
- "dependencies": {
- "@emnapi/runtime": "^1.7.0"
- },
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- }
- },
- "node_modules/@img/sharp-win32-arm64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
- "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
- "cpu": [
- "arm64"
- ],
- "license": "Apache-2.0 AND LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "win32"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- }
- },
- "node_modules/@img/sharp-win32-ia32": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
- "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
- "cpu": [
- "ia32"
- ],
- "license": "Apache-2.0 AND LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "win32"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- }
- },
- "node_modules/@img/sharp-win32-x64": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
- "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
- "cpu": [
- "x64"
- ],
- "license": "Apache-2.0 AND LGPL-3.0-or-later",
- "optional": true,
- "os": [
- "win32"
- ],
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- }
- },
- "node_modules/@isaacs/fs-minipass": {
- "version": "4.0.1",
- "resolved": "https://registry.npmjs.org/@isaacs/fs-minipass/-/fs-minipass-4.0.1.tgz",
- "integrity": "sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==",
- "license": "ISC",
- "dependencies": {
- "minipass": "^7.0.4"
- },
- "engines": {
- "node": ">=18.0.0"
- }
- },
- "node_modules/@modelcontextprotocol/sdk": {
- "version": "1.29.0",
- "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
- "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
- "license": "MIT",
- "dependencies": {
- "@hono/node-server": "^1.19.9",
- "ajv": "^8.17.1",
- "ajv-formats": "^3.0.1",
- "content-type": "^1.0.5",
- "cors": "^2.8.5",
- "cross-spawn": "^7.0.5",
- "eventsource": "^3.0.2",
- "eventsource-parser": "^3.0.0",
- "express": "^5.2.1",
- "express-rate-limit": "^8.2.1",
- "hono": "^4.11.4",
- "jose": "^6.1.3",
- "json-schema-typed": "^8.0.2",
- "pkce-challenge": "^5.0.0",
- "raw-body": "^3.0.0",
- "zod": "^3.25 || ^4.0",
- "zod-to-json-schema": "^3.25.1"
- },
- "engines": {
- "node": ">=18"
- },
- "peerDependencies": {
- "@cfworker/json-schema": "^4.1.1",
- "zod": "^3.25 || ^4.0"
- },
- "peerDependenciesMeta": {
- "@cfworker/json-schema": {
- "optional": true
- },
- "zod": {
- "optional": false
- }
- }
- },
- "node_modules/@protobufjs/aspromise": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
- "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/base64": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz",
- "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/codegen": {
- "version": "2.0.5",
- "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
- "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/eventemitter": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
- "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/fetch": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz",
- "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
- "license": "BSD-3-Clause",
- "dependencies": {
- "@protobufjs/aspromise": "^1.1.1"
- }
- },
- "node_modules/@protobufjs/float": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz",
- "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/path": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
- "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/pool": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz",
- "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@protobufjs/utf8": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz",
- "integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==",
- "license": "BSD-3-Clause"
- },
- "node_modules/@swc/helpers": {
- "version": "0.5.23",
- "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.23.tgz",
- "integrity": "sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==",
- "dev": true,
- "license": "Apache-2.0",
- "dependencies": {
- "tslib": "^2.8.0"
- }
- },
- "node_modules/@types/better-sqlite3": {
- "version": "7.6.13",
- "resolved": "https://registry.npmjs.org/@types/better-sqlite3/-/better-sqlite3-7.6.13.tgz",
- "integrity": "sha512-NMv9ASNARoKksWtsq/SHakpYAYnhBrQgGD8zkLYk/jaK8jUGn08CfEdTRgYhMypUQAfzSP8W6gNLe0q19/t4VA==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "@types/node": "*"
- }
- },
- "node_modules/@types/node": {
- "version": "26.1.0",
- "resolved": "https://registry.npmjs.org/@types/node/-/node-26.1.0.tgz",
- "integrity": "sha512-O0A1G3xPGy4w7AgQdAQYUlQ+BKk2Oovw8eRpofyp5KdBZULnbe+WqaOVNrm705SHphCiG4XHsACrSmPu1f+Kgw==",
- "license": "MIT",
- "dependencies": {
- "undici-types": "~8.3.0"
- }
- },
- "node_modules/accepts": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
- "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==",
- "license": "MIT",
- "dependencies": {
- "mime-types": "^3.0.0",
- "negotiator": "^1.0.0"
- },
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/ajv": {
- "version": "8.20.0",
- "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
- "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
- "license": "MIT",
- "dependencies": {
- "fast-deep-equal": "^3.1.3",
- "fast-uri": "^3.0.1",
- "json-schema-traverse": "^1.0.0",
- "require-from-string": "^2.0.2"
- },
- "funding": {
- "type": "github",
- "url": "https://github.com/sponsors/epoberezkin"
- }
- },
- "node_modules/ajv-formats": {
- "version": "3.0.1",
- "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
- "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
- "license": "MIT",
- "dependencies": {
- "ajv": "^8.0.0"
- },
- "peerDependencies": {
- "ajv": "^8.0.0"
- },
- "peerDependenciesMeta": {
- "ajv": {
- "optional": true
- }
- }
- },
- "node_modules/base64-js": {
- "version": "1.5.1",
- "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
- "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/feross"
- },
- {
- "type": "patreon",
- "url": "https://www.patreon.com/feross"
- },
- {
- "type": "consulting",
- "url": "https://feross.org/support"
- }
- ],
- "license": "MIT"
- },
- "node_modules/better-sqlite3": {
- "version": "12.11.1",
- "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.11.1.tgz",
- "integrity": "sha512-dq9AtApgg5PGFtBzPFSBl3HZQjHok5gaQCM6zh2Yk0aSmDCs1CbnVI8/HgASQkNKsWFpseIO9beg5xxpYhbIfA==",
- "hasInstallScript": true,
- "license": "MIT",
- "dependencies": {
- "bindings": "^1.5.0",
- "prebuild-install": "^7.1.1"
- },
- "engines": {
- "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
- }
- },
- "node_modules/bindings": {
- "version": "1.5.0",
- "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
- "integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==",
- "license": "MIT",
- "dependencies": {
- "file-uri-to-path": "1.0.0"
- }
- },
- "node_modules/bl": {
- "version": "4.1.0",
- "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
- "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
- "license": "MIT",
- "dependencies": {
- "buffer": "^5.5.0",
- "inherits": "^2.0.4",
- "readable-stream": "^3.4.0"
- }
- },
- "node_modules/body-parser": {
- "version": "2.3.0",
- "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz",
- "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==",
- "license": "MIT",
- "dependencies": {
- "bytes": "^3.1.2",
- "content-type": "^2.0.0",
- "debug": "^4.4.3",
- "http-errors": "^2.0.1",
- "iconv-lite": "^0.7.2",
- "on-finished": "^2.4.1",
- "qs": "^6.15.2",
- "raw-body": "^3.0.2",
- "type-is": "^2.1.0"
- },
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/body-parser/node_modules/content-type": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.0.0.tgz",
- "integrity": "sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ==",
- "license": "MIT",
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/boolean": {
- "version": "3.2.0",
- "resolved": "https://registry.npmjs.org/boolean/-/boolean-3.2.0.tgz",
- "integrity": "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw==",
- "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
- "license": "MIT"
- },
- "node_modules/brotli": {
- "version": "1.3.3",
- "resolved": "https://registry.npmjs.org/brotli/-/brotli-1.3.3.tgz",
- "integrity": "sha512-oTKjJdShmDuGW94SyyaoQvAjf30dZaHnjJ8uAF+u2/vGJkJbJPJAT1gDiOJP5v1Zb6f9KEyW/1HpuaWIXtGHPg==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "base64-js": "^1.1.2"
- }
- },
- "node_modules/browserify-zlib": {
- "version": "0.2.0",
- "resolved": "https://registry.npmjs.org/browserify-zlib/-/browserify-zlib-0.2.0.tgz",
- "integrity": "sha512-Z942RysHXmJrhqk88FmKBVq/v5tqmSkDz7p54G/MGyjMnCFFnC79XWNbg+Vta8W6Wb2qtSZTSxIGkJrRpCFEiA==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "pako": "~1.0.5"
- }
- },
- "node_modules/buffer": {
- "version": "5.7.1",
- "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
- "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/feross"
- },
- {
- "type": "patreon",
- "url": "https://www.patreon.com/feross"
- },
- {
- "type": "consulting",
- "url": "https://feross.org/support"
- }
- ],
- "license": "MIT",
- "dependencies": {
- "base64-js": "^1.3.1",
- "ieee754": "^1.1.13"
- }
- },
- "node_modules/bytes": {
- "version": "3.1.2",
- "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
- "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/call-bind-apply-helpers": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
- "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0",
- "function-bind": "^1.1.2"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/call-bound": {
- "version": "1.0.4",
- "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
- "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
- "license": "MIT",
- "dependencies": {
- "call-bind-apply-helpers": "^1.0.2",
- "get-intrinsic": "^1.3.0"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/chokidar": {
- "version": "4.0.3",
- "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
- "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
- "license": "MIT",
- "dependencies": {
- "readdirp": "^4.0.1"
- },
- "engines": {
- "node": ">= 14.16.0"
- },
- "funding": {
- "url": "https://paulmillr.com/funding/"
- }
- },
- "node_modules/chownr": {
- "version": "1.1.4",
- "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz",
- "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==",
- "license": "ISC"
- },
- "node_modules/clone": {
- "version": "2.1.2",
- "resolved": "https://registry.npmjs.org/clone/-/clone-2.1.2.tgz",
- "integrity": "sha512-3Pe/CF1Nn94hyhIYpjtiLhdCoEoz0DqQ+988E9gmeEdQZlojxnOb74wctFyuwWQHzqyf9X7C7MG8juUpqBJT8w==",
- "dev": true,
- "license": "MIT",
- "engines": {
- "node": ">=0.8"
- }
- },
- "node_modules/commander": {
- "version": "15.0.0",
- "resolved": "https://registry.npmjs.org/commander/-/commander-15.0.0.tgz",
- "integrity": "sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==",
- "license": "MIT",
- "engines": {
- "node": ">=22.12.0"
- }
- },
- "node_modules/content-disposition": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz",
- "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==",
- "license": "MIT",
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/content-type": {
- "version": "1.0.5",
- "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz",
- "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/cookie": {
- "version": "0.7.2",
- "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
- "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/cookie-signature": {
- "version": "1.2.2",
- "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
- "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
- "license": "MIT",
- "engines": {
- "node": ">=6.6.0"
- }
- },
- "node_modules/cors": {
- "version": "2.8.6",
- "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
- "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
- "license": "MIT",
- "dependencies": {
- "object-assign": "^4",
- "vary": "^1"
- },
- "engines": {
- "node": ">= 0.10"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/cross-spawn": {
- "version": "7.0.6",
- "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
- "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
- "license": "MIT",
- "dependencies": {
- "path-key": "^3.1.0",
- "shebang-command": "^2.0.0",
- "which": "^2.0.1"
- },
- "engines": {
- "node": ">= 8"
- }
- },
- "node_modules/crypto-js": {
- "version": "4.2.0",
- "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz",
- "integrity": "sha512-KALDyEYgpY+Rlob/iriUtjV6d5Eq+Y191A5g4UqLAi8CyGP9N1+FdVbkc1SxKc2r4YAYqG8JzO2KGL+AizD70Q==",
- "dev": true,
- "license": "MIT"
- },
- "node_modules/debug": {
- "version": "4.4.3",
- "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
- "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
- "license": "MIT",
- "dependencies": {
- "ms": "^2.1.3"
- },
- "engines": {
- "node": ">=6.0"
- },
- "peerDependenciesMeta": {
- "supports-color": {
- "optional": true
- }
- }
- },
- "node_modules/decompress-response": {
- "version": "6.0.0",
- "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
- "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
- "license": "MIT",
- "dependencies": {
- "mimic-response": "^3.1.0"
- },
- "engines": {
- "node": ">=10"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/deep-extend": {
- "version": "0.6.0",
- "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
- "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
- "license": "MIT",
- "engines": {
- "node": ">=4.0.0"
- }
- },
- "node_modules/define-data-property": {
- "version": "1.1.4",
- "resolved": "https://registry.npmjs.org/define-data-property/-/define-data-property-1.1.4.tgz",
- "integrity": "sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==",
- "license": "MIT",
- "dependencies": {
- "es-define-property": "^1.0.0",
- "es-errors": "^1.3.0",
- "gopd": "^1.0.1"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/define-properties": {
- "version": "1.2.1",
- "resolved": "https://registry.npmjs.org/define-properties/-/define-properties-1.2.1.tgz",
- "integrity": "sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==",
- "license": "MIT",
- "dependencies": {
- "define-data-property": "^1.0.1",
- "has-property-descriptors": "^1.0.0",
- "object-keys": "^1.1.1"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/depd": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
- "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/detect-libc": {
- "version": "2.1.2",
- "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
- "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
- "license": "Apache-2.0",
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/detect-node": {
- "version": "2.1.0",
- "resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz",
- "integrity": "sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==",
- "license": "MIT"
- },
- "node_modules/dfa": {
- "version": "1.2.0",
- "resolved": "https://registry.npmjs.org/dfa/-/dfa-1.2.0.tgz",
- "integrity": "sha512-ED3jP8saaweFTjeGX8HQPjeC1YYyZs98jGNZx6IiBvxW7JG5v492kamAQB3m2wop07CvU/RQmzcKr6bgcC5D/Q==",
- "dev": true,
- "license": "MIT"
- },
- "node_modules/dotenv": {
- "version": "17.4.2",
- "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.4.2.tgz",
- "integrity": "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==",
- "license": "BSD-2-Clause",
- "engines": {
- "node": ">=12"
- },
- "funding": {
- "url": "https://dotenvx.com"
- }
- },
- "node_modules/dunder-proto": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
- "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
- "license": "MIT",
- "dependencies": {
- "call-bind-apply-helpers": "^1.0.1",
- "es-errors": "^1.3.0",
- "gopd": "^1.2.0"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/ee-first": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
- "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
- "license": "MIT"
- },
- "node_modules/encodeurl": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
- "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/end-of-stream": {
- "version": "1.4.5",
- "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
- "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
- "license": "MIT",
- "dependencies": {
- "once": "^1.4.0"
- }
- },
- "node_modules/es-define-property": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
- "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/es-errors": {
- "version": "1.3.0",
- "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
- "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/es-object-atoms": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz",
- "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/es6-error": {
- "version": "4.1.1",
- "resolved": "https://registry.npmjs.org/es6-error/-/es6-error-4.1.1.tgz",
- "integrity": "sha512-Um/+FxMr9CISWh0bi5Zv0iOD+4cFh5qLeks1qhAopKVAJw3drgKbKySikp7wGhDL0HPeaja0P5ULZrxLkniUVg==",
- "license": "MIT"
- },
- "node_modules/esbuild": {
- "version": "0.28.1",
- "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
- "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
- "dev": true,
- "hasInstallScript": true,
- "license": "MIT",
- "bin": {
- "esbuild": "bin/esbuild"
- },
- "engines": {
- "node": ">=18"
- },
- "optionalDependencies": {
- "@esbuild/aix-ppc64": "0.28.1",
- "@esbuild/android-arm": "0.28.1",
- "@esbuild/android-arm64": "0.28.1",
- "@esbuild/android-x64": "0.28.1",
- "@esbuild/darwin-arm64": "0.28.1",
- "@esbuild/darwin-x64": "0.28.1",
- "@esbuild/freebsd-arm64": "0.28.1",
- "@esbuild/freebsd-x64": "0.28.1",
- "@esbuild/linux-arm": "0.28.1",
- "@esbuild/linux-arm64": "0.28.1",
- "@esbuild/linux-ia32": "0.28.1",
- "@esbuild/linux-loong64": "0.28.1",
- "@esbuild/linux-mips64el": "0.28.1",
- "@esbuild/linux-ppc64": "0.28.1",
- "@esbuild/linux-riscv64": "0.28.1",
- "@esbuild/linux-s390x": "0.28.1",
- "@esbuild/linux-x64": "0.28.1",
- "@esbuild/netbsd-arm64": "0.28.1",
- "@esbuild/netbsd-x64": "0.28.1",
- "@esbuild/openbsd-arm64": "0.28.1",
- "@esbuild/openbsd-x64": "0.28.1",
- "@esbuild/openharmony-arm64": "0.28.1",
- "@esbuild/sunos-x64": "0.28.1",
- "@esbuild/win32-arm64": "0.28.1",
- "@esbuild/win32-ia32": "0.28.1",
- "@esbuild/win32-x64": "0.28.1"
- }
- },
- "node_modules/escape-html": {
- "version": "1.0.3",
- "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
- "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
- "license": "MIT"
- },
- "node_modules/escape-string-regexp": {
- "version": "4.0.0",
- "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
- "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==",
- "license": "MIT",
- "engines": {
- "node": ">=10"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/etag": {
- "version": "1.8.1",
- "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
- "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/eventsource": {
- "version": "3.0.7",
- "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz",
- "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
- "license": "MIT",
- "dependencies": {
- "eventsource-parser": "^3.0.1"
- },
- "engines": {
- "node": ">=18.0.0"
- }
- },
- "node_modules/eventsource-parser": {
- "version": "3.1.0",
- "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.0.tgz",
- "integrity": "sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg==",
- "license": "MIT",
- "engines": {
- "node": ">=18.0.0"
- }
- },
- "node_modules/expand-template": {
- "version": "2.0.3",
- "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz",
- "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==",
- "license": "(MIT OR WTFPL)",
- "engines": {
- "node": ">=6"
- }
- },
- "node_modules/express": {
- "version": "5.2.1",
- "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
- "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
- "license": "MIT",
- "dependencies": {
- "accepts": "^2.0.0",
- "body-parser": "^2.2.1",
- "content-disposition": "^1.0.0",
- "content-type": "^1.0.5",
- "cookie": "^0.7.1",
- "cookie-signature": "^1.2.1",
- "debug": "^4.4.0",
- "depd": "^2.0.0",
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "etag": "^1.8.1",
- "finalhandler": "^2.1.0",
- "fresh": "^2.0.0",
- "http-errors": "^2.0.0",
- "merge-descriptors": "^2.0.0",
- "mime-types": "^3.0.0",
- "on-finished": "^2.4.1",
- "once": "^1.4.0",
- "parseurl": "^1.3.3",
- "proxy-addr": "^2.0.7",
- "qs": "^6.14.0",
- "range-parser": "^1.2.1",
- "router": "^2.2.0",
- "send": "^1.1.0",
- "serve-static": "^2.2.0",
- "statuses": "^2.0.1",
- "type-is": "^2.0.1",
- "vary": "^1.1.2"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/express-rate-limit": {
- "version": "8.5.2",
- "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.2.tgz",
- "integrity": "sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==",
- "license": "MIT",
- "dependencies": {
- "ip-address": "^10.2.0"
- },
- "engines": {
- "node": ">= 16"
- },
- "funding": {
- "url": "https://github.com/sponsors/express-rate-limit"
- },
- "peerDependencies": {
- "express": ">= 4.11"
- }
- },
- "node_modules/fast-deep-equal": {
- "version": "3.1.3",
- "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
- "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
- "license": "MIT"
- },
- "node_modules/fast-uri": {
- "version": "3.1.3",
- "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz",
- "integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/fastify"
- },
- {
- "type": "opencollective",
- "url": "https://opencollective.com/fastify"
- }
- ],
- "license": "BSD-3-Clause"
- },
- "node_modules/file-uri-to-path": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz",
- "integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==",
- "license": "MIT"
- },
- "node_modules/finalhandler": {
- "version": "2.1.1",
- "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
- "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==",
- "license": "MIT",
- "dependencies": {
- "debug": "^4.4.0",
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "on-finished": "^2.4.1",
- "parseurl": "^1.3.3",
- "statuses": "^2.0.1"
- },
- "engines": {
- "node": ">= 18.0.0"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/flatbuffers": {
- "version": "25.9.23",
- "resolved": "https://registry.npmjs.org/flatbuffers/-/flatbuffers-25.9.23.tgz",
- "integrity": "sha512-MI1qs7Lo4Syw0EOzUl0xjs2lsoeqFku44KpngfIduHBYvzm8h2+7K8YMQh1JtVVVrUvhLpNwqVi4DERegUJhPQ==",
- "license": "Apache-2.0"
- },
- "node_modules/fontkit": {
- "version": "2.0.4",
- "resolved": "https://registry.npmjs.org/fontkit/-/fontkit-2.0.4.tgz",
- "integrity": "sha512-syetQadaUEDNdxdugga9CpEYVaQIxOwk7GlwZWWZ19//qW4zE5bknOKeMBDYAASwnpaSHKJITRLMF9m1fp3s6g==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "@swc/helpers": "^0.5.12",
- "brotli": "^1.3.2",
- "clone": "^2.1.2",
- "dfa": "^1.2.0",
- "fast-deep-equal": "^3.1.3",
- "restructure": "^3.0.0",
- "tiny-inflate": "^1.0.3",
- "unicode-properties": "^1.4.0",
- "unicode-trie": "^2.0.0"
- }
- },
- "node_modules/forwarded": {
- "version": "0.2.0",
- "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
- "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/fresh": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz",
- "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/fs-constants": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
- "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
- "license": "MIT"
- },
- "node_modules/fsevents": {
- "version": "2.3.3",
- "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
- "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
- "dev": true,
- "hasInstallScript": true,
- "license": "MIT",
- "optional": true,
- "os": [
- "darwin"
- ],
- "engines": {
- "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
- }
- },
- "node_modules/function-bind": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
- "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
- "license": "MIT",
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/get-intrinsic": {
- "version": "1.3.0",
- "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
- "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
- "license": "MIT",
- "dependencies": {
- "call-bind-apply-helpers": "^1.0.2",
- "es-define-property": "^1.0.1",
- "es-errors": "^1.3.0",
- "es-object-atoms": "^1.1.1",
- "function-bind": "^1.1.2",
- "get-proto": "^1.0.1",
- "gopd": "^1.2.0",
- "has-symbols": "^1.1.0",
- "hasown": "^2.0.2",
- "math-intrinsics": "^1.1.0"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/get-proto": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
- "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
- "license": "MIT",
- "dependencies": {
- "dunder-proto": "^1.0.1",
- "es-object-atoms": "^1.0.0"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/github-from-package": {
- "version": "0.0.0",
- "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz",
- "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==",
- "license": "MIT"
- },
- "node_modules/global-agent": {
- "version": "3.0.0",
- "resolved": "https://registry.npmjs.org/global-agent/-/global-agent-3.0.0.tgz",
- "integrity": "sha512-PT6XReJ+D07JvGoxQMkT6qji/jVNfX/h364XHZOWeRzy64sSFr+xJ5OX7LI3b4MPQzdL4H8Y8M0xzPpsVMwA8Q==",
- "license": "BSD-3-Clause",
- "dependencies": {
- "boolean": "^3.0.1",
- "es6-error": "^4.1.1",
- "matcher": "^3.0.0",
- "roarr": "^2.15.3",
- "semver": "^7.3.2",
- "serialize-error": "^7.0.1"
- },
- "engines": {
- "node": ">=10.0"
- }
- },
- "node_modules/globalthis": {
- "version": "1.0.4",
- "resolved": "https://registry.npmjs.org/globalthis/-/globalthis-1.0.4.tgz",
- "integrity": "sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ==",
- "license": "MIT",
- "dependencies": {
- "define-properties": "^1.2.1",
- "gopd": "^1.0.1"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/gopd": {
- "version": "1.2.0",
- "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
- "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/guid-typescript": {
- "version": "1.0.9",
- "resolved": "https://registry.npmjs.org/guid-typescript/-/guid-typescript-1.0.9.tgz",
- "integrity": "sha512-Y8T4vYhEfwJOTbouREvG+3XDsjr8E3kIr7uf+JZ0BYloFsttiHU0WfvANVsR7TxNUJa/WpCnw/Ino/p+DeBhBQ==",
- "license": "ISC"
- },
- "node_modules/has-property-descriptors": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.2.tgz",
- "integrity": "sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==",
- "license": "MIT",
- "dependencies": {
- "es-define-property": "^1.0.0"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/has-symbols": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
- "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/hasown": {
- "version": "2.0.4",
- "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
- "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
- "license": "MIT",
- "dependencies": {
- "function-bind": "^1.1.2"
- },
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/hono": {
- "version": "4.12.27",
- "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.27.tgz",
- "integrity": "sha512-1yrb/+w6HWQJrUCLkJ2IF5jNIPvvFkblV5RNOYl6bV+OA6p9GLcMpHFFGTosSvHvcAUibuUukRqhlYI4z32C7Q==",
- "license": "MIT",
- "engines": {
- "node": ">=16.9.0"
- }
- },
- "node_modules/http-errors": {
- "version": "2.0.1",
- "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
- "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
- "license": "MIT",
- "dependencies": {
- "depd": "~2.0.0",
- "inherits": "~2.0.4",
- "setprototypeof": "~1.2.0",
- "statuses": "~2.0.2",
- "toidentifier": "~1.0.1"
- },
- "engines": {
- "node": ">= 0.8"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/iconv-lite": {
- "version": "0.7.2",
- "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
- "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
- "license": "MIT",
- "dependencies": {
- "safer-buffer": ">= 2.1.2 < 3.0.0"
- },
- "engines": {
- "node": ">=0.10.0"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/ieee754": {
- "version": "1.2.1",
- "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
- "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/feross"
- },
- {
- "type": "patreon",
- "url": "https://www.patreon.com/feross"
- },
- {
- "type": "consulting",
- "url": "https://feross.org/support"
- }
- ],
- "license": "BSD-3-Clause"
- },
- "node_modules/inherits": {
- "version": "2.0.4",
- "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
- "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
- "license": "ISC"
- },
- "node_modules/ini": {
- "version": "1.3.8",
- "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
- "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
- "license": "ISC"
- },
- "node_modules/ip-address": {
- "version": "10.2.0",
- "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
- "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
- "license": "MIT",
- "engines": {
- "node": ">= 12"
- }
- },
- "node_modules/ipaddr.js": {
- "version": "1.9.1",
- "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
- "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.10"
- }
- },
- "node_modules/is-promise": {
- "version": "4.0.0",
- "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
- "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
- "license": "MIT"
- },
- "node_modules/isexe": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
- "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
- "license": "ISC"
- },
- "node_modules/jose": {
- "version": "6.2.3",
- "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
- "integrity": "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==",
- "license": "MIT",
- "funding": {
- "url": "https://github.com/sponsors/panva"
- }
- },
- "node_modules/jpeg-exif": {
- "version": "1.1.4",
- "resolved": "https://registry.npmjs.org/jpeg-exif/-/jpeg-exif-1.1.4.tgz",
- "integrity": "sha512-a+bKEcCjtuW5WTdgeXFzswSrdqi0jk4XlEtZlx5A94wCoBpFjfFTbo/Tra5SpNCl/YFZPvcV1dJc+TAYeg6ROQ==",
- "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
- "dev": true,
- "license": "MIT"
- },
- "node_modules/json-schema-traverse": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
- "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
- "license": "MIT"
- },
- "node_modules/json-schema-typed": {
- "version": "8.0.2",
- "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
- "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
- "license": "BSD-2-Clause"
- },
- "node_modules/json-stringify-safe": {
- "version": "5.0.1",
- "resolved": "https://registry.npmjs.org/json-stringify-safe/-/json-stringify-safe-5.0.1.tgz",
- "integrity": "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==",
- "license": "ISC"
- },
- "node_modules/linebreak": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/linebreak/-/linebreak-1.1.0.tgz",
- "integrity": "sha512-MHp03UImeVhB7XZtjd0E4n6+3xr5Dq/9xI/5FptGk5FrbDR3zagPa2DS6U8ks/3HjbKWG9Q1M2ufOzxV2qLYSQ==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "base64-js": "0.0.8",
- "unicode-trie": "^2.0.0"
- }
- },
- "node_modules/linebreak/node_modules/base64-js": {
- "version": "0.0.8",
- "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-0.0.8.tgz",
- "integrity": "sha512-3XSA2cR/h/73EzlXXdU6YNycmYI7+kicTxks4eJg2g39biHR84slg2+des+p7iHYhbRg/udIS4TD53WabcOUkw==",
- "dev": true,
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/long": {
- "version": "5.3.2",
- "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
- "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
- "license": "Apache-2.0"
- },
- "node_modules/matcher": {
- "version": "3.0.0",
- "resolved": "https://registry.npmjs.org/matcher/-/matcher-3.0.0.tgz",
- "integrity": "sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==",
- "license": "MIT",
- "dependencies": {
- "escape-string-regexp": "^4.0.0"
- },
- "engines": {
- "node": ">=10"
- }
- },
- "node_modules/math-intrinsics": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
- "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/media-typer": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
- "integrity": "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/merge-descriptors": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz",
- "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==",
- "license": "MIT",
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/mime-db": {
- "version": "1.54.0",
- "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
- "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/mime-types": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
- "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
- "license": "MIT",
- "dependencies": {
- "mime-db": "^1.54.0"
- },
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/mimic-response": {
- "version": "3.1.0",
- "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz",
- "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==",
- "license": "MIT",
- "engines": {
- "node": ">=10"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/minimist": {
- "version": "1.2.8",
- "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
- "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
- "license": "MIT",
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/minipass": {
- "version": "7.1.3",
- "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
- "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
- "license": "BlueOak-1.0.0",
- "engines": {
- "node": ">=16 || 14 >=14.17"
- }
- },
- "node_modules/minizlib": {
- "version": "3.1.0",
- "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
- "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
- "license": "MIT",
- "dependencies": {
- "minipass": "^7.1.2"
- },
- "engines": {
- "node": ">= 18"
- }
- },
- "node_modules/mkdirp-classic": {
- "version": "0.5.3",
- "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz",
- "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==",
- "license": "MIT"
- },
- "node_modules/ms": {
- "version": "2.1.3",
- "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
- "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
- "license": "MIT"
- },
- "node_modules/napi-build-utils": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz",
- "integrity": "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==",
- "license": "MIT"
- },
- "node_modules/negotiator": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz",
- "integrity": "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- }
- },
- "node_modules/node-abi": {
- "version": "3.93.0",
- "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.93.0.tgz",
- "integrity": "sha512-Cu6yUpX5Iavugm8BeX7c0wgU9CvOqfd1yM6A1d2q2ZMjym7GjpASv2GdRcTq3Fx+Sb5OgBkEEpw4VnAbY6Y5RA==",
- "license": "MIT",
- "dependencies": {
- "semver": "^7.3.5"
- },
- "engines": {
- "node": ">=10"
- }
- },
- "node_modules/object-assign": {
- "version": "4.1.1",
- "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
- "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
- "license": "MIT",
- "engines": {
- "node": ">=0.10.0"
- }
- },
- "node_modules/object-inspect": {
- "version": "1.13.4",
- "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
- "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/object-keys": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz",
- "integrity": "sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.4"
- }
- },
- "node_modules/on-finished": {
- "version": "2.4.1",
- "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
- "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
- "license": "MIT",
- "dependencies": {
- "ee-first": "1.1.1"
- },
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/once": {
- "version": "1.4.0",
- "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
- "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
- "license": "ISC",
- "dependencies": {
- "wrappy": "1"
- }
- },
- "node_modules/onnxruntime-common": {
- "version": "1.21.0",
- "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.21.0.tgz",
- "integrity": "sha512-Q632iLLrtCAVOTO65dh2+mNbQir/QNTVBG3h/QdZBpns7mZ0RYbLRBgGABPbpU9351AgYy7SJf1WaeVwMrBFPQ==",
- "license": "MIT"
- },
- "node_modules/onnxruntime-node": {
- "version": "1.21.0",
- "resolved": "https://registry.npmjs.org/onnxruntime-node/-/onnxruntime-node-1.21.0.tgz",
- "integrity": "sha512-NeaCX6WW2L8cRCSqy3bInlo5ojjQqu2fD3D+9W5qb5irwxhEyWKXeH2vZ8W9r6VxaMPUan+4/7NDwZMtouZxEw==",
- "hasInstallScript": true,
- "license": "MIT",
- "os": [
- "win32",
- "darwin",
- "linux"
- ],
- "dependencies": {
- "global-agent": "^3.0.0",
- "onnxruntime-common": "1.21.0",
- "tar": "^7.0.1"
- }
- },
- "node_modules/onnxruntime-web": {
- "version": "1.22.0-dev.20250409-89f8206ba4",
- "resolved": "https://registry.npmjs.org/onnxruntime-web/-/onnxruntime-web-1.22.0-dev.20250409-89f8206ba4.tgz",
- "integrity": "sha512-0uS76OPgH0hWCPrFKlL8kYVV7ckM7t/36HfbgoFw6Nd0CZVVbQC4PkrR8mBX8LtNUFZO25IQBqV2Hx2ho3FlbQ==",
- "license": "MIT",
- "dependencies": {
- "flatbuffers": "^25.1.24",
- "guid-typescript": "^1.0.9",
- "long": "^5.2.3",
- "onnxruntime-common": "1.22.0-dev.20250409-89f8206ba4",
- "platform": "^1.3.6",
- "protobufjs": "^7.2.4"
- }
- },
- "node_modules/onnxruntime-web/node_modules/onnxruntime-common": {
- "version": "1.22.0-dev.20250409-89f8206ba4",
- "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.22.0-dev.20250409-89f8206ba4.tgz",
- "integrity": "sha512-vDJMkfCfb0b1A836rgHj+ORuZf4B4+cc2bASQtpeoJLueuFc5DuYwjIZUBrSvx/fO5IrLjLz+oTrB3pcGlhovQ==",
- "license": "MIT"
- },
- "node_modules/openai": {
- "version": "6.45.0",
- "resolved": "https://registry.npmjs.org/openai/-/openai-6.45.0.tgz",
- "integrity": "sha512-5DQVNErssk0afNpTTHUm/qZPU4iKR9OYdNid8Ib4puq4gHNNvGWZht2zY4h9a8JMF949Ik6m8gQutllVPbjdnw==",
- "license": "Apache-2.0",
- "peerDependencies": {
- "@aws-sdk/credential-provider-node": ">=3.972.0 <4",
- "@smithy/hash-node": ">=4.3.0 <5",
- "@smithy/signature-v4": ">=5.4.0 <6",
- "ws": "^8.18.0",
- "zod": "^3.25 || ^4.0"
- },
- "peerDependenciesMeta": {
- "@aws-sdk/credential-provider-node": {
- "optional": true
- },
- "@smithy/hash-node": {
- "optional": true
- },
- "@smithy/signature-v4": {
- "optional": true
- },
- "ws": {
- "optional": true
- },
- "zod": {
- "optional": true
- }
- }
- },
- "node_modules/pako": {
- "version": "1.0.11",
- "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
- "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
- "dev": true,
- "license": "(MIT AND Zlib)"
- },
- "node_modules/parseurl": {
- "version": "1.3.3",
- "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
- "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/path-key": {
- "version": "3.1.1",
- "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
- "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
- "license": "MIT",
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/path-to-regexp": {
- "version": "8.4.2",
- "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
- "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==",
- "license": "MIT",
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/pdfkit": {
- "version": "0.17.2",
- "resolved": "https://registry.npmjs.org/pdfkit/-/pdfkit-0.17.2.tgz",
- "integrity": "sha512-UnwF5fXy08f0dnp4jchFYAROKMNTaPqb/xgR8GtCzIcqoTnbOqtp3bwKvO4688oHI6vzEEs8Q6vqqEnC5IUELw==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "crypto-js": "^4.2.0",
- "fontkit": "^2.0.4",
- "jpeg-exif": "^1.1.4",
- "linebreak": "^1.1.0",
- "png-js": "^1.0.0"
- }
- },
- "node_modules/pkce-challenge": {
- "version": "5.0.1",
- "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
- "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==",
- "license": "MIT",
- "engines": {
- "node": ">=16.20.0"
- }
- },
- "node_modules/platform": {
- "version": "1.3.6",
- "resolved": "https://registry.npmjs.org/platform/-/platform-1.3.6.tgz",
- "integrity": "sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==",
- "license": "MIT"
- },
- "node_modules/png-js": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/png-js/-/png-js-1.1.0.tgz",
- "integrity": "sha512-PM/uYGzGdNSzqeOgly68+6wKQDL1SY0a/N+OEa/+br6LnHWOAJB0Npiamnodfq3jd2LS/i2fMeOKSAILjA+m5Q==",
- "dev": true,
- "dependencies": {
- "browserify-zlib": "^0.2.0"
- }
- },
- "node_modules/prebuild-install": {
- "version": "7.1.3",
- "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
- "integrity": "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==",
- "deprecated": "No longer maintained. Please contact the author of the relevant native addon; alternatives are available.",
- "license": "MIT",
- "dependencies": {
- "detect-libc": "^2.0.0",
- "expand-template": "^2.0.3",
- "github-from-package": "0.0.0",
- "minimist": "^1.2.3",
- "mkdirp-classic": "^0.5.3",
- "napi-build-utils": "^2.0.0",
- "node-abi": "^3.3.0",
- "pump": "^3.0.0",
- "rc": "^1.2.7",
- "simple-get": "^4.0.0",
- "tar-fs": "^2.0.0",
- "tunnel-agent": "^0.6.0"
- },
- "bin": {
- "prebuild-install": "bin.js"
- },
- "engines": {
- "node": ">=10"
- }
- },
- "node_modules/protobufjs": {
- "version": "7.6.4",
- "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.4.tgz",
- "integrity": "sha512-RJJPTTpvFfHcWLkIa2JFWK4XvtSzS0yEWDmunqHXli1h3JlkbcQZXDZdcWxv+JK3Xsl5/UFDPZ0iGm7DAengYw==",
- "hasInstallScript": true,
- "license": "BSD-3-Clause",
- "dependencies": {
- "@protobufjs/aspromise": "^1.1.2",
- "@protobufjs/base64": "^1.1.2",
- "@protobufjs/codegen": "^2.0.5",
- "@protobufjs/eventemitter": "^1.1.1",
- "@protobufjs/fetch": "^1.1.1",
- "@protobufjs/float": "^1.0.2",
- "@protobufjs/path": "^1.1.2",
- "@protobufjs/pool": "^1.1.0",
- "@protobufjs/utf8": "^1.1.1",
- "@types/node": ">=13.7.0",
- "long": "^5.3.2"
- },
- "engines": {
- "node": ">=12.0.0"
- }
- },
- "node_modules/proxy-addr": {
- "version": "2.0.7",
- "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
- "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==",
- "license": "MIT",
- "dependencies": {
- "forwarded": "0.2.0",
- "ipaddr.js": "1.9.1"
- },
- "engines": {
- "node": ">= 0.10"
- }
- },
- "node_modules/pump": {
- "version": "3.0.4",
- "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
- "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
- "license": "MIT",
- "dependencies": {
- "end-of-stream": "^1.1.0",
- "once": "^1.3.1"
- }
- },
- "node_modules/qs": {
- "version": "6.15.3",
- "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz",
- "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==",
- "license": "BSD-3-Clause",
- "dependencies": {
- "es-define-property": "^1.0.1",
- "side-channel": "^1.1.1"
- },
- "engines": {
- "node": ">=0.6"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/range-parser": {
- "version": "1.3.0",
- "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.3.0.tgz",
- "integrity": "sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.6"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/raw-body": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
- "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
- "license": "MIT",
- "dependencies": {
- "bytes": "~3.1.2",
- "http-errors": "~2.0.1",
- "iconv-lite": "~0.7.0",
- "unpipe": "~1.0.0"
- },
- "engines": {
- "node": ">= 0.10"
- }
- },
- "node_modules/rc": {
- "version": "1.2.8",
- "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",
- "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==",
- "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
- "dependencies": {
- "deep-extend": "^0.6.0",
- "ini": "~1.3.0",
- "minimist": "^1.2.0",
- "strip-json-comments": "~2.0.1"
- },
- "bin": {
- "rc": "cli.js"
- }
- },
- "node_modules/readable-stream": {
- "version": "3.6.2",
- "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
- "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
- "license": "MIT",
- "dependencies": {
- "inherits": "^2.0.3",
- "string_decoder": "^1.1.1",
- "util-deprecate": "^1.0.1"
- },
- "engines": {
- "node": ">= 6"
- }
- },
- "node_modules/readdirp": {
- "version": "4.1.2",
- "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
- "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
- "license": "MIT",
- "engines": {
- "node": ">= 14.18.0"
- },
- "funding": {
- "type": "individual",
- "url": "https://paulmillr.com/funding/"
- }
- },
- "node_modules/require-from-string": {
- "version": "2.0.2",
- "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
- "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
- "license": "MIT",
- "engines": {
- "node": ">=0.10.0"
- }
- },
- "node_modules/restructure": {
- "version": "3.0.2",
- "resolved": "https://registry.npmjs.org/restructure/-/restructure-3.0.2.tgz",
- "integrity": "sha512-gSfoiOEA0VPE6Tukkrr7I0RBdE0s7H1eFCDBk05l1KIQT1UIKNc5JZy6jdyW6eYH3aR3g5b3PuL77rq0hvwtAw==",
- "dev": true,
- "license": "MIT"
- },
- "node_modules/roarr": {
- "version": "2.15.4",
- "resolved": "https://registry.npmjs.org/roarr/-/roarr-2.15.4.tgz",
- "integrity": "sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A==",
- "license": "BSD-3-Clause",
- "dependencies": {
- "boolean": "^3.0.1",
- "detect-node": "^2.0.4",
- "globalthis": "^1.0.1",
- "json-stringify-safe": "^5.0.1",
- "semver-compare": "^1.0.0",
- "sprintf-js": "^1.1.2"
- },
- "engines": {
- "node": ">=8.0"
- }
- },
- "node_modules/router": {
- "version": "2.2.0",
- "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
- "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==",
- "license": "MIT",
- "dependencies": {
- "debug": "^4.4.0",
- "depd": "^2.0.0",
- "is-promise": "^4.0.0",
- "parseurl": "^1.3.3",
- "path-to-regexp": "^8.0.0"
- },
- "engines": {
- "node": ">= 18"
- }
- },
- "node_modules/safe-buffer": {
- "version": "5.2.1",
- "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
- "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/feross"
- },
- {
- "type": "patreon",
- "url": "https://www.patreon.com/feross"
- },
- {
- "type": "consulting",
- "url": "https://feross.org/support"
- }
- ],
- "license": "MIT"
- },
- "node_modules/safer-buffer": {
- "version": "2.1.2",
- "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
- "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
- "license": "MIT"
- },
- "node_modules/semver": {
- "version": "7.8.5",
- "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
- "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
- "license": "ISC",
- "bin": {
- "semver": "bin/semver.js"
- },
- "engines": {
- "node": ">=10"
- }
- },
- "node_modules/semver-compare": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/semver-compare/-/semver-compare-1.0.0.tgz",
- "integrity": "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==",
- "license": "MIT"
- },
- "node_modules/send": {
- "version": "1.2.1",
- "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
- "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==",
- "license": "MIT",
- "dependencies": {
- "debug": "^4.4.3",
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "etag": "^1.8.1",
- "fresh": "^2.0.0",
- "http-errors": "^2.0.1",
- "mime-types": "^3.0.2",
- "ms": "^2.1.3",
- "on-finished": "^2.4.1",
- "range-parser": "^1.2.1",
- "statuses": "^2.0.2"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/serialize-error": {
- "version": "7.0.1",
- "resolved": "https://registry.npmjs.org/serialize-error/-/serialize-error-7.0.1.tgz",
- "integrity": "sha512-8I8TjW5KMOKsZQTvoxjuSIa7foAwPWGOts+6o7sgjz41/qMD9VQHEDxi6PBvK2l0MXUmqZyNpUK+T2tQaaElvw==",
- "license": "MIT",
- "dependencies": {
- "type-fest": "^0.13.1"
- },
- "engines": {
- "node": ">=10"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/serve-static": {
- "version": "2.2.1",
- "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz",
- "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==",
- "license": "MIT",
- "dependencies": {
- "encodeurl": "^2.0.0",
- "escape-html": "^1.0.3",
- "parseurl": "^1.3.3",
- "send": "^1.2.0"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/setprototypeof": {
- "version": "1.2.0",
- "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
- "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
- "license": "ISC"
- },
- "node_modules/sharp": {
- "version": "0.34.5",
- "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
- "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
- "hasInstallScript": true,
- "license": "Apache-2.0",
- "dependencies": {
- "@img/colour": "^1.0.0",
- "detect-libc": "^2.1.2",
- "semver": "^7.7.3"
- },
- "engines": {
- "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
- },
- "funding": {
- "url": "https://opencollective.com/libvips"
- },
- "optionalDependencies": {
- "@img/sharp-darwin-arm64": "0.34.5",
- "@img/sharp-darwin-x64": "0.34.5",
- "@img/sharp-libvips-darwin-arm64": "1.2.4",
- "@img/sharp-libvips-darwin-x64": "1.2.4",
- "@img/sharp-libvips-linux-arm": "1.2.4",
- "@img/sharp-libvips-linux-arm64": "1.2.4",
- "@img/sharp-libvips-linux-ppc64": "1.2.4",
- "@img/sharp-libvips-linux-riscv64": "1.2.4",
- "@img/sharp-libvips-linux-s390x": "1.2.4",
- "@img/sharp-libvips-linux-x64": "1.2.4",
- "@img/sharp-libvips-linuxmusl-arm64": "1.2.4",
- "@img/sharp-libvips-linuxmusl-x64": "1.2.4",
- "@img/sharp-linux-arm": "0.34.5",
- "@img/sharp-linux-arm64": "0.34.5",
- "@img/sharp-linux-ppc64": "0.34.5",
- "@img/sharp-linux-riscv64": "0.34.5",
- "@img/sharp-linux-s390x": "0.34.5",
- "@img/sharp-linux-x64": "0.34.5",
- "@img/sharp-linuxmusl-arm64": "0.34.5",
- "@img/sharp-linuxmusl-x64": "0.34.5",
- "@img/sharp-wasm32": "0.34.5",
- "@img/sharp-win32-arm64": "0.34.5",
- "@img/sharp-win32-ia32": "0.34.5",
- "@img/sharp-win32-x64": "0.34.5"
- }
- },
- "node_modules/shebang-command": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
- "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
- "license": "MIT",
- "dependencies": {
- "shebang-regex": "^3.0.0"
- },
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/shebang-regex": {
- "version": "3.0.0",
- "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
- "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
- "license": "MIT",
- "engines": {
- "node": ">=8"
- }
- },
- "node_modules/side-channel": {
- "version": "1.1.1",
- "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz",
- "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0",
- "object-inspect": "^1.13.4",
- "side-channel-list": "^1.0.1",
- "side-channel-map": "^1.0.1",
- "side-channel-weakmap": "^1.0.2"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/side-channel-list": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
- "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
- "license": "MIT",
- "dependencies": {
- "es-errors": "^1.3.0",
- "object-inspect": "^1.13.4"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/side-channel-map": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
- "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
- "license": "MIT",
- "dependencies": {
- "call-bound": "^1.0.2",
- "es-errors": "^1.3.0",
- "get-intrinsic": "^1.2.5",
- "object-inspect": "^1.13.3"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/side-channel-weakmap": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
- "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
- "license": "MIT",
- "dependencies": {
- "call-bound": "^1.0.2",
- "es-errors": "^1.3.0",
- "get-intrinsic": "^1.2.5",
- "object-inspect": "^1.13.3",
- "side-channel-map": "^1.0.1"
- },
- "engines": {
- "node": ">= 0.4"
- },
- "funding": {
- "url": "https://github.com/sponsors/ljharb"
- }
- },
- "node_modules/simple-concat": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz",
- "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/feross"
- },
- {
- "type": "patreon",
- "url": "https://www.patreon.com/feross"
- },
- {
- "type": "consulting",
- "url": "https://feross.org/support"
- }
- ],
- "license": "MIT"
- },
- "node_modules/simple-get": {
- "version": "4.0.1",
- "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz",
- "integrity": "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==",
- "funding": [
- {
- "type": "github",
- "url": "https://github.com/sponsors/feross"
- },
- {
- "type": "patreon",
- "url": "https://www.patreon.com/feross"
- },
- {
- "type": "consulting",
- "url": "https://feross.org/support"
- }
- ],
- "license": "MIT",
- "dependencies": {
- "decompress-response": "^6.0.0",
- "once": "^1.3.1",
- "simple-concat": "^1.0.0"
- }
- },
- "node_modules/sprintf-js": {
- "version": "1.1.3",
- "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.1.3.tgz",
- "integrity": "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==",
- "license": "BSD-3-Clause"
- },
- "node_modules/statuses": {
- "version": "2.0.2",
- "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
- "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/string_decoder": {
- "version": "1.3.0",
- "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
- "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
- "license": "MIT",
- "dependencies": {
- "safe-buffer": "~5.2.0"
- }
- },
- "node_modules/strip-json-comments": {
- "version": "2.0.1",
- "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
- "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==",
- "license": "MIT",
- "engines": {
- "node": ">=0.10.0"
- }
- },
- "node_modules/tar": {
- "version": "7.5.19",
- "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.19.tgz",
- "integrity": "sha512-4LeEWl96twnS2Q7Bz4MGqgazLqO+hJN63GZxXoIqh1T3VweYD997gbU1ItNsQafqqXTXd5WFyFdReLtwvRBNiw==",
- "license": "BlueOak-1.0.0",
- "dependencies": {
- "@isaacs/fs-minipass": "^4.0.0",
- "chownr": "^3.0.0",
- "minipass": "^7.1.2",
- "minizlib": "^3.1.0",
- "yallist": "^5.0.0"
- },
- "engines": {
- "node": ">=18"
- }
- },
- "node_modules/tar-fs": {
- "version": "2.1.5",
- "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.5.tgz",
- "integrity": "sha512-OboTd8mmMhZDNPV+UjQcK9yKAatXu2aJ+r1w4im1Otd4M4fl2hwvdoXUxIYHFTHWK/3y3FarBP70v3vwmGlOxw==",
- "license": "MIT",
- "dependencies": {
- "chownr": "^1.1.1",
- "mkdirp-classic": "^0.5.2",
- "pump": "^3.0.0",
- "tar-stream": "^2.1.4"
- }
- },
- "node_modules/tar-stream": {
- "version": "2.2.0",
- "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
- "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
- "license": "MIT",
- "dependencies": {
- "bl": "^4.0.3",
- "end-of-stream": "^1.4.1",
- "fs-constants": "^1.0.0",
- "inherits": "^2.0.3",
- "readable-stream": "^3.1.1"
- },
- "engines": {
- "node": ">=6"
- }
- },
- "node_modules/tar/node_modules/chownr": {
- "version": "3.0.0",
- "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
- "integrity": "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==",
- "license": "BlueOak-1.0.0",
- "engines": {
- "node": ">=18"
- }
- },
- "node_modules/tiny-inflate": {
- "version": "1.0.3",
- "resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz",
- "integrity": "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==",
- "dev": true,
- "license": "MIT"
- },
- "node_modules/toidentifier": {
- "version": "1.0.1",
- "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
- "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
- "license": "MIT",
- "engines": {
- "node": ">=0.6"
- }
- },
- "node_modules/tslib": {
- "version": "2.8.1",
- "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
- "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
- "devOptional": true,
- "license": "0BSD"
- },
"node_modules/tsx": {
"version": "4.22.4",
"resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.4.tgz",
@@ -3213,61 +713,6 @@
"fsevents": "~2.3.3"
}
},
- "node_modules/tunnel-agent": {
- "version": "0.6.0",
- "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",
- "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==",
- "license": "Apache-2.0",
- "dependencies": {
- "safe-buffer": "^5.0.1"
- },
- "engines": {
- "node": "*"
- }
- },
- "node_modules/type-fest": {
- "version": "0.13.1",
- "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.13.1.tgz",
- "integrity": "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==",
- "license": "(MIT OR CC0-1.0)",
- "engines": {
- "node": ">=10"
- },
- "funding": {
- "url": "https://github.com/sponsors/sindresorhus"
- }
- },
- "node_modules/type-is": {
- "version": "2.1.0",
- "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.1.0.tgz",
- "integrity": "sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==",
- "license": "MIT",
- "dependencies": {
- "content-type": "^2.0.0",
- "media-typer": "^1.1.0",
- "mime-types": "^3.0.0"
- },
- "engines": {
- "node": ">= 18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
- "node_modules/type-is/node_modules/content-type": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.0.0.tgz",
- "integrity": "sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ==",
- "license": "MIT",
- "engines": {
- "node": ">=18"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/express"
- }
- },
"node_modules/typescript": {
"version": "6.0.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
@@ -3286,96 +731,9 @@
"version": "8.3.0",
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
"integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
- "license": "MIT"
- },
- "node_modules/unicode-properties": {
- "version": "1.4.1",
- "resolved": "https://registry.npmjs.org/unicode-properties/-/unicode-properties-1.4.1.tgz",
- "integrity": "sha512-CLjCCLQ6UuMxWnbIylkisbRj31qxHPAurvena/0iwSVbQ2G1VY5/HjV0IRabOEbDHlzZlRdCrD4NhB0JtU40Pg==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "base64-js": "^1.3.0",
- "unicode-trie": "^2.0.0"
- }
- },
- "node_modules/unicode-trie": {
- "version": "2.0.0",
- "resolved": "https://registry.npmjs.org/unicode-trie/-/unicode-trie-2.0.0.tgz",
- "integrity": "sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "pako": "^0.2.5",
- "tiny-inflate": "^1.0.0"
- }
- },
- "node_modules/unicode-trie/node_modules/pako": {
- "version": "0.2.9",
- "resolved": "https://registry.npmjs.org/pako/-/pako-0.2.9.tgz",
- "integrity": "sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==",
"dev": true,
"license": "MIT"
},
- "node_modules/unpdf": {
- "version": "1.6.2",
- "resolved": "https://registry.npmjs.org/unpdf/-/unpdf-1.6.2.tgz",
- "integrity": "sha512-zQ80ySoPuPHOsvIoRp/nJyQt8TOUoTh1+WBCGcBvlddQNgKDLRwm0AY3x8Q35I7+kIiRSgqMx+Ma2pl9McIp7A==",
- "license": "MIT",
- "peerDependencies": {
- "@napi-rs/canvas": "^0.1.69"
- },
- "peerDependenciesMeta": {
- "@napi-rs/canvas": {
- "optional": true
- }
- }
- },
- "node_modules/unpipe": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
- "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/util-deprecate": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
- "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
- "license": "MIT"
- },
- "node_modules/vary": {
- "version": "1.1.2",
- "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
- "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
- "license": "MIT",
- "engines": {
- "node": ">= 0.8"
- }
- },
- "node_modules/which": {
- "version": "2.0.2",
- "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
- "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
- "license": "ISC",
- "dependencies": {
- "isexe": "^2.0.0"
- },
- "bin": {
- "node-which": "bin/node-which"
- },
- "engines": {
- "node": ">= 8"
- }
- },
- "node_modules/wrappy": {
- "version": "1.0.2",
- "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
- "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
- "license": "ISC"
- },
"node_modules/ws": {
"version": "8.21.0",
"resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
@@ -3399,32 +757,16 @@
}
}
},
- "node_modules/yallist": {
- "version": "5.0.0",
- "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz",
- "integrity": "sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==",
- "license": "BlueOak-1.0.0",
- "engines": {
- "node": ">=18"
- }
- },
"node_modules/zod": {
"version": "4.4.3",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
"integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
"license": "MIT",
+ "optional": true,
+ "peer": true,
"funding": {
"url": "https://github.com/sponsors/colinhacks"
}
- },
- "node_modules/zod-to-json-schema": {
- "version": "3.25.2",
- "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz",
- "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==",
- "license": "ISC",
- "peerDependencies": {
- "zod": "^3.25.28 || ^4"
- }
}
}
}
diff --git a/package.json b/package.json
index 1ab91c42..79c04c5e 100644
--- a/package.json
+++ b/package.json
@@ -1,15 +1,13 @@
{
"name": "context-graph-engine",
"version": "0.1.0",
- "description": "An open-source engine that turns docs into a structured context graph that AI agents read from and contribute learnings back to.",
+ "description": "Build a repo's context graph as a folder of linked markdown files that live in the repo and stay in sync with the code through git.",
"keywords": [
"ai",
"agents",
"knowledge-graph",
"context",
- "memory",
- "rag",
- "mcp",
+ "codebase",
"llm"
],
"license": "MIT",
@@ -23,10 +21,7 @@
}
},
"bin": {
- "context-graph": "./dist/cli.js",
- "context-graph-mcp": "./dist/mcp.js",
- "context-graph-web": "./dist/web.js",
- "context-graph-serve": "./dist/serve.js"
+ "context-graph": "./dist/cli.js"
},
"files": [
"dist",
@@ -34,13 +29,9 @@
"LICENSE"
],
"scripts": {
- "build": "tsc -p tsconfig.json && node -e \"fs.mkdirSync('dist/web',{recursive:true});fs.copyFileSync('src/web/ui.html','dist/web/ui.html')\"",
+ "build": "tsc -p tsconfig.json",
"dev": "tsc -p tsconfig.json --watch",
"cli": "tsx src/cli.ts",
- "mcp": "tsx src/mcp.ts",
- "web": "tsx src/web.ts",
- "serve": "tsx src/serve.ts",
- "example": "tsx examples/quickstart.ts",
"bench": "tsx bench/run.ts",
"test": "node --import tsx --test test/*.test.ts",
"prepare": "npm run build",
@@ -50,20 +41,13 @@
"node": ">=20"
},
"dependencies": {
- "@huggingface/transformers": "^3.8.1",
- "@modelcontextprotocol/sdk": "^1.29.0",
- "better-sqlite3": "^12.11.1",
- "chokidar": "^4.0.3",
"commander": "^15.0.0",
"dotenv": "^17.4.2",
- "openai": "^6.45.0",
- "unpdf": "^1.6.2",
- "zod": "^4.4.3"
+ "gray-matter": "^4.0.3",
+ "openai": "^6.45.0"
},
"devDependencies": {
- "@types/better-sqlite3": "^7.6.13",
"@types/node": "^26.1.0",
- "pdfkit": "^0.17.2",
"tsx": "^4.22.4",
"typescript": "^6.0.3"
}
diff --git a/sample-docs/meridian-architecture.pdf b/sample-docs/meridian-architecture.pdf
deleted file mode 100644
index 38658c77..00000000
Binary files a/sample-docs/meridian-architecture.pdf and /dev/null differ
diff --git a/sample-docs/meridian-onboarding.pdf b/sample-docs/meridian-onboarding.pdf
deleted file mode 100644
index 65d38d95..00000000
Binary files a/sample-docs/meridian-onboarding.pdf and /dev/null differ
diff --git a/sample-docs/meridian-operations-runbook.pdf b/sample-docs/meridian-operations-runbook.pdf
deleted file mode 100644
index 8c64f440..00000000
Binary files a/sample-docs/meridian-operations-runbook.pdf and /dev/null differ
diff --git a/scripts/make-demo-pdfs.mjs b/scripts/make-demo-pdfs.mjs
deleted file mode 100644
index 66076606..00000000
--- a/scripts/make-demo-pdfs.mjs
+++ /dev/null
@@ -1,130 +0,0 @@
-/**
- * Generate the demo PDFs used in the MCP walkthrough (see DEMO.md).
- *
- * node scripts/make-demo-pdfs.mjs
- *
- * Writes 2–3 PDFs full of specific, queryable facts into examples/demo-docs/.
- * The content is fictional ("Northwind") so nothing here is sensitive; the point
- * is to have concrete details a query can retrieve back through the graph.
- */
-import PDFDocument from "pdfkit";
-import { createWriteStream, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const OUT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "examples", "demo-docs");
-mkdirSync(OUT_DIR, { recursive: true });
-
-/** Render a simple titled document with headings + paragraphs to a PDF file. */
-function writePdf(filename, title, blocks) {
- return new Promise((resolve, reject) => {
- const doc = new PDFDocument({ margin: 56, size: "A4" });
- const path = join(OUT_DIR, filename);
- const stream = createWriteStream(path);
- doc.pipe(stream);
-
- doc.font("Helvetica-Bold").fontSize(20).text(title);
- doc.moveDown(0.8);
-
- for (const block of blocks) {
- if (block.heading) {
- doc.moveDown(0.4);
- doc.font("Helvetica-Bold").fontSize(13).text(block.heading);
- doc.moveDown(0.2);
- }
- doc.font("Helvetica").fontSize(11).text(block.body, { align: "left", lineGap: 2 });
- }
-
- doc.end();
- stream.on("finish", () => resolve(path));
- stream.on("error", reject);
- });
-}
-
-const docs = [
- {
- filename: "northwind-architecture.pdf",
- title: "Northwind Platform — Architecture Overview",
- blocks: [
- {
- heading: "Services",
- body:
- "The Northwind platform is composed of five core services. The Orders Service accepts customer orders and is the system of record for order state. It calls the Inventory Service to reserve stock and the Payments Service to charge the customer. The Payments Service integrates with Stripe as the payment processor. The Notifications Service sends transactional email through SendGrid and SMS through Twilio.",
- },
- {
- heading: "Data stores",
- body:
- "The Orders Service stores order data in a PostgreSQL database named orders_db. The Inventory Service uses a separate PostgreSQL database named inventory_db. Both services publish domain events to an Apache Kafka cluster on the topic 'northwind.events'. The Notifications Service consumes those events to decide when to message customers.",
- },
- {
- heading: "Authentication",
- body:
- "All services authenticate requests using JWT access tokens issued by the Auth Service. Access tokens expire after 15 minutes; refresh tokens expire after 30 days. The Auth Service is backed by Redis for token revocation lists.",
- },
- {
- heading: "Deployment",
- body:
- "Northwind runs on Kubernetes in the AWS us-east-1 region. Each service is deployed as a separate Deployment with a minimum of 3 replicas. Container images are built by GitHub Actions and pushed to Amazon ECR. Production deploys require approval from a member of the Platform team.",
- },
- ],
- },
- {
- filename: "northwind-billing-runbook.pdf",
- title: "Northwind Billing — On-Call Runbook",
- blocks: [
- {
- heading: "Failed charges",
- body:
- "When a charge fails, the Payments Service emits a payment_failed event. The Dunning Worker retries the charge up to 3 times with exponential backoff (1 hour, 6 hours, 24 hours). After the third failed retry, the subscription is marked past_due and the Notifications Service emails the customer. If the account remains past_due for 7 days, it is automatically suspended.",
- },
- {
- heading: "Refunds",
- body:
- "Refunds are issued through the Payments Service admin API. Refunds above $500 require approval from a Finance team lead. All refunds are logged to the audit_log table in payments_db and reflected in Stripe within 24 hours.",
- },
- {
- heading: "Escalation",
- body:
- "The billing on-call rotation is owned by the Payments team. The primary on-call responds within 15 minutes during business hours and within 30 minutes off-hours. Page the on-call via PagerDuty service 'northwind-billing'. For Stripe outages, escalate to the Payments team lead, Dana Whitfield, and post an update in the #billing-incidents Slack channel.",
- },
- {
- heading: "Key metrics",
- body:
- "The billing dashboard tracks charge success rate (target: above 97%), average time to first retry, and past_due account count. An alert fires if the charge success rate drops below 95% over any 30-minute window.",
- },
- ],
- },
- {
- filename: "northwind-onboarding.pdf",
- title: "Northwind Engineering — New Hire Onboarding",
- blocks: [
- {
- heading: "Getting access",
- body:
- "New engineers request access through the IT portal. Standard access includes GitHub (the northwind-inc org), the AWS developer account, PagerDuty, and Slack. Production database access requires a separate request approved by your team lead and is granted for 90 days at a time.",
- },
- {
- heading: "Local setup",
- body:
- "Clone the northwind-inc/platform monorepo. Install Node.js 20 and Docker. Run 'make bootstrap' to start local Postgres, Redis, and Kafka via docker-compose. Copy .env.sample to .env and fill in your personal API keys. Run 'make test' to verify the setup.",
- },
- {
- heading: "Team structure",
- body:
- "Engineering has four teams. The Platform team owns infrastructure and CI/CD. The Payments team owns the Payments Service and billing. The Orders team owns the Orders and Inventory services. The Growth team owns the Notifications Service and customer-facing features. The VP of Engineering is Priya Nair.",
- },
- {
- heading: "First week",
- body:
- "In your first week you should complete the security training, ship one small change to production, and pair with a teammate on an on-call shadow. Your onboarding buddy is assigned on day one. Ask questions in the #eng-help Slack channel.",
- },
- ],
- },
-];
-
-const written = [];
-for (const d of docs) {
- written.push(await writePdf(d.filename, d.title, d.blocks));
-}
-console.log("Wrote demo PDFs:");
-for (const p of written) console.log(" " + p);
diff --git a/src/ai/local.ts b/src/ai/local.ts
deleted file mode 100644
index ba5de569..00000000
--- a/src/ai/local.ts
+++ /dev/null
@@ -1,184 +0,0 @@
-/**
- * Local, key-free providers so the engine runs entirely on the user's machine.
- *
- * - {@link LocalEmbedder} embeds text in-process with a small ONNX model via
- * transformers.js — no server, no API key, models cached to disk on first use.
- * - {@link OllamaExtractor} extracts entities/relationships from a locally
- * running Ollama (https://ollama.com) using its structured-output support.
- *
- * These are what the engine falls back to when no cloud API keys are present,
- * making `curl | sh` → "just works" possible without any accounts.
- */
-import type { Embedder, Extractor } from "./providers.js";
-import type { Extraction } from "../graph/types.js";
-
-/** Output dimensionality for known local embedding models. */
-const LOCAL_MODEL_DIMENSIONS: Record<string, number> = {
- "Xenova/all-MiniLM-L6-v2": 384,
- "Xenova/all-MiniLM-L12-v2": 384,
- "Xenova/bge-small-en-v1.5": 384,
- "Xenova/bge-base-en-v1.5": 768,
- "Xenova/gte-small": 384,
-};
-
-// transformers.js is loaded lazily so importing the engine never pays the cost
-// (or the native onnxruntime dependency) unless local embeddings are used.
-type FeaturePipeline = (
- texts: string[],
- opts: { pooling: "mean"; normalize: boolean },
-) => Promise<{ tolist(): number[][] }>;
-
-/**
- * Embedder that runs a sentence-transformer model in-process via transformers.js.
- * The model is downloaded once and cached under the transformers.js cache dir.
- */
-export class LocalEmbedder implements Embedder {
- readonly dimensions: number;
- private model: string;
- private pipe?: Promise<FeaturePipeline>;
-
- constructor(model = "Xenova/all-MiniLM-L6-v2") {
- this.model = model;
- this.dimensions = LOCAL_MODEL_DIMENSIONS[model] ?? 384;
- }
-
- private load(): Promise<FeaturePipeline> {
- if (!this.pipe) {
- this.pipe = import("@huggingface/transformers").then(({ pipeline, env }) => {
- // Keep console noise down; models still download+cache on first use.
- env.allowRemoteModels = true;
- // Default cache lives inside node_modules, which is read-only in
- // containers / global installs — allow relocating it.
- const cacheDir = process.env.CONTEXT_GRAPH_MODEL_CACHE;
- if (cacheDir) env.cacheDir = cacheDir;
- return pipeline("feature-extraction", this.model) as unknown as Promise<FeaturePipeline>;
- });
- }
- return this.pipe;
- }
-
- async embed(texts: string[]): Promise<number[][]> {
- if (texts.length === 0) return [];
- const pipe = await this.load();
- // Empty strings produce degenerate vectors; substitute a space.
- const inputs = texts.map((t) => (t.trim().length === 0 ? " " : t));
- const out = await pipe(inputs, { pooling: "mean", normalize: true });
- return out.tolist();
- }
-}
-
-/** JSON schema describing the extraction output — shared shape with the cloud extractor. */
-const EXTRACTION_SCHEMA = {
- type: "object",
- properties: {
- entities: {
- type: "array",
- items: {
- type: "object",
- properties: {
- name: { type: "string" },
- type: { type: "string" },
- summary: { type: "string" },
- aliases: { type: "array", items: { type: "string" } },
- },
- required: ["name", "type", "summary"],
- },
- },
- relations: {
- type: "array",
- items: {
- type: "object",
- properties: {
- source: { type: "string" },
- target: { type: "string" },
- relation: { type: "string" },
- description: { type: "string" },
- },
- required: ["source", "target", "relation"],
- },
- },
- },
- required: ["entities", "relations"],
-} as const;
-
-const SYSTEM_PROMPT = `You are a knowledge-graph extraction engine. Given a passage of text, identify the salient entities/concepts and the relationships between them.
-
-Rules:
-- Prefer specific, canonical entity names over pronouns or vague phrases.
-- Use coarse lowercase entity types, e.g. concept, system, service, api, person, org, policy, tool, event, metric.
-- Use snake_case relation predicates, e.g. depends_on, part_of, authenticates_with, produces, owns, replaces.
-- Only include relationships where BOTH endpoints are in your entities list.
-- Deduplicate obvious surface-form variants into one entity with aliases.
-- Do not invent facts unsupported by the text.
-Respond ONLY with a JSON object matching the schema.`;
-
-/**
- * Entity/relationship extractor backed by a locally running Ollama instance.
- * Uses Ollama's structured-output (`format`) support to get schema-valid JSON.
- */
-export class OllamaExtractor implements Extractor {
- private baseUrl: string;
- private model: string;
-
- constructor(model = "llama3.2", baseUrl = "http://localhost:11434") {
- this.model = model;
- this.baseUrl = baseUrl.replace(/\/$/, "");
- }
-
- async extract(text: string, opts?: { hint?: string }): Promise<Extraction> {
- const userContent = opts?.hint
- ? `Context hint: ${opts.hint}\n\nText:\n${text}`
- : `Text:\n${text}`;
-
- let res: Response;
- try {
- res = await fetch(`${this.baseUrl}/api/chat`, {
- method: "POST",
- headers: { "content-type": "application/json" },
- body: JSON.stringify({
- model: this.model,
- stream: false,
- format: EXTRACTION_SCHEMA,
- options: { temperature: 0 },
- messages: [
- { role: "system", content: SYSTEM_PROMPT },
- { role: "user", content: userContent },
- ],
- }),
- });
- } catch (err) {
- throw new Error(
- `Could not reach Ollama at ${this.baseUrl}. Start it (https://ollama.com) and pull a model ` +
- `(e.g. \`ollama pull ${this.model}\`), or set OPENROUTER_API_KEY to use cloud extraction. ` +
- `Underlying error: ${err instanceof Error ? err.message : String(err)}`,
- );
- }
-
- if (!res.ok) {
- const body = await res.text().catch(() => "");
- if (res.status === 404) {
- throw new Error(
- `Ollama has no model "${this.model}". Run \`ollama pull ${this.model}\`, or set ` +
- `CONTEXT_GRAPH_OLLAMA_MODEL to a model you have.`,
- );
- }
- throw new Error(`Ollama returned ${res.status}: ${body}`);
- }
-
- const data = (await res.json()) as { message?: { content?: string } };
- const content = data.message?.content ?? "";
- let parsed: Partial<Extraction>;
- try {
- parsed = JSON.parse(content) as Partial<Extraction>;
- } catch {
- return { entities: [], relations: [] };
- }
-
- return {
- entities: (parsed.entities ?? []).filter((e) => e && e.name && e.type),
- relations: (parsed.relations ?? []).filter(
- (r) => r && r.source && r.target && r.relation,
- ),
- };
- }
-}
diff --git a/src/ai/openai.ts b/src/ai/openai.ts
deleted file mode 100644
index 4de40874..00000000
--- a/src/ai/openai.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import OpenAI from "openai";
-import type { Embedder } from "./providers.js";
-
-/** Known output dimensionality for OpenAI embedding models. */
-const MODEL_DIMENSIONS: Record<string, number> = {
- "text-embedding-3-small": 1536,
- "text-embedding-3-large": 3072,
- "text-embedding-ada-002": 1536,
-};
-
-/** Embedder backed by the OpenAI embeddings API. */
-export class OpenAIEmbedder implements Embedder {
- readonly dimensions: number;
- private client: OpenAI;
- private model: string;
-
- constructor(apiKey: string, model: string) {
- this.client = new OpenAI({ apiKey });
- this.model = model;
- this.dimensions = MODEL_DIMENSIONS[model] ?? 1536;
- }
-
- async embed(texts: string[]): Promise<number[][]> {
- if (texts.length === 0) return [];
- // The API accepts batches; empty strings are not allowed, so guard them.
- const inputs = texts.map((t) => (t.trim().length === 0 ? " " : t));
- const response = await this.client.embeddings.create({
- model: this.model,
- input: inputs,
- });
- // Responses are returned in input order, but sort by index to be safe.
- return response.data
- .slice()
- .sort((a, b) => a.index - b.index)
- .map((d) => d.embedding as number[]);
- }
-}
diff --git a/src/ai/openrouter.ts b/src/ai/openrouter.ts
deleted file mode 100644
index 0320a663..00000000
--- a/src/ai/openrouter.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import OpenAI from "openai";
-import type { Extractor } from "./providers.js";
-import type { Extraction } from "../graph/types.js";
-
-/**
- * Entity/relationship extractor backed by OpenRouter (https://openrouter.ai).
- *
- * OpenRouter exposes an OpenAI-compatible chat-completions API in front of many
- * model providers, so we reuse the `openai` SDK with a custom `baseURL` and rely
- * on OpenAI-style tool calling to get schema-valid structured output. Pick any
- * tool-calling model via `CONTEXT_GRAPH_OPENROUTER_MODEL` (default gpt-4o-mini).
- */
-const EXTRACTION_TOOL = {
- type: "function" as const,
- function: {
- name: "record_graph",
- description:
- "Record the entities and relationships extracted from the text as a knowledge graph.",
- parameters: {
- type: "object",
- properties: {
- entities: {
- type: "array",
- description: "Distinct real-world entities or concepts mentioned in the text.",
- items: {
- type: "object",
- properties: {
- name: { type: "string", description: "Canonical, specific name of the entity." },
- type: {
- type: "string",
- description:
- "Coarse category, lowercase, e.g. concept, system, service, api, person, org, policy, tool, event, metric.",
- },
- summary: {
- type: "string",
- description:
- "One or two sentences describing the entity, grounded in the text.",
- },
- aliases: {
- type: "array",
- items: { type: "string" },
- description: "Alternate names/abbreviations used for this entity.",
- },
- },
- required: ["name", "type", "summary"],
- },
- },
- relations: {
- type: "array",
- description: "Directed relationships between the extracted entities.",
- items: {
- type: "object",
- properties: {
- source: { type: "string", description: "Name of the source entity." },
- target: { type: "string", description: "Name of the target entity." },
- relation: {
- type: "string",
- description:
- "Predicate in snake_case, e.g. depends_on, part_of, authenticates_with, produces, owns, replaces.",
- },
- description: {
- type: "string",
- description: "Short explanation of the relationship.",
- },
- },
- required: ["source", "target", "relation"],
- },
- },
- },
- required: ["entities", "relations"],
- },
- },
-};
-
-const SYSTEM_PROMPT = `You are a knowledge-graph extraction engine. Given a passage of text, identify the salient entities/concepts and the relationships between them.
-
-Rules:
-- Prefer specific, canonical entity names over pronouns or vague phrases.
-- Use coarse lowercase entity types, e.g. concept, system, service, api, person, org, policy, tool, event, metric.
-- Use snake_case relation predicates, e.g. depends_on, part_of, authenticates_with, produces, owns, replaces.
-- Only include relationships where BOTH endpoints are in your entities list.
-- Deduplicate: merge obvious surface-form variants into one entity with aliases.
-- Do not invent facts that are not supported by the text.
-Always respond by calling the record_graph tool.`;
-
-export class OpenRouterExtractor implements Extractor {
- private client: OpenAI;
- private model: string;
-
- constructor(apiKey: string, model: string, baseUrl = "https://openrouter.ai/api/v1") {
- this.client = new OpenAI({
- apiKey,
- baseURL: baseUrl,
- // Optional attribution headers OpenRouter surfaces in dashboards; harmless if unused.
- defaultHeaders: { "X-Title": "Context Graph Engine" },
- });
- this.model = model;
- }
-
- async extract(text: string, opts?: { hint?: string }): Promise<Extraction> {
- const userContent = opts?.hint
- ? `Context hint: ${opts.hint}\n\nText:\n${text}`
- : `Text:\n${text}`;
-
- const response = await this.client.chat.completions.create({
- model: this.model,
- temperature: 0,
- tools: [EXTRACTION_TOOL],
- tool_choice: { type: "function", function: { name: "record_graph" } },
- messages: [
- { role: "system", content: SYSTEM_PROMPT },
- { role: "user", content: userContent },
- ],
- });
-
- const call = response.choices[0]?.message?.tool_calls?.[0];
- if (!call || call.type !== "function") return { entities: [], relations: [] };
-
- let parsed: Partial<Extraction>;
- try {
- parsed = JSON.parse(call.function.arguments) as Partial<Extraction>;
- } catch {
- return { entities: [], relations: [] };
- }
-
- return {
- entities: (parsed.entities ?? []).filter((e) => e && e.name && e.type),
- relations: (parsed.relations ?? []).filter(
- (r) => r && r.source && r.target && r.relation,
- ),
- };
- }
-}
diff --git a/src/ai/providers.ts b/src/ai/providers.ts
index bf639562..349bc2d3 100644
--- a/src/ai/providers.ts
+++ b/src/ai/providers.ts
@@ -1,159 +1,72 @@
-import type { Extraction } from "../graph/types.js";
-import type { GraphStore } from "../graph/store.js";
import type { Summarizer } from "./summarize.js";
-
-/** Turns text into embedding vectors for semantic search and dedup. */
-export interface Embedder {
- /** Vector dimensionality produced by {@link embed}. */
- readonly dimensions: number;
- /** Embed a batch of texts, returning one vector per input (order preserved). */
- embed(texts: string[]): Promise<number[][]>;
-}
-
-/** Extracts entities and relationships from a passage of text. */
-export interface Extractor {
- extract(text: string, opts?: { hint?: string }): Promise<Extraction>;
-}
+import type { Synthesizer } from "./synthesize.js";
/**
- * User-facing configuration for the engine. Anything omitted falls back to
- * environment variables and then to sensible defaults.
+ * User-facing configuration. Anything omitted falls back to environment
+ * variables and then to sensible defaults. The engine runs fully locally
+ * (Ollama) unless an OpenRouter key is present.
*/
export interface EngineConfig {
- /** Path to the SQLite graph file. Env: CONTEXT_GRAPH_DB. Default: ./.context-graph/graph.db */
- dbPath?: string;
+ /** Where the graph lives. Env: CONTEXT_GRAPH_DIR. Default: `<repo>/.context`. */
+ contextDir?: string;
- /** OpenRouter key for extraction. Env: OPENROUTER_API_KEY. */
+ /** OpenRouter key for extraction + summarization. Env: OPENROUTER_API_KEY. */
openrouterApiKey?: string;
- /** Extraction model (an OpenRouter model id). Env: CONTEXT_GRAPH_OPENROUTER_MODEL. Default: openai/gpt-4o-mini */
+ /** OpenRouter model id. Env: CONTEXT_GRAPH_OPENROUTER_MODEL. Default: openai/gpt-4o-mini */
openrouterModel?: string;
/** OpenRouter API base URL. Env: OPENROUTER_BASE_URL. Default: https://openrouter.ai/api/v1 */
openrouterBaseUrl?: string;
- /**
- * OpenAI key for embeddings (optional — OpenRouter has no embeddings endpoint,
- * so embeddings run locally unless this is set). Env: OPENAI_API_KEY.
- */
- openaiApiKey?: string;
- /** Embedding model. Env: CONTEXT_GRAPH_EMBEDDING_MODEL. Default: text-embedding-3-small */
- embeddingModel?: string;
-
- /**
- * Force the fully-local providers (in-process embeddings + Ollama extraction)
- * even when an OpenRouter/OpenAI key is present. Env: CONTEXT_GRAPH_LOCAL=1.
- */
+ /** Force local providers (Ollama) even when an OpenRouter key is set. Env: CONTEXT_GRAPH_LOCAL=1. */
forceLocal?: boolean;
- /** Local embedding model (transformers.js). Env: CONTEXT_GRAPH_LOCAL_EMBEDDING_MODEL. Default: Xenova/all-MiniLM-L6-v2 */
- localEmbeddingModel?: string;
- /** Ollama model for local extraction. Env: CONTEXT_GRAPH_OLLAMA_MODEL. Default: llama3.2 */
+ /** Ollama model for local extraction/summarization. Env: CONTEXT_GRAPH_OLLAMA_MODEL. Default: llama3.2 */
ollamaModel?: string;
/** Ollama base URL. Env: CONTEXT_GRAPH_OLLAMA_URL. Default: http://localhost:11434 */
ollamaBaseUrl?: string;
- /** Target characters per chunk during ingestion. Default: 1200. */
- chunkSize?: number;
- /** Character overlap between adjacent chunks. Default: 200. */
- chunkOverlap?: number;
-
- /**
- * Cosine-similarity threshold above which two entities are treated as the
- * same node and merged. Higher = stricter. Default: 0.86.
- */
- mergeThreshold?: number;
-
- /**
- * When a changed file is re-ingested, prune the observations contributed by
- * its now-superseded prior version: facts that survived into the new version
- * are re-observed and stay, while facts that disappeared decay out (and orphan
- * nodes/edges are removed). This is what keeps the graph fresh instead of
- * accumulating stale facts forever. Env: CONTEXT_GRAPH_PRUNE (set to 0 to
- * disable). Default: true.
- */
- pruneSuperseded?: boolean;
-
// --- advanced: bring your own components ---
- /** Override the storage backend (defaults to a SQLite store at dbPath). */
- store?: GraphStore;
- /** Override the embedder (defaults to local, or OpenAI when a key is set). */
- embedder?: Embedder;
- /** Override the extractor (defaults to OpenRouter, or local Ollama with no key). */
- extractor?: Extractor;
- /** Override the code summarizer used by repo ingestion (same fallbacks as extractor). */
+ /** Override the synthesizer (defaults to OpenRouter, or local Ollama with no key). */
+ synthesizer?: Synthesizer;
+ /** Override the code summarizer (same fallbacks as the synthesizer). */
summarizer?: Summarizer;
}
/** Fully-resolved configuration with all defaults applied. */
export interface ResolvedConfig {
- dbPath: string;
+ contextDir?: string;
openrouterApiKey?: string;
openrouterModel: string;
openrouterBaseUrl: string;
- openaiApiKey?: string;
- embeddingModel: string;
forceLocal: boolean;
- localEmbeddingModel: string;
ollamaModel: string;
ollamaBaseUrl: string;
- chunkSize: number;
- chunkOverlap: number;
- mergeThreshold: number;
- pruneSuperseded: boolean;
- store?: GraphStore;
- embedder?: Embedder;
- extractor?: Extractor;
+ synthesizer?: Synthesizer;
summarizer?: Summarizer;
}
export const DEFAULTS = {
- dbPath: "./.context-graph/graph.db",
openrouterModel: "openai/gpt-4o-mini",
openrouterBaseUrl: "https://openrouter.ai/api/v1",
- embeddingModel: "text-embedding-3-small",
- localEmbeddingModel: "Xenova/all-MiniLM-L6-v2",
ollamaModel: "llama3.2",
ollamaBaseUrl: "http://localhost:11434",
- chunkSize: 1200,
- chunkOverlap: 200,
- mergeThreshold: 0.86,
} as const;
/** Merge user config with environment variables and defaults. */
export function resolveConfig(config: EngineConfig = {}): ResolvedConfig {
const env = process.env;
return {
- dbPath: config.dbPath ?? env.CONTEXT_GRAPH_DB ?? DEFAULTS.dbPath,
+ contextDir: config.contextDir ?? env.CONTEXT_GRAPH_DIR,
openrouterApiKey: config.openrouterApiKey ?? env.OPENROUTER_API_KEY,
openrouterModel:
- config.openrouterModel ??
- env.CONTEXT_GRAPH_OPENROUTER_MODEL ??
- DEFAULTS.openrouterModel,
+ config.openrouterModel ?? env.CONTEXT_GRAPH_OPENROUTER_MODEL ?? DEFAULTS.openrouterModel,
openrouterBaseUrl:
config.openrouterBaseUrl ?? env.OPENROUTER_BASE_URL ?? DEFAULTS.openrouterBaseUrl,
- openaiApiKey: config.openaiApiKey ?? env.OPENAI_API_KEY,
- embeddingModel:
- config.embeddingModel ??
- env.CONTEXT_GRAPH_EMBEDDING_MODEL ??
- DEFAULTS.embeddingModel,
forceLocal:
config.forceLocal ??
["1", "true", "yes"].includes((env.CONTEXT_GRAPH_LOCAL ?? "").toLowerCase()),
- localEmbeddingModel:
- config.localEmbeddingModel ??
- env.CONTEXT_GRAPH_LOCAL_EMBEDDING_MODEL ??
- DEFAULTS.localEmbeddingModel,
- ollamaModel:
- config.ollamaModel ?? env.CONTEXT_GRAPH_OLLAMA_MODEL ?? DEFAULTS.ollamaModel,
- ollamaBaseUrl:
- config.ollamaBaseUrl ?? env.CONTEXT_GRAPH_OLLAMA_URL ?? DEFAULTS.ollamaBaseUrl,
- chunkSize: config.chunkSize ?? DEFAULTS.chunkSize,
- chunkOverlap: config.chunkOverlap ?? DEFAULTS.chunkOverlap,
- mergeThreshold: config.mergeThreshold ?? DEFAULTS.mergeThreshold,
- pruneSuperseded:
- config.pruneSuperseded ??
- !["0", "false", "no"].includes((env.CONTEXT_GRAPH_PRUNE ?? "").toLowerCase()),
- store: config.store,
- embedder: config.embedder,
- extractor: config.extractor,
+ ollamaModel: config.ollamaModel ?? env.CONTEXT_GRAPH_OLLAMA_MODEL ?? DEFAULTS.ollamaModel,
+ ollamaBaseUrl: config.ollamaBaseUrl ?? env.CONTEXT_GRAPH_OLLAMA_URL ?? DEFAULTS.ollamaBaseUrl,
+ synthesizer: config.synthesizer,
summarizer: config.summarizer,
};
}
diff --git a/src/ai/synthesize.ts b/src/ai/synthesize.ts
new file mode 100644
index 00000000..5d18befa
--- /dev/null
+++ b/src/ai/synthesize.ts
@@ -0,0 +1,213 @@
+/**
+ * The synthesis step: turn per-file prose summaries into a CURATED set of graph
+ * nodes. This is where granularity is decided — the model groups related files
+ * into subsystem nodes, keeps a notable file as its own node when it deserves
+ * one, and adds cross-cutting concept nodes, instead of emitting one entity per
+ * incidental identifier. Each node is attributed to the source files it is
+ * grounded in, so provenance (and staleness) stays exact.
+ */
+import OpenAI from "openai";
+
+/** A directed edge to another node, by node name (resolved to a slug later). */
+export interface SynthLink {
+ to: string;
+ relation: string;
+ description?: string;
+}
+
+/** A node as proposed by the synthesizer, before it is written to disk. */
+export interface SynthNode {
+ name: string;
+ /** system | api | file | concept */
+ type: string;
+ summary: string;
+ /** Source file paths (from the provided set) this node is grounded in. */
+ sources: string[];
+ links: SynthLink[];
+}
+
+/** One labeled file summary fed into synthesis. */
+export interface FileSummary {
+ path: string;
+ summary: string;
+}
+
+export interface Synthesizer {
+ synthesize(files: FileSummary[]): Promise<SynthNode[]>;
+}
+
+const SYSTEM_PROMPT = `You build an ARCHITECTURE graph of a codebase from per-file summaries. The reader is an AI agent that will read this graph before working on the code, so it must describe the system at the level a senior engineer would explain it — not file by file.
+
+Produce a CURATED set of nodes of mixed granularity:
+- "system" nodes: GROUP files that collaborate as one component (usually a directory or a cohesive set) into a SINGLE node. This should be the most common node type. Prefer one system node over several file nodes.
+- "file" nodes: only for a substantial, standalone module that genuinely deserves its own node apart from its system.
+- "concept" nodes: cross-cutting ideas, design decisions, or invariants that span multiple files (e.g. "local-first provider fallback", "staleness checking", "content-hash provenance"). Include several — they are the most valuable nodes for an agent.
+
+Rules:
+- Strongly prefer FEWER, larger, meaningful nodes. For a repo of N files, aim for well under N nodes. Do NOT emit one node per file, and never a node per incidental identifier (a local interface, helper, or third-party symbol).
+- Merge duplicates and surface-form variants into one node.
+- For each node give: a canonical human-readable name; a type ("system" | "file" | "concept"); a 1-3 sentence summary of its ROLE in the system; "sources" = the exact file paths (from the input) it is grounded in (a system lists all its files; a concept lists the files that motivate it); and "links" to other nodes you define, each with a snake_case relation (depends_on, part_of, uses, implements, produces) and a short description.
+- Only link to nodes you actually define in this response.
+Respond only via the record_graph tool / JSON schema.`;
+
+const NODES_SCHEMA = {
+ type: "object",
+ properties: {
+ nodes: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ name: { type: "string" },
+ type: { type: "string" },
+ summary: { type: "string" },
+ sources: { type: "array", items: { type: "string" } },
+ links: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ to: { type: "string" },
+ relation: { type: "string" },
+ description: { type: "string" },
+ },
+ required: ["to", "relation"],
+ },
+ },
+ },
+ required: ["name", "type", "summary", "sources"],
+ },
+ },
+ },
+ required: ["nodes"],
+} as const;
+
+/** Cap the total summary text sent in one call so it never blows the context. */
+const MAX_INPUT_CHARS = 60_000;
+
+function userContent(files: FileSummary[]): string {
+ const body = files.map((f) => `## ${f.path}\n\n${f.summary}`).join("\n\n");
+ return body.length > MAX_INPUT_CHARS
+ ? `${body.slice(0, MAX_INPUT_CHARS)}\n… (truncated)`
+ : body;
+}
+
+/** Normalize a raw model response into clean {@link SynthNode}s. */
+function clean(nodes: unknown): SynthNode[] {
+ if (!Array.isArray(nodes)) return [];
+ const out: SynthNode[] = [];
+ for (const n of nodes as Array<Record<string, unknown>>) {
+ if (!n || typeof n.name !== "string" || typeof n.type !== "string") continue;
+ out.push({
+ name: n.name,
+ type: n.type,
+ summary: typeof n.summary === "string" ? n.summary : "",
+ sources: Array.isArray(n.sources) ? (n.sources as unknown[]).filter((s): s is string => typeof s === "string") : [],
+ links: Array.isArray(n.links)
+ ? (n.links as Array<Record<string, unknown>>)
+ .filter((l) => l && typeof l.to === "string" && typeof l.relation === "string")
+ .map((l) => ({
+ to: l.to as string,
+ relation: l.relation as string,
+ description: typeof l.description === "string" ? l.description : undefined,
+ }))
+ : [],
+ });
+ }
+ return out;
+}
+
+const RECORD_TOOL = {
+ type: "function" as const,
+ function: {
+ name: "record_graph",
+ description: "Record the curated architecture-graph nodes and their links.",
+ parameters: NODES_SCHEMA,
+ },
+};
+
+/** Synthesizer backed by OpenRouter's OpenAI-compatible chat API (tool calling). */
+export class OpenRouterSynthesizer implements Synthesizer {
+ private client: OpenAI;
+ private model: string;
+
+ constructor(apiKey: string, model: string, baseUrl = "https://openrouter.ai/api/v1") {
+ this.client = new OpenAI({ apiKey, baseURL: baseUrl, defaultHeaders: { "X-Title": "Context Graph Engine" } });
+ this.model = model;
+ }
+
+ async synthesize(files: FileSummary[]): Promise<SynthNode[]> {
+ if (files.length === 0) return [];
+ const response = await this.client.chat.completions.create({
+ model: this.model,
+ temperature: 0,
+ tools: [RECORD_TOOL],
+ tool_choice: { type: "function", function: { name: "record_graph" } },
+ messages: [
+ { role: "system", content: SYSTEM_PROMPT },
+ { role: "user", content: userContent(files) },
+ ],
+ });
+ const call = response.choices[0]?.message?.tool_calls?.[0];
+ if (!call || call.type !== "function") return [];
+ try {
+ return clean((JSON.parse(call.function.arguments) as { nodes?: unknown }).nodes);
+ } catch {
+ return [];
+ }
+ }
+}
+
+/** Synthesizer backed by a locally running Ollama instance (key-free). */
+export class OllamaSynthesizer implements Synthesizer {
+ private baseUrl: string;
+ private model: string;
+
+ constructor(model = "llama3.2", baseUrl = "http://localhost:11434") {
+ this.model = model;
+ this.baseUrl = baseUrl.replace(/\/$/, "");
+ }
+
+ async synthesize(files: FileSummary[]): Promise<SynthNode[]> {
+ if (files.length === 0) return [];
+ let res: Response;
+ try {
+ res = await fetch(`${this.baseUrl}/api/chat`, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({
+ model: this.model,
+ stream: false,
+ format: NODES_SCHEMA,
+ options: { temperature: 0 },
+ messages: [
+ { role: "system", content: SYSTEM_PROMPT },
+ { role: "user", content: userContent(files) },
+ ],
+ }),
+ });
+ } catch (err) {
+ throw new Error(
+ `Could not reach Ollama at ${this.baseUrl}. Start it (https://ollama.com) and pull a model ` +
+ `(e.g. \`ollama pull ${this.model}\`), or set OPENROUTER_API_KEY to use cloud synthesis. ` +
+ `Underlying error: ${err instanceof Error ? err.message : String(err)}`,
+ );
+ }
+ if (!res.ok) {
+ const body = await res.text().catch(() => "");
+ if (res.status === 404) {
+ throw new Error(
+ `Ollama has no model "${this.model}". Run \`ollama pull ${this.model}\`, or set ` +
+ `CONTEXT_GRAPH_OLLAMA_MODEL to a model you have.`,
+ );
+ }
+ throw new Error(`Ollama returned ${res.status}: ${body}`);
+ }
+ const data = (await res.json()) as { message?: { content?: string } };
+ try {
+ return clean((JSON.parse(data.message?.content ?? "{}") as { nodes?: unknown }).nodes);
+ } catch {
+ return [];
+ }
+ }
+}
diff --git a/src/cli.ts b/src/cli.ts
index 3d280547..bfa8e45e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1,649 +1,71 @@
#!/usr/bin/env node
/**
- * `context-graph` CLI — a thin wrapper over {@link ContextGraphEngine} for use
- * from the shell. Subcommands mirror the engine's core verbs:
+ * `context-graph` CLI. Two commands:
*
- * ingest / ingest-text build the graph from docs
- * query read the graph for a query (the agent's "read context")
- * contribute write a learning back into the graph
- * stats report how much the graph holds
+ * init build .context/ from your code (one markdown node per system,
+ * API, or concept; linked to each other; committed to the repo).
+ * check fail if .context/ has drifted from the code — for CI.
*
- * A `--db <path>` flag (or CONTEXT_GRAPH_DB) selects which graph file to use.
+ * Git is the sync: commit .context/ and anyone who clones the repo has the
+ * graph, with no setup.
*/
import "dotenv/config";
import { Command } from "commander";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { basename, dirname, join, resolve } from "node:path";
+import { relative } from "node:path";
import { ContextGraphEngine } from "./engine.js";
-import { GraphWatcher, type WatchEvent } from "./watch.js";
-import { resolveConfig } from "./ai/providers.js";
-import { toHtml, toMermaid } from "./graph/export.js";
-import { startServe } from "./serve.js";
+import { formatCheckReport } from "./context/check.js";
const program = new Command();
program
.name("context-graph")
- .description("Turn docs into a structured context graph that AI agents read from and write back to.")
- .option("--db <path>", "path to the graph database (overrides CONTEXT_GRAPH_DB)");
+ .description("Build a repo's context graph as linked markdown, and keep it in sync with the code.")
+ .option("--dir <path>", "context graph directory (default: <repo>/.context)")
+ .option("--local", "force local Ollama providers even when OPENROUTER_API_KEY is set");
function engineFrom(): ContextGraphEngine {
- const opts = program.opts<{ db?: string }>();
- return new ContextGraphEngine({ dbPath: opts.db });
+ const opts = program.opts<{ dir?: string; local?: boolean }>();
+ return new ContextGraphEngine({ contextDir: opts.dir, forceLocal: opts.local });
}
program
- .command("ingest")
- .description("Ingest one or more files into the graph")
- .argument("<paths...>", "files to ingest")
- .option("-t, --title <title>", "title override (single file only)")
- .action(async (paths: string[], opts: { title?: string }) => {
- const engine = engineFrom();
- try {
- for (const path of paths) {
- const r = await engine.ingestFile(path, { title: paths.length === 1 ? opts.title : undefined });
- if (r.skipped) {
- console.log(`• ${r.title} — already ingested, skipped`);
- } else {
- console.log(
- `✓ ${r.title} — ${r.chunks} chunks, +${r.nodesCreated} nodes (${r.nodesUpdated} reinforced), +${r.edgesCreated} edges (${r.edgesUpdated} reinforced)`,
- );
- }
- }
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("ingest-text")
- .description("Ingest text passed as an argument or piped via stdin")
- .argument("[text]", "text to ingest (or pipe via stdin)")
- .option("-t, --title <title>", "document title", "inline")
- .action(async (text: string | undefined, opts: { title: string }) => {
- const engine = engineFrom();
- try {
- const content = text ?? readFileSync(0, "utf8");
- const r = await engine.ingest(content, { title: opts.title });
- console.log(
- r.skipped
- ? `• already ingested, skipped`
- : `✓ ${r.chunks} chunks, +${r.nodesCreated} nodes, +${r.edgesCreated} edges`,
- );
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("query")
- .description("Read the graph for a query and print the context bundle")
- .argument("<text>", "the query")
- .option("--json", "output the full bundle as JSON")
- .option("-n, --max-nodes <n>", "max entities to surface", (v) => parseInt(v, 10), 8)
- .option("-c, --max-chunks <n>", "max source passages to surface", (v) => parseInt(v, 10), 6)
- .action(async (text: string, opts: { json?: boolean; maxNodes: number; maxChunks: number }) => {
- const engine = engineFrom();
- try {
- const bundle = await engine.read(text, {
- maxNodes: opts.maxNodes,
- maxChunks: opts.maxChunks,
- });
- console.log(opts.json ? JSON.stringify(bundle, null, 2) : bundle.prompt);
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("contribute")
- .description("Contribute a learning back into the graph")
- .argument("<text>", "the learning to record")
- .option("-a, --agent <id>", "agent identifier", "cli")
- .action(async (text: string, opts: { agent: string }) => {
- const engine = engineFrom();
- try {
- const r = await engine.contribute(text, { agentId: opts.agent });
- console.log(
- `✓ contributed — +${r.nodesCreated} nodes (${r.nodesUpdated} reinforced), +${r.edgesCreated} edges (${r.edgesUpdated} reinforced)`,
- );
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("ingest-dir")
- .description("Ingest every supported doc (.pdf .md .txt) in a directory, recursively")
- .argument("<dir>", "directory to ingest")
- .option("-w, --watch", "also register the directory for auto-watching")
- .action(async (dir: string, opts: { watch?: boolean }) => {
- const engine = engineFrom();
- try {
- const results = await engine.ingestDir(dir);
- if (results.length === 0) {
- console.log(`No supported files found under ${dir}`);
- }
- for (const r of results) {
- console.log(
- r.skipped
- ? `• ${r.title} — already ingested, skipped`
- : `✓ ${r.title} — ${r.chunks} chunks, +${r.nodesCreated} nodes, +${r.edgesCreated} edges`,
- );
- }
- if (opts.watch) {
- const w = engine.addWatchedDir(dir);
- console.log(`✓ registered ${w.dir} for auto-watch — run \`context-graph watch\` to start the daemon`);
- }
- } finally {
- await engine.close();
- }
- });
-
-/** One log line per watcher event, mirroring the ingest commands' ✓/•/✗ style. */
-function logWatchEvent(event: WatchEvent): void {
- switch (event.type) {
- case "watching":
- console.log(`watching ${event.dir} (${event.files} files to catch up on)`);
- break;
- case "queued":
- if (event.reason !== "initial") console.log(` queued ${event.file} (${event.reason})`);
- break;
- case "ingested":
- console.log(
- event.result.skipped
- ? `• ${event.result.title} — unchanged, skipped`
- : `✓ ${event.result.title} — ${event.result.chunks} chunks, +${event.result.nodesCreated} nodes, +${event.result.edgesCreated} edges`,
- );
- break;
- case "deleted": {
- const p = event.pruned;
- const detail = p
- ? ` (pruned ${p.nodesRemoved} entities, ${p.edgesRemoved} relationships; ${p.nodesDecayed} decayed)`
- : "";
- console.log(`• ${event.file} — deleted${detail}`);
- break;
- }
- case "error":
- console.error(`✗ ${event.file}: ${event.error}`);
- break;
- }
-}
-
-program
- .command("watch")
- .description(
- "Watch folders and keep the graph evolving: new and edited docs are re-ingested automatically. " +
- "With no arguments, resumes previously registered folders. Ctrl-C to stop.",
- )
- .argument("[dirs...]", "directories to watch (registered for future runs unless --no-register)")
- .option("-e, --ext <exts...>", 'extensions to ingest (default: ".pdf" ".md" ".markdown" ".txt")')
- .option("--debounce <ms>", "quiet time after a save before re-ingesting", (v) => parseInt(v, 10), 1500)
- .option("--no-register", "don't persist the given directories to the watch registry")
- .option("--no-initial-scan", "skip the catch-up scan of existing files at startup")
- .action(
- async (
- dirs: string[],
- opts: { ext?: string[]; debounce: number; register: boolean; initialScan: boolean },
- ) => {
- const engine = engineFrom();
- if (opts.register) {
- for (const dir of dirs) engine.addWatchedDir(dir, opts.ext);
- }
- const targets = new Set(dirs.map((d) => resolve(d)));
- for (const w of engine.listWatchedDirs()) targets.add(w.dir);
- if (targets.size === 0) {
- console.error("No watched folders. Run: context-graph watch <dir>");
- await engine.close();
- process.exit(1);
- }
-
- const watcher = new GraphWatcher(engine, {
- extensions: opts.ext,
- debounceMs: opts.debounce,
- initialScan: opts.initialScan,
- onEvent: logWatchEvent,
- });
- // The daemon owns the engine for its lifetime — closed on signal, not
- // in a finally like the one-shot commands.
- let stopping = false;
- const stop = async () => {
- if (stopping) return;
- stopping = true;
- console.log("\nstopping…");
- await watcher.close();
- await engine.close();
- process.exit(0);
- };
- process.on("SIGINT", () => void stop());
- process.on("SIGTERM", () => void stop());
-
- for (const dir of targets) await watcher.add(dir);
- await watcher.idle();
- console.log("caught up — watching for changes (Ctrl-C to stop)");
- },
- );
-
-program
- .command("watch-status")
- .description("List folders registered for auto-watching")
- .action(async () => {
- const engine = engineFrom();
- try {
- const dirs = engine.listWatchedDirs();
- if (dirs.length === 0) {
- console.log("No watched folders. Register one with: context-graph watch <dir>");
- return;
- }
- for (const w of dirs) {
- const exts = w.extensions?.join(" ") ?? "default extensions";
- console.log(`${w.dir} (${exts}, since ${w.addedAt.slice(0, 10)})`);
- }
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("unwatch")
- .description("Remove a folder from the auto-watch registry")
- .argument("<dir>", "directory to stop watching")
- .action(async (dir: string) => {
- const engine = engineFrom();
- try {
- console.log(
- engine.removeWatchedDir(dir)
- ? `✓ removed ${resolve(dir)} from the watch registry`
- : `• ${resolve(dir)} was not registered`,
- );
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("repo")
- .description(
- "Ingest a code repository as prose summaries (one LLM summary per file, grouped per top-level " +
- "directory). Raw code is never fed to the extractor. Incremental: only changed files are re-summarized.",
- )
- .argument("<dir>", "repository root")
+ .command("init")
+ .description("Build .context/ from your code — one markdown node per system, API, or concept")
+ .argument("[dir]", "repository root", ".")
.option("-e, --extensions <exts...>", 'code extensions to include (e.g. ".ts" ".py")')
.action(async (dir: string, opts: { extensions?: string[] }) => {
const engine = engineFrom();
- try {
- const r = await engine.ingestRepo(dir, {
- extensions: opts.extensions,
- onProgress: ({ phase, index, total, file }) =>
- process.stderr.write(
- `\r${phase === "summarize" ? "summarizing" : "ingesting"} ${index + 1}/${total}: ${file.slice(0, 60).padEnd(60)}`,
- ),
- });
- process.stderr.write("\n");
- console.log(
- `✓ ${r.files} code files — ${r.summarized} summarized, ${r.cached} unchanged (cache hits)`,
- );
- for (const m of r.modules) {
- console.log(
- m.skipped
- ? `• ${m.title} — unchanged, skipped`
- : `✓ ${m.title} — ${m.chunks} chunks, +${m.nodesCreated} nodes, +${m.edgesCreated} edges`,
- );
- }
- for (const e of r.errors) console.error(`✗ ${e}`);
- } finally {
- await engine.close();
- }
- });
-
-const ghExec = promisify(execFile);
-
-/** Run a `gh` command and parse its JSON output. */
-async function gh<T>(args: string[]): Promise<T> {
- try {
- const { stdout } = await ghExec("gh", args, { maxBuffer: 32_000_000 });
- return JSON.parse(stdout) as T;
- } catch (err) {
- const e = err as NodeJS.ErrnoException & { stderr?: string };
- if (e.code === "ENOENT") {
- throw new Error("GitHub CLI (`gh`) not found. Install it from https://cli.github.com and run `gh auth login`.");
- }
- throw new Error(`gh ${args.slice(0, 3).join(" ")} failed: ${e.stderr?.trim() || e.message}`);
- }
-}
-
-interface PrDetail {
- number: number;
- title: string;
- body: string;
- url: string;
- state: string;
- mergedAt: string | null;
- author: { login: string } | null;
- comments: Array<{ author: { login: string } | null; body: string }>;
- reviews: Array<{ author: { login: string } | null; state: string; body: string }>;
-}
-
-program
- .command("ingest-prs")
- .description("Ingest GitHub pull requests (title, description, review comments) via the gh CLI")
- .option("-R, --repo <owner/name>", "GitHub repository (default: the current directory's repo)")
- .option("-n, --limit <n>", "max PRs to ingest", (v) => parseInt(v, 10), 50)
- .option("-s, --state <state>", "open | closed | merged | all", "merged")
- .action(async (opts: { repo?: string; limit: number; state: string }) => {
- const repo =
- opts.repo ??
- (await gh<{ nameWithOwner: string }>(["repo", "view", "--json", "nameWithOwner"])).nameWithOwner;
- const list = await gh<Array<{ number: number }>>([
- "pr", "list", "--repo", repo, "--state", opts.state,
- "--limit", String(opts.limit), "--json", "number",
- ]);
- if (list.length === 0) {
- console.log(`No ${opts.state} PRs found in ${repo}.`);
- return;
- }
- const engine = engineFrom();
- try {
- for (const { number } of list) {
- const pr = await gh<PrDetail>([
- "pr", "view", String(number), "--repo", repo,
- "--json", "number,title,body,url,state,mergedAt,author,comments,reviews",
- ]);
- const discussion = [
- ...pr.reviews
- .filter((r) => r.body?.trim())
- .map((r) => `- ${r.author?.login ?? "unknown"} (review, ${r.state}): ${r.body.trim()}`),
- ...pr.comments
- .filter((c) => c.body?.trim())
- .map((c) => `- ${c.author?.login ?? "unknown"}: ${c.body.trim()}`),
- ];
- const text = [
- `# PR #${pr.number}: ${pr.title}`,
- `Repo: ${repo}. Author: ${pr.author?.login ?? "unknown"}. State: ${pr.state}${pr.mergedAt ? ` (merged ${pr.mergedAt.slice(0, 10)})` : ""}. ${pr.url}`,
- `## Description\n\n${pr.body?.trim() || "(no description)"}`,
- ...(discussion.length ? [`## Discussion\n\n${discussion.join("\n")}`] : []),
- ].join("\n\n");
- const r = await engine.ingest(text, {
- title: `PR #${pr.number}: ${pr.title}`,
- source: `pr:${repo}#${pr.number}`,
- });
- console.log(
- r.skipped
- ? `• PR #${pr.number} — already ingested, skipped`
- : `✓ PR #${pr.number}: ${pr.title} — +${r.nodesCreated} nodes, +${r.edgesCreated} edges`,
- );
- }
- } finally {
- await engine.close();
- }
- });
-
-/** The two hook commands install-hooks wires into Claude Code. */
-const SESSION_START_CMD = "context-graph hook session-start";
-const STOP_CMD = "context-graph hook stop";
-
-program
- .command("install-hooks")
- .description("Install Claude Code hooks: inject graph context at session start, nudge a contribution at stop")
- .option("--dir <path>", "project directory (default: current directory)")
- .option("--no-stop", "skip the Stop hook (the contribution nudge)")
- .action(async (opts: { dir?: string; stop: boolean }) => {
- const projectDir = resolve(opts.dir ?? ".");
- const settingsPath = join(projectDir, ".claude", "settings.json");
- let settings: Record<string, unknown> = {};
- if (existsSync(settingsPath)) {
- settings = JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
- }
- const hooks = (settings.hooks ??= {}) as Record<
- string,
- Array<{ matcher?: string; hooks: Array<{ type: string; command: string }> }>
- >;
- const addHook = (event: string, command: string): boolean => {
- const entries = (hooks[event] ??= []);
- if (entries.some((e) => e.hooks?.some((h) => h.command === command))) return false;
- entries.push({ hooks: [{ type: "command", command }] });
- return true;
- };
- const added: string[] = [];
- if (addHook("SessionStart", SESSION_START_CMD)) added.push("SessionStart");
- if (opts.stop && addHook("Stop", STOP_CMD)) added.push("Stop");
- mkdirSync(dirname(settingsPath), { recursive: true });
- writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+ const r = await engine.init(dir, {
+ extensions: opts.extensions,
+ onProgress: ({ phase, index, total, file }) =>
+ process.stderr.write(
+ `\r${phase === "summarize" ? "reading" : "writing"} ${index + 1}/${total}: ${file.slice(0, 50).padEnd(50)}`,
+ ),
+ });
+ process.stderr.write("\n");
console.log(
- added.length
- ? `✓ installed ${added.join(" + ")} hook${added.length > 1 ? "s" : ""} in ${settingsPath}`
- : `• hooks already installed in ${settingsPath}`,
- );
- console.log(" SessionStart injects relevant graph context; Stop nudges the agent to contribute learnings.");
- });
-
-const hook = program
- .command("hook")
- .description("Claude Code hook entry points (installed by `install-hooks`; not usually run by hand)");
-
-hook
- .command("session-start")
- .description("Print relevant graph context for injection at Claude Code session start")
- .action(async () => {
- // No graph yet → stay silent rather than erroring inside the hook.
- const cfg = resolveConfig({ dbPath: program.opts<{ db?: string }>().db });
- if (cfg.dbPath !== ":memory:" && !existsSync(cfg.dbPath)) return;
- const engine = engineFrom();
- try {
- const stats = await engine.stats();
- if (stats.nodes === 0) return;
- const project = basename(process.cwd());
- const bundle = await engine.read(
- `${project}: conventions, architecture decisions, gotchas, current work`,
- { maxNodes: 8, maxChunks: 4 },
- );
- if (bundle.nodes.length === 0 && bundle.chunks.length === 0) return;
- console.log("## Team context graph (auto-injected at session start)\n");
- console.log(bundle.prompt);
- console.log(
- "\nWhen you learn something durable this session (a decision, gotcha, or convention), " +
- "record it with the context_contribute MCP tool.",
- );
- } finally {
- await engine.close();
- }
- });
-
-hook
- .command("stop")
- .description("Nudge the agent to contribute session learnings before finishing")
- .action(async () => {
- // Reads the Stop-hook JSON from stdin. `stop_hook_active` means this stop
- // was already extended by us once — let it through or we'd loop forever.
- let input: { stop_hook_active?: boolean } = {};
- try {
- input = JSON.parse(readFileSync(0, "utf8")) as { stop_hook_active?: boolean };
- } catch {
- /* no stdin — treat as a plain stop */
- }
- if (input.stop_hook_active) return;
- const cfg = resolveConfig({ dbPath: program.opts<{ db?: string }>().db });
- if (cfg.dbPath !== ":memory:" && !existsSync(cfg.dbPath)) return;
- console.log(
- JSON.stringify({
- decision: "block",
- reason:
- "Before finishing: if this session produced a durable, non-obvious learning (a decision made, " +
- "a gotcha hit, a convention discovered, a fix future agents should know about), record each one " +
- "with the context_contribute MCP tool. If nothing is worth recording, finish without contributing.",
- }),
- );
- });
-
-program
- .command("export")
- .description("Export the whole graph for viewing (interactive HTML, JSON, or Mermaid)")
- .option("-f, --format <fmt>", "html | json | mermaid", "html")
- .option("-o, --out <path>", "output file (default: context-graph.<ext>)")
- .action(async (opts: { format: string; out?: string }) => {
- const engine = engineFrom();
- try {
- const g = await engine.exportGraph();
- let content: string;
- let ext: string;
- if (opts.format === "json") {
- content = JSON.stringify(g, null, 2);
- ext = "json";
- } else if (opts.format === "mermaid") {
- content = toMermaid(g);
- ext = "mmd";
- } else {
- content = toHtml(g);
- ext = "html";
- }
- const out = opts.out ?? `context-graph.${ext}`;
- writeFileSync(out, content);
- console.log(`✓ wrote ${g.nodes.length} entities / ${g.edges.length} relationships to ${out}`);
- if (ext === "html") console.log(` open it: open ${out}`);
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("stats")
- .description("Show graph statistics")
- .action(async () => {
- const engine = engineFrom();
- try {
- const s = await engine.stats();
- console.log(`documents: ${s.documents}\nnodes: ${s.nodes}\nedges: ${s.edges}\nchunks: ${s.chunks}`);
- } finally {
- await engine.close();
- }
- });
-
-/** Resolve the graph-file path for team sync (flag overrides the default). */
-function syncFilePath(engine: ContextGraphEngine, flag?: string): string {
- const file = flag ?? engine.graphFilePath;
- if (!file) {
- throw new Error(
- "No graph file path — an in-memory graph can't be synced. Pass --file <path> or use a file-backed --db.",
+ `✓ ${r.nodes} nodes, ${r.links} links from ${r.files} files ` +
+ `(${r.summarized} read, ${r.cached} cached)`,
);
- }
- return file;
-}
-
-program
- .command("push")
- .description("Team sync (git mode): write the graph to a committable JSONL file")
- .option("--file <path>", "graph file (default: graph.jsonl next to the db)")
- .action(async (opts: { file?: string }) => {
- const engine = engineFrom();
- try {
- const file = syncFilePath(engine, opts.file);
- writeFileSync(file, await engine.exportJsonl());
- const s = await engine.stats();
- console.log(`✓ wrote ${s.nodes} entities / ${s.edges} relationships to ${file}`);
- console.log(` commit it: git add ${file} && git commit -m "update context graph"`);
- } finally {
- await engine.close();
- }
+ console.log(` → ${r.contextDir}`);
+ for (const e of r.errors) console.error(`✗ ${e}`);
+ const rel = relative(process.cwd(), r.contextDir) || ".context";
+ console.log(` commit it: git add ${rel} && git commit -m "update context graph"`);
});
program
- .command("pull")
- .description("Team sync (git mode): import + re-merge a teammate's JSONL file")
- .option("--file <path>", "graph file (default: graph.jsonl next to the db)")
- .action(async (opts: { file?: string }) => {
+ .command("check")
+ .description("Fail if .context/ is stale relative to the code (for CI)")
+ .argument("[dir]", "repository root", ".")
+ .option("-e, --extensions <exts...>", "code extensions to include")
+ .option("--json", "output the drift as JSON")
+ .action((dir: string, opts: { extensions?: string[]; json?: boolean }) => {
const engine = engineFrom();
- try {
- const file = syncFilePath(engine, opts.file);
- if (!existsSync(file)) {
- console.log(`No graph file at ${file} yet — nothing to pull.`);
- return;
- }
- const r = await engine.importJsonl(readFileSync(file, "utf8"));
- for (const w of r.warnings) console.warn(`⚠ ${w}`);
- console.log(
- `✓ merged ${file} — +${r.nodesCreated} nodes (${r.nodesUpdated} reinforced), ` +
- `+${r.edgesCreated} edges (${r.edgesUpdated} reinforced), ` +
- `+${r.documentsAdded} docs, +${r.chunksAdded} sources`,
- );
- } finally {
- await engine.close();
- }
+ const r = engine.check(dir, { extensions: opts.extensions });
+ console.log(opts.json ? JSON.stringify(r, null, 2) : formatCheckReport(r));
+ if (!r.ok) process.exit(1);
});
-program
- .command("sync")
- .description("Team sync (git mode): pull a teammate's JSONL, re-merge, then push the merged graph")
- .option("--file <path>", "graph file (default: graph.jsonl next to the db)")
- .action(async (opts: { file?: string }) => {
- const engine = engineFrom();
- try {
- const file = syncFilePath(engine, opts.file);
- if (existsSync(file)) {
- const r = await engine.importJsonl(readFileSync(file, "utf8"));
- for (const w of r.warnings) console.warn(`⚠ ${w}`);
- console.log(
- `↓ merged in — +${r.nodesCreated} nodes (${r.nodesUpdated} reinforced), ` +
- `+${r.edgesCreated} edges (${r.edgesUpdated} reinforced)`,
- );
- }
- writeFileSync(file, await engine.exportJsonl());
- const s = await engine.stats();
- console.log(`↑ wrote merged graph (${s.nodes} entities / ${s.edges} relationships) to ${file}`);
- console.log(` commit it: git add ${file} && git commit -m "sync context graph"`);
- } finally {
- await engine.close();
- }
- });
-
-program
- .command("serve")
- .description(
- "Run everything in one process: the web UI, the MCP server (over HTTP at /mcp), and the " +
- "watcher — one engine, one watcher, one port. Resumes registered folders unless --no-watch.",
- )
- .argument("[dirs...]", "extra folders to register and watch")
- .option("-p, --port <port>", "port to listen on (default 4680)", (v) => parseInt(v, 10))
- .option("-H, --host <host>", "host to bind (default 127.0.0.1; use 0.0.0.0 to expose)")
- .option("-e, --ext <exts...>", 'extensions to watch (default: ".pdf" ".md" ".markdown" ".txt")')
- .option("--no-watch", "start the web/MCP servers without resuming or watching any folders")
- .action(
- async (
- dirs: string[],
- opts: { port?: number; host?: string; ext?: string[]; watch: boolean },
- ) => {
- const { db } = program.opts<{ db?: string }>();
- const running = await startServe({
- host: opts.host,
- port: opts.port,
- watch: opts.watch,
- dirs,
- extensions: opts.ext,
- engineConfig: { dbPath: db },
- });
- const cfg = resolveConfig({ dbPath: db });
- const watched = running.engine.listWatchedDirs().length;
- console.log(`Context Graph → ${running.url}`);
- console.log(` web UI: ${running.url}`);
- console.log(` MCP (HTTP): ${running.url}/mcp`);
- console.log(` graph db: ${resolve(cfg.dbPath)}`);
- if (opts.watch && watched > 0) console.log(` watching: ${watched} registered folder(s)`);
- console.log(" Ctrl-C to stop.");
-
- let stopping = false;
- const stop = async () => {
- if (stopping) return;
- stopping = true;
- console.log("\nstopping…");
- await running.close();
- process.exit(0);
- };
- process.on("SIGINT", () => void stop());
- process.on("SIGTERM", () => void stop());
- },
- );
-
program.parseAsync().catch((err) => {
console.error(err instanceof Error ? err.message : err);
process.exit(1);
diff --git a/src/context/build.ts b/src/context/build.ts
new file mode 100644
index 00000000..463a9f1c
--- /dev/null
+++ b/src/context/build.ts
@@ -0,0 +1,349 @@
+/**
+ * `init` — build the `.context/` graph from a code repository.
+ *
+ * Pipeline (no database, no embeddings):
+ * 1. Walk the repo for source files.
+ * 2. Summarize each file to prose (one LLM call per file, cached by content hash).
+ * 3. Synthesize a CURATED node set from the labeled summaries (the synthesizer
+ * decides granularity: subsystems, notable files, and concepts). This is
+ * one LLM call per batch of summaries; batches are cached by content.
+ * 4. Resolve node names → slugs and links → edges; attribute each node to its
+ * source files so staleness stays exact.
+ * 5. Write one markdown file per node (preserving human notes) + a manifest.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { walkDir } from "../ingest/fs.js";
+import { contentHash } from "../util/id.js";
+import type { Summarizer } from "../ai/summarize.js";
+import type { FileSummary, SynthNode, Synthesizer } from "../ai/synthesize.js";
+import {
+ CACHE_DIR,
+ MANIFEST_VERSION,
+ contextDirFor,
+ deleteNode,
+ digestSources,
+ existingNodeSlugs,
+ slugify,
+ writeManifest,
+ writeNode,
+ type ContextNode,
+ type Manifest,
+ type NodeLink,
+ type SourceRef,
+} from "./node-file.js";
+
+/** Extensions treated as source code. */
+export const CODE_EXTENSIONS = [
+ ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+ ".py", ".go", ".rs", ".java", ".kt", ".scala",
+ ".rb", ".php", ".c", ".h", ".cpp", ".hpp", ".cc",
+ ".cs", ".swift", ".sql", ".sh", ".proto",
+];
+
+/** Char budget of summary text per synthesis call (keeps each call in-context). */
+const BATCH_CHAR_BUDGET = 48_000;
+
+export interface BuildProgress {
+ phase: "summarize" | "synthesize" | "write";
+ index: number;
+ total: number;
+ file: string;
+}
+
+export interface BuildOptions {
+ /** Override the output dir (default: `<root>/.context`). */
+ contextDir?: string;
+ /** Extensions to treat as code. Default: {@link CODE_EXTENSIONS}. */
+ extensions?: string[];
+ /** Human label for the model, recorded in the manifest (e.g. "ollama:llama3.2"). */
+ model: string;
+ summarizer: Summarizer;
+ synthesizer: Synthesizer;
+ onProgress?: (info: BuildProgress) => void;
+}
+
+export interface BuildResult {
+ contextDir: string;
+ files: number;
+ summarized: number;
+ cached: number;
+ batches: number;
+ nodes: number;
+ links: number;
+ errors: string[];
+}
+
+/** The gitignored LLM-call cache: per-file summaries + per-batch synthesis. */
+interface BuildCache {
+ summaries: Record<string, { hash: string; summary: string }>;
+ synth: Record<string, SynthNode[]>;
+}
+
+interface FileWork {
+ rel: string;
+ hash: string;
+ summary?: string;
+}
+
+/** A node under construction, before its digest/links are finalized. */
+interface NodeDraft {
+ name: string;
+ slug: string;
+ type: string;
+ summary: string;
+ sources: Map<string, string>; // path → hash
+ links: Map<string, NodeLink>; // "to|relation" → link
+}
+
+export async function buildContext(dir: string, opts: BuildOptions): Promise<BuildResult> {
+ const root = resolve(dir);
+ const outDir = contextDirFor(root, opts.contextDir);
+ const exts = opts.extensions ?? CODE_EXTENSIONS;
+ const files = walkDir(root)
+ .filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)))
+ .filter((f) => !f.startsWith(outDir));
+
+ const cache = loadCache(outDir);
+ const result: BuildResult = {
+ contextDir: outDir,
+ files: 0,
+ summarized: 0,
+ cached: 0,
+ batches: 0,
+ nodes: 0,
+ links: 0,
+ errors: [],
+ };
+
+ // Phase 1: summarize each file, concurrent, content-hash cached.
+ const work = await mapWithConcurrency(files, 8, async (file, i): Promise<FileWork | undefined> => {
+ const rel = relative(root, file);
+ opts.onProgress?.({ phase: "summarize", index: i, total: files.length, file: rel });
+ let code: string;
+ try {
+ code = readFileSync(file, "utf8");
+ } catch (err) {
+ result.errors.push(`${rel}: ${errMsg(err)}`);
+ return undefined;
+ }
+ const hash = contentHash(code);
+ const hit = cache.summaries[rel];
+ if (hit && hit.hash === hash) {
+ result.cached++;
+ return { rel, hash, summary: hit.summary };
+ }
+ try {
+ const summary = await opts.summarizer.summarize(code, { path: rel });
+ cache.summaries[rel] = { hash, summary };
+ result.summarized++;
+ return { rel, hash, summary };
+ } catch (err) {
+ result.errors.push(`${rel}: ${errMsg(err)}`);
+ return { rel, hash }; // covered (counts against staleness) but not summarized
+ }
+ });
+
+ const processed = work.filter((w): w is FileWork => w !== undefined);
+ result.files = processed.length;
+ const hashByPath = new Map(processed.map((w) => [w.rel, w.hash]));
+
+ // Phase 2: synthesize curated nodes from the summaries, batched + cached.
+ const summarized: FileSummary[] = processed
+ .filter((w): w is FileWork & { summary: string } => Boolean(w.summary))
+ .map((w) => ({ path: w.rel, summary: w.summary }))
+ .sort((a, b) => a.path.localeCompare(b.path));
+ const batches = batchBySize(summarized, BATCH_CHAR_BUDGET);
+ result.batches = batches.length;
+
+ const synthNodes: SynthNode[] = [];
+ for (let b = 0; b < batches.length; b++) {
+ opts.onProgress?.({ phase: "synthesize", index: b, total: batches.length, file: `batch ${b + 1}` });
+ const key = batchKey(batches[b], hashByPath);
+ let nodes = cache.synth[key];
+ if (!nodes) {
+ nodes = await opts.synthesizer.synthesize(batches[b]);
+ cache.synth[key] = nodes;
+ }
+ synthNodes.push(...nodes);
+ }
+ // Drop cache entries for batches we no longer produce, so it can't grow forever.
+ cache.synth = Object.fromEntries(
+ batches.map((batch) => [batchKey(batch, hashByPath), cache.synth[batchKey(batch, hashByPath)] ?? []]),
+ );
+ saveCache(outDir, cache);
+
+ // Phase 3: merge synth nodes by slug, building a name→slug resolution table.
+ const drafts = new Map<string, NodeDraft>();
+ const nameToSlug = new Map<string, string>();
+ for (const n of synthNodes) {
+ const slug = slugify(n.name);
+ let draft = drafts.get(slug);
+ if (!draft) {
+ draft = { name: n.name, slug, type: n.type || "concept", summary: n.summary ?? "", sources: new Map(), links: new Map() };
+ drafts.set(slug, draft);
+ }
+ if ((n.summary?.length ?? 0) > draft.summary.length) draft.summary = n.summary;
+ if (n.type && draft.type === "concept") draft.type = n.type;
+ for (const src of n.sources) {
+ const hash = hashByPath.get(src);
+ if (hash) draft.sources.set(src, hash);
+ }
+ registerName(nameToSlug, n.name, slug);
+ }
+
+ // Phase 4: resolve links to slugs (both endpoints must be defined nodes).
+ for (const n of synthNodes) {
+ const from = drafts.get(slugify(n.name));
+ if (!from) continue;
+ for (const link of n.links) {
+ const to = resolveSlug(nameToSlug, link.to);
+ if (!to || to === from.slug) continue;
+ const key = `${to}|${link.relation}`;
+ if (!from.links.has(key)) from.links.set(key, { to, relation: link.relation, description: link.description });
+ }
+ }
+
+ // Concept nodes the model didn't attribute to files inherit the provenance of
+ // the nodes they link to, so they still go stale when their subject changes.
+ for (const draft of drafts.values()) {
+ if (draft.sources.size > 0) continue;
+ for (const link of draft.links.values()) {
+ const target = drafts.get(link.to);
+ if (target) for (const [p, h] of target.sources) draft.sources.set(p, h);
+ }
+ }
+
+ // Phase 5: finalize, reconcile with disk, write.
+ const nodes: ContextNode[] = [...drafts.values()].map((d) => {
+ const sources: SourceRef[] = [...d.sources.entries()]
+ .map(([path, hash]) => ({ path, hash }))
+ .sort((a, b) => a.path.localeCompare(b.path));
+ return {
+ name: d.name,
+ slug: d.slug,
+ type: d.type || "concept",
+ summary: d.summary,
+ sources,
+ sourcesDigest: digestSources(sources),
+ links: [...d.links.values()].sort((a, b) => a.to.localeCompare(b.to)),
+ human: "",
+ };
+ });
+ nodes.sort((a, b) => a.slug.localeCompare(b.slug));
+
+ const liveSlugs = new Set(nodes.map((n) => n.slug));
+ for (const slug of existingNodeSlugs(outDir)) {
+ if (!liveSlugs.has(slug)) deleteNode(outDir, slug);
+ }
+ for (let i = 0; i < nodes.length; i++) {
+ opts.onProgress?.({ phase: "write", index: i, total: nodes.length, file: nodes[i].slug });
+ writeNode(outDir, nodes[i]);
+ }
+ result.nodes = nodes.length;
+ result.links = nodes.reduce((n, node) => n + node.links.length, 0);
+
+ // Manifest: authoritative file→hash map (every processed file) + node roster.
+ const fileRefs: SourceRef[] = processed
+ .map((w) => ({ path: w.rel, hash: w.hash }))
+ .sort((a, b) => a.path.localeCompare(b.path));
+ const manifest: Manifest = {
+ version: MANIFEST_VERSION,
+ model: opts.model,
+ repoDigest: digestSources(fileRefs),
+ files: fileRefs,
+ nodes: nodes.map((n) => ({
+ slug: n.slug,
+ name: n.name,
+ type: n.type,
+ sources: n.sources.map((s) => s.path),
+ sourcesDigest: n.sourcesDigest,
+ })),
+ };
+ writeManifest(outDir, manifest);
+
+ return result;
+}
+
+/** Greedily pack file summaries into batches under a char budget (≥1 file each). */
+function batchBySize(files: FileSummary[], budget: number): FileSummary[][] {
+ const batches: FileSummary[][] = [];
+ let cur: FileSummary[] = [];
+ let size = 0;
+ for (const f of files) {
+ const len = f.path.length + f.summary.length + 8;
+ if (cur.length > 0 && size + len > budget) {
+ batches.push(cur);
+ cur = [];
+ size = 0;
+ }
+ cur.push(f);
+ size += len;
+ }
+ if (cur.length > 0) batches.push(cur);
+ return batches;
+}
+
+/** Stable key for a batch: its files and their content hashes. */
+function batchKey(batch: FileSummary[], hashByPath: Map<string, string>): string {
+ return contentHash(
+ batch
+ .map((f) => `${f.path}:${hashByPath.get(f.path) ?? ""}`)
+ .sort()
+ .join("\n"),
+ );
+}
+
+function registerName(table: Map<string, string>, name: string, slug: string): void {
+ const key = name.trim().toLowerCase();
+ if (key && !table.has(key)) table.set(key, slug);
+}
+
+function resolveSlug(table: Map<string, string>, name: string): string | undefined {
+ return table.get(name.trim().toLowerCase());
+}
+
+function errMsg(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+function cachePath(outDir: string): string {
+ return join(outDir, CACHE_DIR, "summaries.json");
+}
+
+function loadCache(outDir: string): BuildCache {
+ const path = cachePath(outDir);
+ if (existsSync(path)) {
+ try {
+ const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<BuildCache>;
+ return { summaries: parsed.summaries ?? {}, synth: parsed.synth ?? {} };
+ } catch {
+ /* fall through to empty */
+ }
+ }
+ return { summaries: {}, synth: {} };
+}
+
+function saveCache(outDir: string, cache: BuildCache): void {
+ const path = cachePath(outDir);
+ mkdirSync(join(outDir, CACHE_DIR), { recursive: true });
+ writeFileSync(path, JSON.stringify(cache, null, 2));
+}
+
+/** Run `fn` over `items` with at most `limit` in flight, preserving order. */
+async function mapWithConcurrency<T, R>(
+ items: T[],
+ limit: number,
+ fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+ const results: R[] = new Array(items.length);
+ let next = 0;
+ const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+ while (next < items.length) {
+ const i = next++;
+ results[i] = await fn(items[i], i);
+ }
+ });
+ await Promise.all(workers);
+ return results;
+}
diff --git a/src/context/check.ts b/src/context/check.ts
new file mode 100644
index 00000000..ee0f6775
--- /dev/null
+++ b/src/context/check.ts
@@ -0,0 +1,139 @@
+/**
+ * `check` — is the committed `.context/` graph still in sync with the code?
+ *
+ * Pure I/O + hashing: no LLM, no network, milliseconds. It re-hashes the source
+ * files the manifest recorded and compares. Meant to run in CI: exit 0 when the
+ * graph is fresh, 1 when it has drifted (so a PR that changed code but not the
+ * graph fails until `context-graph init` is re-run and committed).
+ *
+ * Drift categories:
+ * content a recorded source file's bytes changed
+ * removed a recorded source file no longer exists
+ * coverage a code file exists that no node was built from (new/uningested)
+ * index a node's frontmatter disagrees with the manifest (hand-edited)
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { walkDir } from "../ingest/fs.js";
+import { contentHash } from "../util/id.js";
+import { CODE_EXTENSIONS } from "./build.js";
+import { contextDirFor, readManifest, readNodes } from "./node-file.js";
+
+export interface CheckResult {
+ ok: boolean;
+ /** True when there is no graph at all (init has never run). */
+ missing: boolean;
+ contentDrift: Array<{ path: string; from: string; to: string }>;
+ removed: string[];
+ coverage: string[];
+ indexDrift: string[];
+}
+
+export interface CheckOptions {
+ contextDir?: string;
+ extensions?: string[];
+}
+
+export function checkContext(dir: string, opts: CheckOptions = {}): CheckResult {
+ const root = resolve(dir);
+ const outDir = contextDirFor(root, opts.contextDir);
+ const exts = opts.extensions ?? CODE_EXTENSIONS;
+
+ const result: CheckResult = {
+ ok: false,
+ missing: false,
+ contentDrift: [],
+ removed: [],
+ coverage: [],
+ indexDrift: [],
+ };
+
+ const manifest = readManifest(outDir);
+ if (!manifest) {
+ result.missing = true;
+ return result;
+ }
+
+ // Current code files on disk (same rules `init` used).
+ const current = new Map<string, string>(); // rel → hash
+ for (const file of walkDir(root)) {
+ if (file.startsWith(outDir)) continue;
+ if (!exts.some((e) => file.toLowerCase().endsWith(e))) continue;
+ try {
+ current.set(relative(root, file), contentHash(readFileSync(file, "utf8")));
+ } catch {
+ // Unreadable now → treat as removed below (it won't be in `current`).
+ }
+ }
+
+ // Compare the manifest's recorded files against what's on disk.
+ const recorded = new Set<string>();
+ for (const ref of manifest.files) {
+ recorded.add(ref.path);
+ const now = current.get(ref.path);
+ if (now === undefined) {
+ result.removed.push(ref.path);
+ } else if (now !== ref.hash) {
+ result.contentDrift.push({ path: ref.path, from: short(ref.hash), to: short(now) });
+ }
+ }
+ for (const path of current.keys()) {
+ if (!recorded.has(path)) result.coverage.push(path);
+ }
+
+ // Node frontmatter must agree with the manifest roster (catches hand edits).
+ const manifestNodes = new Map(manifest.nodes.map((n) => [n.slug, n]));
+ const onDisk = readNodes(outDir);
+ const seen = new Set<string>();
+ for (const node of onDisk) {
+ seen.add(node.slug);
+ const m = manifestNodes.get(node.slug);
+ if (!m) {
+ result.indexDrift.push(`${node.slug}: node file not in manifest`);
+ } else if (m.sourcesDigest !== node.sourcesDigest) {
+ result.indexDrift.push(`${node.slug}: frontmatter digest ≠ manifest`);
+ }
+ }
+ for (const slug of manifestNodes.keys()) {
+ if (!seen.has(slug)) result.indexDrift.push(`${slug}: in manifest but node file missing`);
+ }
+
+ result.ok =
+ result.contentDrift.length === 0 &&
+ result.removed.length === 0 &&
+ result.coverage.length === 0 &&
+ result.indexDrift.length === 0;
+ return result;
+}
+
+/** Render a check result as a human-readable report. */
+export function formatCheckReport(r: CheckResult): string {
+ if (r.missing) {
+ return "context-graph check: NO GRAPH\n\nNo .context/manifest.json found. Run `context-graph init` first.";
+ }
+ if (r.ok) return "context-graph check: OK — the graph is in sync with the code.";
+
+ const lines: string[] = ["context-graph check: STALE", ""];
+ if (r.contentDrift.length) {
+ lines.push(`changed (${r.contentDrift.length}):`);
+ for (const c of r.contentDrift) lines.push(` ~ ${c.path} (${c.from} → ${c.to})`);
+ }
+ if (r.removed.length) {
+ lines.push(`removed (${r.removed.length}):`);
+ for (const p of r.removed) lines.push(` - ${p}`);
+ }
+ if (r.coverage.length) {
+ lines.push(`not in graph (${r.coverage.length}):`);
+ for (const p of r.coverage) lines.push(` + ${p}`);
+ }
+ if (r.indexDrift.length) {
+ lines.push(`index mismatch (${r.indexDrift.length}):`);
+ for (const s of r.indexDrift) lines.push(` ! ${s}`);
+ }
+ lines.push("", "Run `context-graph init` to regenerate, then commit .context/.");
+ return lines.join("\n");
+}
+
+function short(hash: string): string {
+ return hash.slice(0, 8);
+}
diff --git a/src/context/node-file.ts b/src/context/node-file.ts
new file mode 100644
index 00000000..bab14950
--- /dev/null
+++ b/src/context/node-file.ts
@@ -0,0 +1,227 @@
+/**
+ * The on-disk format of the context graph: a folder of plain markdown files
+ * under `.context/`, one per node. The files ARE the graph — the frontmatter
+ * carries the machine-readable node (identity, source provenance, edges) and
+ * the body is human/agent-readable prose. There is no database.
+ *
+ * Layout of a node file:
+ *
+ * --- ← YAML frontmatter (canonical, machine-owned)
+ * name / slug / type
+ * sources: [{path, hash}] ← provenance + the staleness key
+ * sources_digest
+ * links: [{to, relation}] ← edges (canonical form)
+ * ---
+ * <!-- context:generated:start -->
+ * ## Summary … ## Related … ← regenerated on every `init`
+ * <!-- context:generated:end -->
+ * ## Notes … ← anything a human writes is preserved verbatim
+ *
+ * `.context/manifest.json` is a generated index over all nodes plus the full
+ * file→hash map `init` saw, so `check` can detect drift in O(files) without an
+ * LLM and without re-reading every node body.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import matter from "gray-matter";
+import { contentHash, normalizeName } from "../util/id.js";
+
+/** A source file a node was derived from, with its content hash at generation time. */
+export interface SourceRef {
+ path: string;
+ hash: string;
+}
+
+/** A directed edge to another node (by slug). */
+export interface NodeLink {
+ to: string;
+ relation: string;
+ description?: string;
+}
+
+/** A single node in the graph — one markdown file. */
+export interface ContextNode {
+ name: string;
+ slug: string;
+ /** Coarse category from extraction: system | service | api | concept | … */
+ type: string;
+ /** Prose description that becomes the node body. */
+ summary: string;
+ /** Source files that produced this node (empty only for hand-authored nodes). */
+ sources: SourceRef[];
+ /** sha256 over the sorted `path:hash` lines of {@link sources}. */
+ sourcesDigest: string;
+ /** Outbound edges. */
+ links: NodeLink[];
+ /** Free-form region below the generated block, preserved across re-runs. */
+ human: string;
+}
+
+/** The generated index written alongside the node files. */
+export interface Manifest {
+ version: number;
+ /** Human label for the model that built the graph, e.g. "ollama:llama3.2". */
+ model: string;
+ /** sha256 over every source file's `path:hash` — the whole-graph fingerprint. */
+ repoDigest: string;
+ /** Every source file `init` processed, with its hash. The staleness ground-truth. */
+ files: SourceRef[];
+ /** Node roster (a subset of each node's frontmatter, for fast reads). */
+ nodes: Array<{ slug: string; name: string; type: string; sources: string[]; sourcesDigest: string }>;
+}
+
+export const MANIFEST_VERSION = 1;
+const GEN_START = "<!-- context:generated:start -->";
+const GEN_END = "<!-- context:generated:end -->";
+const MANIFEST_FILE = "manifest.json";
+/** Gitignored cache dir (per-file summaries + extractions), never committed. */
+export const CACHE_DIR = ".cache";
+
+/** Turn a display name into a stable, filesystem- and link-safe slug. */
+export function slugify(name: string): string {
+ const base = normalizeName(name)
+ .replace(/[^a-z0-9]+/g, "-")
+ .replace(/^-+|-+$/g, "");
+ return base || "node";
+}
+
+/** sha256 over the sorted `path:hash` lines of a set of sources. */
+export function digestSources(sources: SourceRef[]): string {
+ const lines = sources
+ .map((s) => `${s.path}:${s.hash}`)
+ .sort()
+ .join("\n");
+ return contentHash(lines);
+}
+
+/** Absolute path of the `.context/` directory for a repo root. */
+export function contextDirFor(root: string, override?: string): string {
+ if (override) return override;
+ return join(root, ".context");
+}
+
+/** Render the generated body (Summary + Related) for a node. */
+function renderGenerated(node: ContextNode): string {
+ const lines = [`## Summary`, ``, node.summary.trim() || "_(no summary)_", ``];
+ if (node.links.length > 0) {
+ lines.push(`## Related`, ``);
+ for (const link of [...node.links].sort((a, b) => a.to.localeCompare(b.to))) {
+ const rel = link.relation.replace(/_/g, " ");
+ const tail = link.description ? ` — ${link.description}` : "";
+ lines.push(`- ${rel} [[${link.to}]]${tail}`);
+ }
+ lines.push(``);
+ }
+ return lines.join("\n");
+}
+
+/** Default human region for a brand-new node (preserved verbatim afterwards). */
+function defaultHuman(): string {
+ return `\n## Notes\n\n_Anything written below the generated block is preserved when the graph is regenerated._\n`;
+}
+
+/** Serialize a node to its full markdown file contents. */
+export function renderNodeFile(node: ContextNode): string {
+ const data = {
+ name: node.name,
+ slug: node.slug,
+ type: node.type,
+ sources: node.sources.map((s) => ({ path: s.path, hash: s.hash })),
+ sources_digest: node.sourcesDigest,
+ links: node.links.map((l) =>
+ l.description ? { to: l.to, relation: l.relation, description: l.description } : { to: l.to, relation: l.relation },
+ ),
+ generator: { version: MANIFEST_VERSION },
+ };
+ const body = `${GEN_START}\n${renderGenerated(node)}${GEN_END}\n${node.human}`;
+ // gray-matter appends a trailing newline; keep output stable across runs.
+ return matter.stringify(body, data);
+}
+
+/**
+ * Extract the human region (everything after the generated-end marker) from an
+ * existing node file so it survives regeneration. If the markers are missing
+ * (a hand-deleted or foreign file), returns a fresh default region.
+ */
+function preserveHuman(existingContent: string): string {
+ const idx = existingContent.indexOf(GEN_END);
+ if (idx === -1) return defaultHuman();
+ return existingContent.slice(idx + GEN_END.length).replace(/^\n/, "");
+}
+
+/**
+ * Write a node file, preserving any existing human region. Returns the file
+ * path written.
+ */
+export function writeNode(dir: string, node: ContextNode): string {
+ mkdirSync(dir, { recursive: true });
+ const path = join(dir, `${node.slug}.md`);
+ if (existsSync(path)) {
+ const parsed = matter(readFileSync(path, "utf8"));
+ node = { ...node, human: preserveHuman(parsed.content) };
+ } else {
+ node = { ...node, human: node.human || defaultHuman() };
+ }
+ writeFileSync(path, renderNodeFile(node));
+ return path;
+}
+
+/** A node file parsed back off disk (frontmatter only; body is not needed for `check`). */
+export interface ParsedNode {
+ slug: string;
+ name: string;
+ type: string;
+ sources: SourceRef[];
+ sourcesDigest: string;
+ links: NodeLink[];
+}
+
+/** Read and parse every `.md` node file in a context dir (skips the manifest). */
+export function readNodes(dir: string): ParsedNode[] {
+ if (!existsSync(dir)) return [];
+ const out: ParsedNode[] = [];
+ for (const entry of readdirSync(dir)) {
+ if (!entry.endsWith(".md")) continue;
+ const fm = matter(readFileSync(join(dir, entry), "utf8")).data as Record<string, unknown>;
+ out.push({
+ slug: String(fm.slug ?? entry.replace(/\.md$/, "")),
+ name: String(fm.name ?? ""),
+ type: String(fm.type ?? ""),
+ sources: Array.isArray(fm.sources) ? (fm.sources as SourceRef[]) : [],
+ sourcesDigest: String(fm.sources_digest ?? ""),
+ links: Array.isArray(fm.links) ? (fm.links as NodeLink[]) : [],
+ });
+ }
+ return out;
+}
+
+/** List the node files present (slug → filename), for pruning deleted nodes. */
+export function existingNodeSlugs(dir: string): Set<string> {
+ if (!existsSync(dir)) return new Set();
+ return new Set(
+ readdirSync(dir)
+ .filter((e) => e.endsWith(".md"))
+ .map((e) => e.replace(/\.md$/, "")),
+ );
+}
+
+/** Delete a node file by slug. */
+export function deleteNode(dir: string, slug: string): void {
+ const path = join(dir, `${slug}.md`);
+ if (existsSync(path)) rmSync(path);
+}
+
+export function writeManifest(dir: string, manifest: Manifest): void {
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2) + "\n");
+}
+
+export function readManifest(dir: string): Manifest | undefined {
+ const path = join(dir, MANIFEST_FILE);
+ if (!existsSync(path)) return undefined;
+ try {
+ return JSON.parse(readFileSync(path, "utf8")) as Manifest;
+ } catch {
+ return undefined;
+ }
+}
diff --git a/src/engine.ts b/src/engine.ts
index 7a636dfd..ee8159a2 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -1,720 +1,87 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { extractPdfText, isPdfPath } from "./ingest/pdf.js";
-import { DOC_EXTENSIONS, walkDir } from "./ingest/fs.js";
-import { buildGraphExport, type GraphExport } from "./graph/export.js";
-import type { GraphStore } from "./graph/store.js";
-import { SqliteStore } from "./graph/sqlite-store.js";
-import type { Embedder, EngineConfig, Extractor, ResolvedConfig } from "./ai/providers.js";
-import { resolveConfig } from "./ai/providers.js";
-import { OpenRouterExtractor } from "./ai/openrouter.js";
-import { OpenAIEmbedder } from "./ai/openai.js";
-import { LocalEmbedder, OllamaExtractor } from "./ai/local.js";
-import { OllamaSummarizer, OpenRouterSummarizer, type Summarizer } from "./ai/summarize.js";
-import { chunkText } from "./ingest/chunker.js";
-import { mergeExtraction } from "./graph/merge.js";
-import { confidenceFromObservations, totalObservations } from "./graph/crdt.js";
-import { serializeGraph, importGraph, type ImportResult } from "./graph/serialize.js";
-import { retrieve, type RetrieveOptions } from "./retrieval/retriever.js";
-import type { ContextBundle, Chunk, Extraction, GraphStats } from "./graph/types.js";
-import { contentHash, newId } from "./util/id.js";
-
-export interface IngestOptions {
- /** Human-readable title for the document. Default: derived from source. */
- title?: string;
- /** Where the content came from (path, URL, label). Default: "inline". */
- source?: string;
-}
-
-export interface IngestResult {
- documentId: string;
- title: string;
- /** True if the document was already present (identical hash) and was skipped. */
- skipped: boolean;
- chunks: number;
- nodesCreated: number;
- nodesUpdated: number;
- edgesCreated: number;
- edgesUpdated: number;
-}
-
-export interface ContributeOptions {
- /** Identifier of the agent contributing the learning. Default: "agent". */
- agentId?: string;
- /** Optional label for where the learning came from (task id, session, …). */
- source?: string;
-}
-
-export interface ContributeResult {
- documentId: string;
- nodesCreated: number;
- nodesUpdated: number;
- edgesCreated: number;
- edgesUpdated: number;
-}
-
-/** Outcome of pruning stale observations (see {@link ContextGraphEngine.pruneDocuments}). */
-export interface PruneResult {
- /** Nodes deleted because their last supporting observation was removed. */
- nodesRemoved: number;
- /** Nodes that lost an observation but retained others (confidence re-derived). */
- nodesDecayed: number;
- /** Edges deleted because their last supporting observation was removed. */
- edgesRemoved: number;
- /** Edges that lost an observation but retained others. */
- edgesDecayed: number;
-}
+/**
+ * The Context Graph Engine.
+ *
+ * Two operations, no database:
+ * - {@link ContextGraphEngine.init} build `.context/` from a code repo.
+ * - {@link ContextGraphEngine.check} report whether `.context/` is still in
+ * sync with the code (for CI).
+ *
+ * The graph is a folder of linked markdown files committed to the repo; git is
+ * the sync. This class only wires the configured LLM providers (local Ollama by
+ * default, OpenRouter when a key is present) into the build/check pipelines.
+ */
+import { resolveConfig, type EngineConfig, type ResolvedConfig } from "./ai/providers.js";
+import { OpenRouterSynthesizer, OllamaSynthesizer, type Synthesizer } from "./ai/synthesize.js";
+import { OpenRouterSummarizer, OllamaSummarizer, type Summarizer } from "./ai/summarize.js";
+import { buildContext, CODE_EXTENSIONS, type BuildProgress, type BuildResult } from "./context/build.js";
+import { checkContext, type CheckResult } from "./context/check.js";
-/** Extensions treated as source code by {@link ContextGraphEngine.ingestRepo}. */
-export const CODE_EXTENSIONS = [
- ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
- ".py", ".go", ".rs", ".java", ".kt", ".scala",
- ".rb", ".php", ".c", ".h", ".cpp", ".hpp", ".cc",
- ".cs", ".swift", ".sql", ".sh", ".proto",
-];
+export { CODE_EXTENSIONS };
+export type { BuildResult, BuildProgress, CheckResult };
-export interface RepoIngestOptions {
- /** File extensions to treat as code. Default: {@link CODE_EXTENSIONS}. */
+export interface InitOptions {
+ /** Code extensions to include. Default: {@link CODE_EXTENSIONS}. */
extensions?: string[];
- /** Called before each file summary and each module ingest, for progress UIs. */
- onProgress?: (info: {
- phase: "summarize" | "ingest";
- index: number;
- total: number;
- file: string;
- }) => void;
-}
-
-export interface RepoIngestResult {
- /** Code files considered. */
- files: number;
- /** Files freshly summarized with an LLM call this run. */
- summarized: number;
- /** Files whose summary was reused from the content-hash cache. */
- cached: number;
- /** One ingest result per module (top-level directory) document. */
- modules: IngestResult[];
- /** Files that could not be read or summarized (path: reason). */
- errors: string[];
+ /** Progress callback for long builds. */
+ onProgress?: (info: BuildProgress) => void;
}
-/** file path → { content hash, cached summary } */
-type RepoSummaryCache = Record<string, { hash: string; summary: string }>;
-
-/** A folder registered for auto-watching (see `context-graph watch`). */
-export interface WatchedDir {
- /** Absolute path of the watched directory. */
- dir: string;
- /** Extensions to ingest; undefined means {@link DOC_EXTENSIONS}. */
+export interface CheckRunOptions {
extensions?: string[];
- /** ISO timestamp of when the folder was first registered. */
- addedAt: string;
}
-/** absolute dir → registry entry (persisted as watched-dirs.json next to the db) */
-type WatchRegistry = Record<string, { extensions?: string[]; addedAt: string }>;
-
-/**
- * The Context Graph Engine.
- *
- * Turn documents into a structured knowledge graph ({@link ingest}), let agents
- * read relevant context before doing work ({@link read}), and let them
- * contribute learnings back so the graph improves over time ({@link contribute}).
- */
export class ContextGraphEngine {
private cfg: ResolvedConfig;
- private _store?: GraphStore;
- private _embedder?: Embedder;
- private _extractor?: Extractor;
- private _summarizer?: Summarizer;
- private _memRepoCache: RepoSummaryCache = {};
- private _memWatchRegistry: WatchRegistry = {};
constructor(config: EngineConfig = {}) {
this.cfg = resolveConfig(config);
}
- /** The underlying graph store (lazily opened): an explicit `store` override, or the local SQLite file. */
- get store(): GraphStore {
- if (!this._store) {
- this._store = this.cfg.store ?? new SqliteStore(this.cfg.dbPath);
- }
- return this._store;
- }
-
- private get embedder(): Embedder {
- if (!this._embedder) {
- if (this.cfg.embedder) {
- // Explicit override wins.
- this._embedder = this.cfg.embedder;
- } else if (!this.cfg.forceLocal && this.cfg.openaiApiKey) {
- // Use cloud embeddings when a key is available.
- this._embedder = new OpenAIEmbedder(this.cfg.openaiApiKey, this.cfg.embeddingModel);
- } else {
- // Fall back to fully-local, in-process embeddings (no key required).
- this._embedder = new LocalEmbedder(this.cfg.localEmbeddingModel);
- }
- }
- return this._embedder;
- }
-
- private get extractor(): Extractor {
- if (!this._extractor) {
- if (this.cfg.extractor) {
- // Explicit override wins.
- this._extractor = this.cfg.extractor;
- } else if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) {
- // Use OpenRouter for extraction when a key is available.
- this._extractor = new OpenRouterExtractor(
- this.cfg.openrouterApiKey,
- this.cfg.openrouterModel,
- this.cfg.openrouterBaseUrl,
- );
- } else {
- // Fall back to local extraction via a running Ollama instance.
- this._extractor = new OllamaExtractor(this.cfg.ollamaModel, this.cfg.ollamaBaseUrl);
- }
- }
- return this._extractor;
- }
-
- private get summarizer(): Summarizer {
- if (!this._summarizer) {
- if (this.cfg.summarizer) {
- this._summarizer = this.cfg.summarizer;
- } else if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) {
- this._summarizer = new OpenRouterSummarizer(
- this.cfg.openrouterApiKey,
- this.cfg.openrouterModel,
- this.cfg.openrouterBaseUrl,
- );
- } else {
- this._summarizer = new OllamaSummarizer(this.cfg.ollamaModel, this.cfg.ollamaBaseUrl);
- }
- }
- return this._summarizer;
+ /** Build the `.context/` graph from the repo at `dir`. */
+ async init(dir: string, opts: InitOptions = {}): Promise<BuildResult> {
+ return buildContext(dir, {
+ contextDir: this.cfg.contextDir,
+ extensions: opts.extensions,
+ model: this.modelLabel(),
+ summarizer: this.summarizer(),
+ synthesizer: this.synthesizer(),
+ onProgress: opts.onProgress,
+ });
}
- /**
- * Ingest a document from disk. PDFs (`.pdf`) are parsed to text automatically;
- * anything else is read as UTF-8. Title defaults to the file name.
- */
- async ingestFile(path: string, opts: IngestOptions = {}): Promise<IngestResult> {
- const text = isPdfPath(path) ? await extractPdfText(path) : readFileSync(path, "utf8");
- return this.ingest(text, { title: opts.title ?? basename(path), source: opts.source ?? path });
+ /** Report whether the committed graph is still in sync with the code. */
+ check(dir: string, opts: CheckRunOptions = {}): CheckResult {
+ return checkContext(dir, { contextDir: this.cfg.contextDir, extensions: opts.extensions });
}
- /** Ingest raw text: chunk it, extract entities/relations, and merge into the graph. */
- async ingest(text: string, opts: IngestOptions = {}): Promise<IngestResult> {
- const now = new Date().toISOString();
- const source = opts.source ?? "inline";
- const title = opts.title ?? source;
- const hash = contentHash(text);
-
- const existing = await this.store.getDocumentByHash(hash);
- if (existing) {
- return {
- documentId: existing.id,
- title: existing.title,
- skipped: true,
- chunks: 0,
- nodesCreated: 0,
- nodesUpdated: 0,
- edgesCreated: 0,
- edgesUpdated: 0,
- };
- }
-
- // Same source, new content: the file changed, so replace its stale
- // document(s) instead of piling up superseded chunks. "inline" is the
- // catch-all source for pasted text and is exempt — many unrelated
- // documents legitimately share it. The prior ids are remembered so their
- // observations can be pruned after the new content merges in (below).
- const supersededIds: string[] = [];
- if (source !== "inline") {
- for (const prior of await this.store.documentsBySource(source)) {
- supersededIds.push(prior.id);
- await this.store.deleteDocument(prior.id);
- }
- }
-
- const documentId = newId("doc");
- await this.store.insertDocument({ id: documentId, title, source, hash, createdAt: now });
-
- const pieces = chunkText(text, this.cfg.chunkSize, this.cfg.chunkOverlap);
- const embeddings = await this.embedder.embed(pieces);
- for (let i = 0; i < pieces.length; i++) {
- const chunk: Chunk = {
- id: newId("chunk"),
- documentId,
- ordinal: i,
- text: pieces[i],
- embedding: embeddings[i],
- createdAt: now,
- };
- await this.store.insertChunk(chunk);
- }
-
- // Extract per chunk (parallel, bounded), then merge sequentially so each
- // merge sees nodes created by earlier chunks. The document id is a unique
- // observation key, so re-importing this document later never double-counts.
- const extractions = await mapWithConcurrency(pieces, 4, (piece) =>
- this.extractor.extract(piece, { hint: title }),
- );
-
- const provenance = `doc:${documentId}`;
- const totals = { nodesCreated: 0, nodesUpdated: 0, edgesCreated: 0, edgesUpdated: 0 };
- for (const extraction of extractions) {
- const r = await mergeExtraction(
- this.store,
- this.embedder,
- extraction,
- provenance,
- provenance,
- this.cfg.mergeThreshold,
- now,
+ private synthesizer(): Synthesizer {
+ if (this.cfg.synthesizer) return this.cfg.synthesizer;
+ if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) {
+ return new OpenRouterSynthesizer(
+ this.cfg.openrouterApiKey,
+ this.cfg.openrouterModel,
+ this.cfg.openrouterBaseUrl,
);
- totals.nodesCreated += r.nodesCreated;
- totals.nodesUpdated += r.nodesUpdated;
- totals.edgesCreated += r.edgesCreated;
- totals.edgesUpdated += r.edgesUpdated;
- }
-
- // Now that the new version has re-observed everything it still asserts,
- // retire the superseded version's observations. Facts present in both
- // versions keep the fresh observation; facts that vanished lose their last
- // support and are pruned. Runs after the merge so a fact never briefly
- // drops to zero observations mid-update.
- if (this.cfg.pruneSuperseded && supersededIds.length > 0) {
- await this.pruneDocuments(supersededIds);
- }
-
- return { documentId, title, skipped: false, chunks: pieces.length, ...totals };
- }
-
- /**
- * Ingest every supported document in a directory (recursively). Supported
- * extensions: .pdf, .md, .markdown, .txt. Returns one result per file.
- *
- * `onProgress` is invoked before each file starts (so callers can report
- * progress on long, multi-file ingests — e.g. to keep an MCP client's request
- * timeout from firing).
- */
- async ingestDir(
- dir: string,
- opts: {
- extensions?: string[];
- onProgress?: (info: { index: number; total: number; file: string }) => void;
- } = {},
- ): Promise<IngestResult[]> {
- const exts = opts.extensions ?? DOC_EXTENSIONS;
- const files = walkDir(dir).filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)));
- const results: IngestResult[] = [];
- for (let i = 0; i < files.length; i++) {
- opts.onProgress?.({ index: i, total: files.length, file: files[i] });
- results.push(await this.ingestFile(files[i]));
}
- return results;
+ return new OllamaSynthesizer(this.cfg.ollamaModel, this.cfg.ollamaBaseUrl);
}
- /**
- * Ingest a code repository as **summaries, not raw code**.
- *
- * Raw source is deliberately kept out of the extraction pipeline (LLM entity
- * extraction over code is noisy and expensive; agents already grep code
- * live). Instead each code file gets one LLM-written prose summary; the
- * summaries are grouped into one document per top-level directory and fed
- * through the normal {@link ingest} pipeline.
- *
- * Incremental: summaries are cached by file content hash (in
- * `repo-summaries.json` next to the db), so re-running after edits only
- * re-summarizes changed files, and unchanged module documents are skipped by
- * the ordinary document-hash dedup.
- */
- async ingestRepo(dir: string, opts: RepoIngestOptions = {}): Promise<RepoIngestResult> {
- const root = resolve(dir);
- const exts = opts.extensions ?? CODE_EXTENSIONS;
- const files = walkDir(root).filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)));
-
- const cache = this.loadRepoCache();
- const result: RepoIngestResult = {
- files: files.length,
- summarized: 0,
- cached: 0,
- modules: [],
- errors: [],
- };
-
- // Phase 1: one summary per file, concurrent, content-hash cached.
- const summaries = await mapWithConcurrency(files, 8, async (file, i) => {
- const rel = relative(root, file);
- opts.onProgress?.({ phase: "summarize", index: i, total: files.length, file: rel });
- let code: string;
- try {
- code = readFileSync(file, "utf8");
- } catch (err) {
- result.errors.push(`${rel}: ${err instanceof Error ? err.message : String(err)}`);
- return undefined;
- }
- const hash = contentHash(code);
- const hit = cache[file];
- if (hit && hit.hash === hash) {
- result.cached++;
- return { rel, summary: hit.summary };
- }
- try {
- const summary = await this.summarizer.summarize(code, { path: rel });
- if (!summary) return undefined;
- cache[file] = { hash, summary };
- result.summarized++;
- return { rel, summary };
- } catch (err) {
- result.errors.push(`${rel}: ${err instanceof Error ? err.message : String(err)}`);
- return undefined;
- }
- });
- this.saveRepoCache(cache);
-
- // Phase 2: group summaries into one document per top-level directory and
- // run them through the normal ingest pipeline. The stable `repo:` source
- // makes re-ingestion replace a module's stale document when it changed.
- const repoName = basename(root);
- const modules = new Map<string, Array<{ rel: string; summary: string }>>();
- for (const s of summaries) {
- if (!s) continue;
- const module = s.rel.includes(sep) ? s.rel.split(sep)[0] : "(root)";
- (modules.get(module) ?? modules.set(module, []).get(module)!).push(s);
- }
-
- let i = 0;
- for (const [module, entries] of modules) {
- opts.onProgress?.({ phase: "ingest", index: i++, total: modules.size, file: module });
- const text = [
- `# Code summary: ${repoName}/${module}`,
- ...entries.map((e) => `## ${e.rel}\n\n${e.summary}`),
- ].join("\n\n");
- result.modules.push(
- await this.ingest(text, {
- title: `${repoName}/${module} (code summary)`,
- source: `repo:${root}#${module}`,
- }),
+ private summarizer(): Summarizer {
+ if (this.cfg.summarizer) return this.cfg.summarizer;
+ if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) {
+ return new OpenRouterSummarizer(
+ this.cfg.openrouterApiKey,
+ this.cfg.openrouterModel,
+ this.cfg.openrouterBaseUrl,
);
}
- return result;
- }
-
- /** Path of the watch registry, or undefined for in-memory graphs. */
- private get watchRegistryPath(): string | undefined {
- if (this.cfg.dbPath === ":memory:") return undefined;
- return join(dirname(this.cfg.dbPath), "watched-dirs.json");
- }
-
- private loadWatchRegistry(): WatchRegistry {
- const path = this.watchRegistryPath;
- if (!path) return this._memWatchRegistry;
- if (!existsSync(path)) return {};
- try {
- return JSON.parse(readFileSync(path, "utf8")) as WatchRegistry;
- } catch {
- return {};
- }
- }
-
- private saveWatchRegistry(registry: WatchRegistry): void {
- const path = this.watchRegistryPath;
- if (!path) {
- this._memWatchRegistry = registry;
- return;
- }
- mkdirSync(dirname(path), { recursive: true });
- writeFileSync(path, JSON.stringify(registry, null, 2));
- }
-
- /** Folders registered for auto-watching, in registration order. */
- listWatchedDirs(): WatchedDir[] {
- return Object.entries(this.loadWatchRegistry()).map(([dir, entry]) => ({ dir, ...entry }));
- }
-
- /**
- * Register a folder for auto-watching (see `context-graph watch`). The
- * registry lives in `watched-dirs.json` next to the db — machine-local
- * paths deliberately stay out of the git-synced graph. Idempotent; the
- * extensions of an existing entry are updated in place.
- */
- addWatchedDir(dir: string, extensions?: string[]): WatchedDir {
- const abs = resolve(dir);
- const registry = this.loadWatchRegistry();
- const entry = {
- extensions: extensions ?? registry[abs]?.extensions,
- addedAt: registry[abs]?.addedAt ?? new Date().toISOString(),
- };
- registry[abs] = entry;
- this.saveWatchRegistry(registry);
- return { dir: abs, ...entry };
- }
-
- /** Unregister a watched folder. Returns false if it wasn't registered. */
- removeWatchedDir(dir: string): boolean {
- const abs = resolve(dir);
- const registry = this.loadWatchRegistry();
- if (!(abs in registry)) return false;
- delete registry[abs];
- this.saveWatchRegistry(registry);
- return true;
- }
-
- /** Path of the file-summary cache, or undefined for in-memory graphs. */
- private get repoCachePath(): string | undefined {
- if (this.cfg.dbPath === ":memory:") return undefined;
- return join(dirname(this.cfg.dbPath), "repo-summaries.json");
- }
-
- private loadRepoCache(): RepoSummaryCache {
- const path = this.repoCachePath;
- if (!path) return this._memRepoCache;
- if (!existsSync(path)) return {};
- try {
- return JSON.parse(readFileSync(path, "utf8")) as RepoSummaryCache;
- } catch {
- return {};
- }
- }
-
- private saveRepoCache(cache: RepoSummaryCache): void {
- const path = this.repoCachePath;
- if (!path) {
- this._memRepoCache = cache;
- return;
- }
- mkdirSync(dirname(path), { recursive: true });
- writeFileSync(path, JSON.stringify(cache, null, 2));
- }
-
- /** Read the graph for a query, returning a structured context bundle. */
- async read(query: string, opts: RetrieveOptions = {}): Promise<ContextBundle> {
- return retrieve(this.store, this.embedder, query, opts);
- }
-
- /** A serializable snapshot of the whole graph, for export/visualization. */
- async exportGraph(): Promise<GraphExport> {
- return buildGraphExport(this.store);
- }
-
- /**
- * Default path for the git-committed graph file (Mode A), alongside the db
- * file — e.g. `.context-graph/graph.jsonl` next to `.context-graph/graph.db`.
- * Undefined for an in-memory graph.
- */
- get graphFilePath(): string | undefined {
- if (this.cfg.dbPath === ":memory:") return undefined;
- return join(dirname(this.cfg.dbPath), "graph.jsonl");
- }
-
- /** Human label for the active embedding model, recorded in exported files. */
- private embeddingModelLabel(): string {
- if (!this.cfg.forceLocal && this.cfg.openaiApiKey) return this.cfg.embeddingModel;
- return this.cfg.localEmbeddingModel;
- }
-
- /**
- * Serialize the whole graph to a JSONL string for git-native team sync
- * (Mode A). Commit the result; teammates {@link importJsonl} it after a pull.
- */
- async exportJsonl(): Promise<string> {
- return serializeGraph(this.store, {
- embeddingDimensions: this.embedder.dimensions,
- embeddingModel: this.embeddingModelLabel(),
- });
- }
-
- /**
- * Import a serialized graph (from a teammate's commit) and CRDT-merge it into
- * the local graph. Idempotent — re-importing the same content is a no-op.
- */
- async importJsonl(jsonl: string): Promise<ImportResult> {
- return importGraph(this.store, jsonl, this.embedder.dimensions);
- }
-
- /**
- * Contribute a learning discovered by an agent. The text is stored as
- * retrievable evidence and its entities/relations are merged into the graph,
- * reinforcing what is already known and adding what is new.
- */
- async contribute(learning: string, opts: ContributeOptions = {}): Promise<ContributeResult> {
- const now = new Date().toISOString();
- const agentId = opts.agentId ?? "agent";
- const provenance = `agent:${agentId}`;
- const title = `Learning from ${agentId}: ${learning.slice(0, 60)}${learning.length > 60 ? "…" : ""}`;
- const hash = contentHash(`${provenance}|${learning}`);
-
- let documentId: string;
- const existing = await this.store.getDocumentByHash(hash);
- if (existing) {
- documentId = existing.id;
- } else {
- documentId = newId("doc");
- await this.store.insertDocument({
- id: documentId,
- title,
- source: opts.source ?? provenance,
- hash,
- createdAt: now,
- });
- const [embedding] = await this.embedder.embed([learning]);
- await this.store.insertChunk({
- id: newId("chunk"),
- documentId,
- ordinal: 0,
- text: learning,
- embedding,
- createdAt: now,
- });
- }
-
- const extraction: Extraction = await this.extractor.extract(learning, {
- hint: "An agent's learning to fold into the shared knowledge graph.",
- });
- // `agent:<id>` is the human-facing origin; the (unique) contribution
- // document id is the observation key, so replays stay idempotent.
- const r = await mergeExtraction(
- this.store,
- this.embedder,
- extraction,
- provenance,
- `doc:${documentId}`,
- this.cfg.mergeThreshold,
- now,
- );
-
- return {
- documentId,
- nodesCreated: r.nodesCreated,
- nodesUpdated: r.nodesUpdated,
- edgesCreated: r.edgesCreated,
- edgesUpdated: r.edgesUpdated,
- };
- }
-
- /**
- * Prune the observations contributed by one or more documents.
- *
- * For every node and edge, the given documents' observation keys are removed
- * from the grow-only CRDT counter and provenance set, and `observations` /
- * `confidence` are re-derived from what remains. A node or edge left with no
- * supporting observation is deleted entirely (deleting a node cascades to its
- * incident edges). Observations from *other* documents and from agent
- * contributions are untouched — so a fact seen in several places survives the
- * loss of any one of them.
- *
- * This is the counterpart to the grow-only merge: the deliberate, local
- * write path that lets stale knowledge leave the graph.
- */
- async pruneDocuments(documentIds: string[]): Promise<PruneResult> {
- const keys = new Set(documentIds.map((id) => `doc:${id}`));
- const result: PruneResult = { nodesRemoved: 0, nodesDecayed: 0, edgesRemoved: 0, edgesDecayed: 0 };
- if (keys.size === 0) return result;
-
- // Nodes first. An orphaned node is removed, which cascades to its incident
- // edges via the store's foreign keys — so we record those edge ids up front
- // to count them, then let the cascade do the deletion.
- const orphanedNodeIds: string[] = [];
- for (const node of await this.store.allNodes()) {
- let touched = false;
- for (const key of keys) {
- if (key in node.observationSources) {
- delete node.observationSources[key];
- touched = true;
- }
- }
- if (!touched) continue;
- node.provenance = node.provenance.filter((p) => !keys.has(p));
- const total = totalObservations(node.observationSources);
- if (total <= 0) {
- orphanedNodeIds.push(node.id);
- } else {
- node.observations = total;
- node.confidence = confidenceFromObservations(total);
- await this.store.upsertNode(node);
- result.nodesDecayed += 1;
- }
- }
-
- // Edges that will vanish with their endpoints, counted before the cascade.
- const cascadedEdgeIds = new Set(
- orphanedNodeIds.length > 0
- ? (await this.store.edgesForNodes(orphanedNodeIds)).map((e) => e.id)
- : [],
- );
- for (const id of orphanedNodeIds) await this.store.deleteNode(id);
- result.nodesRemoved += orphanedNodeIds.length;
- result.edgesRemoved += cascadedEdgeIds.size;
-
- // Surviving edges that themselves lost their last observation. (Edges that
- // already cascaded above are gone from the store and won't reappear here.)
- for (const edge of await this.store.allEdges()) {
- let touched = false;
- for (const key of keys) {
- if (key in edge.observationSources) {
- delete edge.observationSources[key];
- touched = true;
- }
- }
- if (!touched) continue;
- edge.provenance = edge.provenance.filter((p) => !keys.has(p));
- const total = totalObservations(edge.observationSources);
- if (total <= 0) {
- await this.store.deleteEdge(edge.id);
- result.edgesRemoved += 1;
- } else {
- edge.observations = total;
- edge.confidence = confidenceFromObservations(total);
- await this.store.upsertEdge(edge);
- result.edgesDecayed += 1;
- }
- }
-
- return result;
+ return new OllamaSummarizer(this.cfg.ollamaModel, this.cfg.ollamaBaseUrl);
}
- /**
- * Forget a source that no longer exists (e.g. a watched file was deleted):
- * delete its document(s) and prune the observations they contributed. Returns
- * the prune result plus how many documents were removed. A source with no
- * documents is a no-op.
- */
- async forgetSource(source: string): Promise<PruneResult & { documentsRemoved: number }> {
- const docs = await this.store.documentsBySource(source);
- const ids = docs.map((d) => d.id);
- for (const id of ids) await this.store.deleteDocument(id);
- const pruned = await this.pruneDocuments(ids);
- return { ...pruned, documentsRemoved: ids.length };
+ /** Human label for the active model, recorded in the manifest. */
+ private modelLabel(): string {
+ if (this.cfg.synthesizer || this.cfg.summarizer) return "custom";
+ if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) return `openrouter:${this.cfg.openrouterModel}`;
+ return `ollama:${this.cfg.ollamaModel}`;
}
-
- /** Current graph statistics. */
- async stats(): Promise<GraphStats> {
- return this.store.stats();
- }
-
- /** Close the underlying store. */
- async close(): Promise<void> {
- await this._store?.close();
- }
-}
-
-/** Run `fn` over `items` with at most `limit` in flight at once, preserving order. */
-async function mapWithConcurrency<T, R>(
- items: T[],
- limit: number,
- fn: (item: T, index: number) => Promise<R>,
-): Promise<R[]> {
- const results: R[] = new Array(items.length);
- let next = 0;
- const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
- while (next < items.length) {
- const i = next++;
- results[i] = await fn(items[i], i);
- }
- });
- await Promise.all(workers);
- return results;
}
diff --git a/src/graph/crdt.ts b/src/graph/crdt.ts
deleted file mode 100644
index 42c01db6..00000000
--- a/src/graph/crdt.ts
+++ /dev/null
@@ -1,78 +0,0 @@
-/**
- * Conflict-free primitives that make the graph safe to merge across replicas.
- *
- * The whole point: two teammates can build the graph independently (offline, on
- * different machines) and later reconcile it — via a git pull of a serialized
- * graph, or an embedded-replica sync — **without** double-counting reinforcement
- * or letting merge order change the result.
- *
- * Two ideas do the heavy lifting:
- *
- * 1. **Observations are a grow-only counter (G-Counter).** Each observation
- * event has a globally-unique key (the id of the document/contribution that
- * produced it). Merging two counters is an element-wise `max`, which is
- * commutative, associative and *idempotent* — replaying the same record is a
- * no-op. `observations` (the scalar) and `confidence` are then *derived*
- * from the counter, never mutated in place.
- *
- * 2. **Free-text fields (summary/description) are last-writer-wins registers**
- * keyed by a wall-clock stamp, with deterministic tiebreaks so every replica
- * picks the same winner.
- */
-import type { ObservationCounter } from "./types.js";
-
-/**
- * Confidence as a pure function of the observation total. Reproduces the
- * original reinforcement curve exactly — a fresh single observation is 0.6, and
- * each further observation closes 20% of the gap to 1 (0.6 → 0.68 → 0.744 → …),
- * capped at 0.99 — but as a *derivation* rather than a mutated register, so it
- * converges no matter how or how often records are merged.
- */
-export function confidenceFromObservations(total: number): number {
- if (total <= 0) return 0.5;
- return Math.min(0.99, 1 - 0.4 * Math.pow(0.8, total - 1));
-}
-
-/** Sum of a G-Counter's per-source counts (the total observation count). */
-export function totalObservations(sources: ObservationCounter): number {
- let n = 0;
- for (const key in sources) n += sources[key];
- return n;
-}
-
-/** Increment (in place) the count for one observation key. */
-export function bumpObservation(sources: ObservationCounter, key: string, by = 1): void {
- sources[key] = (sources[key] ?? 0) + by;
-}
-
-/**
- * Merge two G-Counters by element-wise max. Commutative, associative, and
- * idempotent — the mathematical guarantee behind replay-safe imports.
- */
-export function mergeObservationCounters(
- a: ObservationCounter,
- b: ObservationCounter,
-): ObservationCounter {
- const out: ObservationCounter = { ...a };
- for (const key in b) out[key] = Math.max(out[key] ?? 0, b[key]);
- return out;
-}
-
-/** Set-union of two grow-only string sets (dropping empties), order-stable. */
-export function unionSet(a: string[], b: string[]): string[] {
- return [...new Set([...a, ...b].filter((v) => v && v.length > 0))];
-}
-
-/**
- * Last-writer-wins pick between two timestamped text values. The newer stamp
- * wins; ties break toward the longer (more informative) text, then lexically —
- * so all replicas converge on the same choice regardless of merge order.
- */
-export function pickLatestText(
- a: { text: string; at: string },
- b: { text: string; at: string },
-): { text: string; at: string } {
- if (a.at !== b.at) return a.at > b.at ? a : b;
- if (a.text.length !== b.text.length) return a.text.length > b.text.length ? a : b;
- return a.text >= b.text ? a : b;
-}
diff --git a/src/graph/export.ts b/src/graph/export.ts
deleted file mode 100644
index 51f13c69..00000000
--- a/src/graph/export.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import type { GraphStore } from "./store.js";
-import type { GraphEdge, GraphNode } from "./types.js";
-
-/** A plain, serializable snapshot of the whole graph. */
-export interface GraphExport {
- nodes: Array<Pick<GraphNode, "id" | "name" | "type" | "summary" | "confidence" | "observations">>;
- edges: Array<Pick<GraphEdge, "sourceId" | "targetId" | "relation" | "description" | "confidence">>;
-}
-
-/** Read the entire graph out of a store into a serializable snapshot. */
-export async function buildGraphExport(store: GraphStore): Promise<GraphExport> {
- const nodes = (await store.allNodes()).map((n) => ({
- id: n.id,
- name: n.name,
- type: n.type,
- summary: n.summary,
- confidence: n.confidence,
- observations: n.observations,
- }));
- const edges = (await store.allEdges()).map((e) => ({
- sourceId: e.sourceId,
- targetId: e.targetId,
- relation: e.relation,
- description: e.description,
- confidence: e.confidence,
- }));
- return { nodes, edges };
-}
-
-/** Render the graph as a Mermaid `graph LR` definition (handy for docs/markdown). */
-export function toMermaid(g: GraphExport): string {
- const safe = (id: string) => id.replace(/[^a-zA-Z0-9_]/g, "_");
- const lines = ["graph LR"];
- for (const n of g.nodes) {
- lines.push(` ${safe(n.id)}["${n.name.replace(/"/g, "'")} (${n.type})"]`);
- }
- for (const e of g.edges) {
- lines.push(` ${safe(e.sourceId)} -->|${e.relation}| ${safe(e.targetId)}`);
- }
- return lines.join("\n");
-}
-
-/**
- * Render the graph as a self-contained, interactive HTML page.
- *
- * Uses vis-network (loaded from a CDN) for a draggable/zoomable force layout —
- * the graph data itself is embedded inline, so the only network dependency is
- * the viz library. Nodes are colored by type and sized by observation count.
- */
-export function toHtml(g: GraphExport, title = "Context Graph"): string {
- // Graph fields are LLM-extracted from arbitrary ingested documents, so treat
- // them as untrusted: escape text interpolated into HTML, and neutralize "<"
- // in the inline JSON so a "</script>" inside a summary can't break out.
- const esc = (s: string): string =>
- String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] as string);
- const jsonSafe = (v: unknown): string => JSON.stringify(v).replace(/</g, "\\u003c");
-
- const palette = [
- "#4f46e5", "#0891b2", "#059669", "#d97706", "#dc2626",
- "#7c3aed", "#db2777", "#65a30d", "#0284c7", "#ca8a04",
- ];
- const types = [...new Set(g.nodes.map((n) => n.type))];
- const colorFor = (t: string) => palette[types.indexOf(t) % palette.length];
-
- const nodes = g.nodes.map((n) => ({
- id: n.id,
- label: n.name,
- title: `${n.name} (${n.type})\nconfidence ${Math.round(n.confidence * 100)}% · ${n.observations} observation(s)\n${n.summary}`,
- group: n.type,
- value: n.observations,
- color: colorFor(n.type),
- }));
- const edges = g.edges.map((e) => ({
- from: e.sourceId,
- to: e.targetId,
- label: e.relation,
- title: e.description || e.relation,
- width: 1 + e.confidence * 2,
- }));
-
- const legend = types
- .map((t) => `<span class="chip"><i style="background:${colorFor(t)}"></i>${esc(t)}</span>`)
- .join("");
-
- return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>${esc(title)}</title>
-<script src="https://unpkg.com/[email protected]/standalone/umd/vis-network.min.js"
- integrity="sha384-yxKDWWf0wwdUj/gPeuL11czrnKFQROnLgY8ll7En9NYoXibgg3C6NK/UDHNtUgWJ"
- crossorigin="anonymous"></script>
-<style>
- :root { color-scheme: light dark; }
- body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
- header { padding: 12px 16px; border-bottom: 1px solid #8883; }
- h1 { font-size: 16px; margin: 0 0 6px; }
- .meta { font-size: 12px; opacity: 0.7; }
- .legend { margin-top: 8px; display: flex; flex-wrap: wrap; gap: 8px; }
- .chip { font-size: 11px; display: inline-flex; align-items: center; gap: 4px; }
- .chip i { width: 10px; height: 10px; border-radius: 50%; display: inline-block; }
- #graph { width: 100vw; height: calc(100vh - 92px); }
-</style>
-</head>
-<body>
-<header>
- <h1>${esc(title)}</h1>
- <div class="meta">${g.nodes.length} entities · ${g.edges.length} relationships</div>
- <div class="legend">${legend}</div>
-</header>
-<div id="graph"></div>
-<script>
- const nodes = new vis.DataSet(${jsonSafe(nodes)});
- const edges = new vis.DataSet(${jsonSafe(edges)});
- new vis.Network(document.getElementById("graph"), { nodes, edges }, {
- nodes: { shape: "dot", scaling: { min: 8, max: 32 }, font: { size: 14 } },
- edges: { arrows: "to", font: { size: 10, align: "middle" }, color: { opacity: 0.5 }, smooth: { type: "dynamic" } },
- physics: { stabilization: true, barnesHut: { gravitationalConstant: -8000, springLength: 140 } },
- interaction: { hover: true, tooltipDelay: 120 },
- });
-</script>
-</body>
-</html>`;
-}
diff --git a/src/graph/merge.ts b/src/graph/merge.ts
deleted file mode 100644
index 67e3d091..00000000
--- a/src/graph/merge.ts
+++ /dev/null
@@ -1,268 +0,0 @@
-import type { GraphStore } from "./store.js";
-import type { Embedder } from "../ai/providers.js";
-import type {
- Extraction,
- GraphEdge,
- GraphNode,
-} from "./types.js";
-import { newId, normalizeName } from "../util/id.js";
-import { cosineSimilarity } from "../util/similarity.js";
-import {
- bumpObservation,
- confidenceFromObservations,
- mergeObservationCounters,
- pickLatestText,
- totalObservations,
- unionSet,
-} from "./crdt.js";
-
-/** Pick the more informative of two summaries (prefers the longer, richer one). */
-function betterSummary(existing: string, incoming: string): string {
- if (!existing) return incoming;
- if (!incoming) return existing;
- return incoming.length > existing.length * 1.2 ? incoming : existing;
-}
-
-export interface MergeResult {
- nodesCreated: number;
- nodesUpdated: number;
- edgesCreated: number;
- edgesUpdated: number;
- /** Maps normalized entity name -> node id, so callers can link chunks/edges. */
- nameToId: Map<string, string>;
-}
-
-/**
- * Merge an {@link Extraction} into the graph (the *live* write path used by
- * ingest/contribute).
- *
- * Entities are matched against existing nodes by (a) exact normalized name /
- * alias and (b) embedding similarity above `mergeThreshold`. A match records a
- * fresh observation under `observationKey` (a bump of the CRDT counter);
- * confidence is then *derived* from the new total, never mutated directly.
- * Non-matches are created. Relations are linked between resolved node ids,
- * deduped by (source, target, relation).
- *
- * @param provenance Human-facing origin label added to the grow-only set
- * (e.g. `doc:<id>` or `agent:<id>`).
- * @param observationKey Globally-unique key for *this* observation event
- * (the document/contribution id), so re-observing the
- * same event later is idempotent under counter merge.
- */
-export async function mergeExtraction(
- store: GraphStore,
- embedder: Embedder,
- extraction: Extraction,
- provenance: string,
- observationKey: string,
- mergeThreshold: number,
- now: string,
-): Promise<MergeResult> {
- const result: MergeResult = {
- nodesCreated: 0,
- nodesUpdated: 0,
- edgesCreated: 0,
- edgesUpdated: 0,
- nameToId: new Map(),
- };
-
- const entities = extraction.entities;
- if (entities.length > 0) {
- // Embed all incoming entities in one batch.
- const embedInputs = entities.map((e) => `${e.name}: ${e.summary}`);
- const embeddings = await embedder.embed(embedInputs);
-
- // Cache the full embedded-node set once; refresh with nodes we create so
- // duplicates *within this same extraction* also collapse.
- const candidatePool = await store.allEmbeddedNodes();
-
- for (let i = 0; i < entities.length; i++) {
- const ent = entities[i];
- const embedding = embeddings[i];
- const norm = normalizeName(ent.name);
- const aliases = unionSet([norm], (ent.aliases ?? []).map(normalizeName));
-
- const match = await findMatch(store, candidatePool, norm, aliases, embedding, mergeThreshold);
-
- if (match) {
- const summary = betterSummary(match.summary, ent.summary);
- if (summary !== match.summary) {
- match.summary = summary;
- match.summaryUpdatedAt = now;
- }
- match.aliases = unionSet(match.aliases, [...aliases, norm]);
- bumpObservation(match.observationSources, observationKey);
- match.observations = totalObservations(match.observationSources);
- match.confidence = confidenceFromObservations(match.observations);
- match.provenance = unionSet(match.provenance, [provenance]);
- match.embedding = embedding;
- match.updatedAt = now;
- await store.upsertNode(match);
- result.nameToId.set(norm, match.id);
- result.nodesUpdated += 1;
- } else {
- const node: GraphNode = {
- id: newId("node"),
- name: ent.name,
- type: ent.type,
- summary: ent.summary,
- summaryUpdatedAt: now,
- aliases,
- confidence: confidenceFromObservations(1),
- observations: 1,
- observationSources: { [observationKey]: 1 },
- embedding,
- provenance: [provenance],
- createdAt: now,
- updatedAt: now,
- };
- await store.upsertNode(node);
- candidatePool.push(node); // allow intra-batch dedup
- result.nameToId.set(norm, node.id);
- result.nodesCreated += 1;
- }
- }
- }
-
- // Link relations between resolved nodes.
- for (const rel of extraction.relations) {
- const sourceId = result.nameToId.get(normalizeName(rel.source));
- const targetId = result.nameToId.get(normalizeName(rel.target));
- if (!sourceId || !targetId || sourceId === targetId) continue;
-
- const relation = normalizeName(rel.relation).replace(/\s+/g, "_");
- const existing = await store.findEdge(sourceId, targetId, relation);
- if (existing) {
- const description = betterSummary(existing.description, rel.description ?? "");
- if (description !== existing.description) {
- existing.description = description;
- existing.descriptionUpdatedAt = now;
- }
- bumpObservation(existing.observationSources, observationKey);
- existing.observations = totalObservations(existing.observationSources);
- existing.confidence = confidenceFromObservations(existing.observations);
- existing.provenance = unionSet(existing.provenance, [provenance]);
- existing.updatedAt = now;
- await store.upsertEdge(existing);
- result.edgesUpdated += 1;
- } else {
- const edge: GraphEdge = {
- id: newId("edge"),
- sourceId,
- targetId,
- relation,
- description: rel.description ?? "",
- descriptionUpdatedAt: now,
- confidence: confidenceFromObservations(1),
- observations: 1,
- observationSources: { [observationKey]: 1 },
- provenance: [provenance],
- createdAt: now,
- updatedAt: now,
- };
- await store.upsertEdge(edge);
- result.edgesCreated += 1;
- }
- }
-
- return result;
-}
-
-/** Find the best existing node to merge an incoming entity into, or undefined. */
-async function findMatch(
- store: GraphStore,
- candidatePool: GraphNode[],
- norm: string,
- aliases: string[],
- embedding: number[],
- threshold: number,
-): Promise<GraphNode | undefined> {
- // 1) Exact name/alias hit is authoritative.
- const byName = await store.findNodesByName(norm);
- if (byName.length > 0) {
- // Prefer the most-observed among exact matches.
- return byName.sort((a, b) => b.observations - a.observations)[0];
- }
-
- // 2) Otherwise, semantic match above the threshold.
- let best: GraphNode | undefined;
- let bestScore = threshold;
- for (const node of candidatePool) {
- if (!node.embedding) continue;
- // Alias overlap is a strong signal; give it a small boost.
- const aliasOverlap = node.aliases.some((a) => aliases.includes(a)) ? 0.05 : 0;
- const score = cosineSimilarity(embedding, node.embedding) + aliasOverlap;
- if (score >= bestScore) {
- best = node;
- bestScore = score;
- }
- }
- return best;
-}
-
-/**
- * Reconcile two *full node records* for the same logical entity — the CRDT merge
- * used when importing a serialized graph from a teammate (Mode A) or a replica.
- *
- * Unlike {@link mergeExtraction}, this does not add a new observation: it takes
- * the element-wise **max** of the two observation counters (idempotent — a
- * re-import is a no-op), unions the grow-only sets, and resolves free text by
- * last-writer-wins. The result is independent of merge order.
- */
-export function mergeNodeRecords(existing: GraphNode, incoming: GraphNode): GraphNode {
- const observationSources = mergeObservationCounters(
- existing.observationSources,
- incoming.observationSources,
- );
- const observations = totalObservations(observationSources);
- const summary = pickLatestText(
- { text: existing.summary, at: existing.summaryUpdatedAt },
- { text: incoming.summary, at: incoming.summaryUpdatedAt },
- );
- return {
- ...existing,
- // Keep the canonical name/type of the record we already have, but retain
- // both surface forms as aliases so either resolves to this node.
- aliases: unionSet(existing.aliases, incoming.aliases),
- summary: summary.text,
- summaryUpdatedAt: summary.at,
- confidence: confidenceFromObservations(observations),
- observations,
- observationSources,
- provenance: unionSet(existing.provenance, incoming.provenance),
- embedding: existing.embedding ?? incoming.embedding,
- createdAt: minStr(existing.createdAt, incoming.createdAt),
- updatedAt: maxStr(existing.updatedAt, incoming.updatedAt),
- };
-}
-
-/** CRDT reconciliation of two edge records for the same (source, target, relation). */
-export function mergeEdgeRecords(existing: GraphEdge, incoming: GraphEdge): GraphEdge {
- const observationSources = mergeObservationCounters(
- existing.observationSources,
- incoming.observationSources,
- );
- const observations = totalObservations(observationSources);
- const description = pickLatestText(
- { text: existing.description, at: existing.descriptionUpdatedAt },
- { text: incoming.description, at: incoming.descriptionUpdatedAt },
- );
- return {
- ...existing,
- description: description.text,
- descriptionUpdatedAt: description.at,
- confidence: confidenceFromObservations(observations),
- observations,
- observationSources,
- provenance: unionSet(existing.provenance, incoming.provenance),
- createdAt: minStr(existing.createdAt, incoming.createdAt),
- updatedAt: maxStr(existing.updatedAt, incoming.updatedAt),
- };
-}
-
-function minStr(a: string, b: string): string {
- return a <= b ? a : b;
-}
-function maxStr(a: string, b: string): string {
- return a >= b ? a : b;
-}
diff --git a/src/graph/serialize.ts b/src/graph/serialize.ts
deleted file mode 100644
index f377b58e..00000000
--- a/src/graph/serialize.ts
+++ /dev/null
@@ -1,231 +0,0 @@
-/**
- * Git-native team sync (Mode A): serialize the whole graph to a single
- * human-diffable JSONL file that a team commits to their repo, and import it
- * back with a conflict-free re-merge.
- *
- * The file is line-delimited JSON — one record per line, in FK-safe order
- * (meta, documents, nodes, edges, chunks) — so `git diff` shows exactly which
- * facts changed. Importing runs the CRDT record-merge ({@link mergeNodeRecords}
- * / {@link mergeEdgeRecords}), which is idempotent: pulling the same file twice
- * changes nothing, and two teammates' additions converge regardless of order.
- */
-import type { GraphStore } from "./store.js";
-import type { Chunk, GraphDocument, GraphEdge, GraphNode } from "./types.js";
-import { mergeEdgeRecords, mergeNodeRecords } from "./merge.js";
-import { normalizeName } from "../util/id.js";
-
-/** Current on-disk format version. Bumped if the record shape changes. */
-export const GRAPH_FILE_FORMAT = 1;
-
-interface GraphFileMeta {
- kind: "meta";
- format: number;
- /** Embedding dimensionality of the graph that produced this file. */
- embeddingDimensions: number;
- /** Optional embedding-model label, to warn on cross-model drift. */
- embeddingModel?: string;
- exportedAt: string;
- counts: { documents: number; nodes: number; edges: number; chunks: number };
-}
-
-export interface SerializeOptions {
- embeddingDimensions: number;
- embeddingModel?: string;
- /** Decimal places to round embeddings to (smaller = tidier git diffs). Default 6. */
- precision?: number;
-}
-
-export interface ImportResult {
- nodesCreated: number;
- nodesUpdated: number;
- edgesCreated: number;
- edgesUpdated: number;
- documentsAdded: number;
- chunksAdded: number;
- /** Non-fatal problems (e.g. embedding-model mismatch), for the caller to surface. */
- warnings: string[];
-}
-
-function round(vec: number[] | undefined, precision: number): number[] | undefined {
- if (!vec) return undefined;
- const f = 10 ** precision;
- return vec.map((x) => Math.round(x * f) / f);
-}
-
-/** Serialize the entire graph to a JSONL string. */
-export async function serializeGraph(
- store: GraphStore,
- opts: SerializeOptions,
-): Promise<string> {
- const precision = opts.precision ?? 6;
- const [documents, nodes, edges, chunks] = await Promise.all([
- store.allDocuments(),
- store.allNodes(),
- store.allEdges(),
- store.allChunks(),
- ]);
-
- const meta: GraphFileMeta = {
- kind: "meta",
- format: GRAPH_FILE_FORMAT,
- embeddingDimensions: opts.embeddingDimensions,
- embeddingModel: opts.embeddingModel,
- exportedAt: new Date().toISOString(),
- counts: {
- documents: documents.length,
- nodes: nodes.length,
- edges: edges.length,
- chunks: chunks.length,
- },
- };
-
- const lines: string[] = [JSON.stringify(meta)];
- // Deterministic ordering keeps diffs stable across exports.
- for (const d of [...documents].sort(byId)) lines.push(JSON.stringify({ kind: "document", ...d }));
- for (const n of [...nodes].sort(byId)) {
- lines.push(JSON.stringify({ kind: "node", ...n, embedding: round(n.embedding, precision) }));
- }
- for (const e of [...edges].sort(byId)) lines.push(JSON.stringify({ kind: "edge", ...e }));
- for (const c of [...chunks].sort(byId)) {
- lines.push(JSON.stringify({ kind: "chunk", ...c, embedding: round(c.embedding, precision) }));
- }
- return lines.join("\n") + "\n";
-}
-
-function byId(a: { id: string }, b: { id: string }): number {
- return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-}
-
-/**
- * Import a serialized graph into a store, CRDT-merging every record. Idempotent:
- * importing the same content twice is a no-op.
- *
- * @param embeddingDimensions The importing graph's embedding size; a mismatch
- * means the incoming vectors aren't comparable, so they're dropped (a warning
- * is returned) rather than corrupting retrieval.
- */
-export async function importGraph(
- store: GraphStore,
- jsonl: string,
- embeddingDimensions: number,
-): Promise<ImportResult> {
- const result: ImportResult = {
- nodesCreated: 0,
- nodesUpdated: 0,
- edgesCreated: 0,
- edgesUpdated: 0,
- documentsAdded: 0,
- chunksAdded: 0,
- warnings: [],
- };
-
- const documents: GraphDocument[] = [];
- const nodes: GraphNode[] = [];
- const edges: GraphEdge[] = [];
- const chunks: Chunk[] = [];
- let dropEmbeddings = false;
-
- for (const raw of jsonl.split("\n")) {
- const line = raw.trim();
- if (!line) continue;
- const rec = JSON.parse(line) as { kind: string } & Record<string, unknown>;
- switch (rec.kind) {
- case "meta": {
- const meta = rec as unknown as GraphFileMeta;
- if (meta.embeddingDimensions && meta.embeddingDimensions !== embeddingDimensions) {
- dropEmbeddings = true;
- result.warnings.push(
- `Embedding dimension mismatch (file ${meta.embeddingDimensions} vs local ${embeddingDimensions}` +
- (meta.embeddingModel ? `, model "${meta.embeddingModel}"` : "") +
- `). Imported facts kept; their embeddings were dropped, so re-embed by re-ingesting sources.`,
- );
- }
- break;
- }
- case "document":
- documents.push(stripKind(rec) as unknown as GraphDocument);
- break;
- case "node":
- nodes.push(stripKind(rec) as unknown as GraphNode);
- break;
- case "edge":
- edges.push(stripKind(rec) as unknown as GraphEdge);
- break;
- case "chunk":
- chunks.push(stripKind(rec) as unknown as Chunk);
- break;
- }
- }
-
- // Documents (dedup by content hash; remember any id remap for chunks).
- const docIdMap = new Map<string, string>();
- for (const doc of documents) {
- const existing = await store.getDocumentByHash(doc.hash);
- if (existing) {
- docIdMap.set(doc.id, existing.id);
- } else {
- await store.insertDocument(doc);
- docIdMap.set(doc.id, doc.id);
- result.documentsAdded += 1;
- }
- }
-
- // Nodes (resolve identity by id, then by name; remember id remap for edges).
- const nodeIdMap = new Map<string, string>();
- for (const incoming of nodes) {
- if (dropEmbeddings) incoming.embedding = undefined;
- const byId = await store.getNodeById(incoming.id);
- if (byId) {
- await store.upsertNode(mergeNodeRecords(byId, incoming));
- nodeIdMap.set(incoming.id, byId.id);
- result.nodesUpdated += 1;
- continue;
- }
- const byName = (await store.findNodesByName(normalizeName(incoming.name))).sort(
- (a, b) => b.observations - a.observations,
- )[0];
- if (byName) {
- await store.upsertNode(mergeNodeRecords(byName, incoming));
- nodeIdMap.set(incoming.id, byName.id);
- result.nodesUpdated += 1;
- } else {
- await store.upsertNode(incoming);
- nodeIdMap.set(incoming.id, incoming.id);
- result.nodesCreated += 1;
- }
- }
-
- // Edges (remap endpoints, then merge on the (source, target, relation) key).
- for (const incoming of edges) {
- const sourceId = nodeIdMap.get(incoming.sourceId) ?? incoming.sourceId;
- const targetId = nodeIdMap.get(incoming.targetId) ?? incoming.targetId;
- const mapped: GraphEdge = { ...incoming, sourceId, targetId };
- const existing = await store.findEdge(sourceId, targetId, incoming.relation);
- if (existing) {
- await store.upsertEdge(mergeEdgeRecords(existing, mapped));
- result.edgesUpdated += 1;
- } else {
- await store.upsertEdge(mapped);
- result.edgesCreated += 1;
- }
- }
-
- // Chunks (grow-only; skip ones we already have or whose document is absent).
- for (const incoming of chunks) {
- if (dropEmbeddings) incoming.embedding = undefined;
- const documentId = docIdMap.get(incoming.documentId) ?? incoming.documentId;
- if (!(await store.getDocumentById(documentId))) continue;
- const present = await store.getChunksByIds([incoming.id]);
- if (present.length > 0) continue;
- await store.insertChunk({ ...incoming, documentId });
- result.chunksAdded += 1;
- }
-
- return result;
-}
-
-function stripKind(rec: Record<string, unknown>): Record<string, unknown> {
- const { kind, ...rest } = rec;
- void kind;
- return rest;
-}
diff --git a/src/graph/sqlite-store.ts b/src/graph/sqlite-store.ts
deleted file mode 100644
index f1e090a8..00000000
--- a/src/graph/sqlite-store.ts
+++ /dev/null
@@ -1,481 +0,0 @@
-import Database from "better-sqlite3";
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import type { GraphStore } from "./store.js";
-import type {
- Chunk,
- GraphDocument,
- GraphEdge,
- GraphNode,
- GraphStats,
- ObservationCounter,
-} from "./types.js";
-import { normalizeName } from "../util/id.js";
-import { totalObservations } from "./crdt.js";
-
-interface NodeRow {
- id: string;
- name: string;
- norm_name: string;
- type: string;
- summary: string;
- summary_updated_at: string | null;
- aliases: string;
- confidence: number;
- observations: number;
- observation_sources: string | null;
- embedding: string | null;
- provenance: string;
- created_at: string;
- updated_at: string;
-}
-
-interface EdgeRow {
- id: string;
- source_id: string;
- target_id: string;
- relation: string;
- description: string;
- description_updated_at: string | null;
- confidence: number;
- observations: number;
- observation_sources: string | null;
- provenance: string;
- created_at: string;
- updated_at: string;
-}
-
-interface ChunkRow {
- id: string;
- document_id: string;
- ordinal: number;
- text: string;
- embedding: string | null;
- created_at: string;
-}
-
-/**
- * File-backed graph store using SQLite via better-sqlite3.
- *
- * better-sqlite3 is synchronous; the async {@link GraphStore} methods here just
- * wrap those synchronous calls and resolve immediately, so the local path stays
- * as fast as before while conforming to the interface a networked store needs.
- */
-export class SqliteStore implements GraphStore {
- private db: Database.Database;
-
- /** @param path Path to the .db file, or ":memory:" for an ephemeral graph. */
- constructor(path: string) {
- if (path !== ":memory:") {
- mkdirSync(dirname(path), { recursive: true });
- }
- this.db = new Database(path);
- this.db.pragma("journal_mode = WAL");
- this.db.pragma("foreign_keys = ON");
- this.migrate();
- }
-
- private migrate(): void {
- this.db.exec(`
- CREATE TABLE IF NOT EXISTS documents (
- id TEXT PRIMARY KEY,
- title TEXT NOT NULL,
- source TEXT NOT NULL,
- hash TEXT NOT NULL UNIQUE,
- created_at TEXT NOT NULL
- );
-
- CREATE TABLE IF NOT EXISTS chunks (
- id TEXT PRIMARY KEY,
- document_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
- ordinal INTEGER NOT NULL,
- text TEXT NOT NULL,
- embedding TEXT,
- created_at TEXT NOT NULL
- );
-
- CREATE TABLE IF NOT EXISTS nodes (
- id TEXT PRIMARY KEY,
- name TEXT NOT NULL,
- norm_name TEXT NOT NULL,
- type TEXT NOT NULL,
- summary TEXT NOT NULL,
- summary_updated_at TEXT,
- aliases TEXT NOT NULL DEFAULT '[]',
- confidence REAL NOT NULL DEFAULT 0.5,
- observations INTEGER NOT NULL DEFAULT 1,
- observation_sources TEXT NOT NULL DEFAULT '{}',
- embedding TEXT,
- provenance TEXT NOT NULL DEFAULT '[]',
- created_at TEXT NOT NULL,
- updated_at TEXT NOT NULL
- );
- CREATE INDEX IF NOT EXISTS idx_nodes_norm_name ON nodes(norm_name);
-
- CREATE TABLE IF NOT EXISTS edges (
- id TEXT PRIMARY KEY,
- source_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
- target_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
- relation TEXT NOT NULL,
- description TEXT NOT NULL DEFAULT '',
- description_updated_at TEXT,
- confidence REAL NOT NULL DEFAULT 0.5,
- observations INTEGER NOT NULL DEFAULT 1,
- observation_sources TEXT NOT NULL DEFAULT '{}',
- provenance TEXT NOT NULL DEFAULT '[]',
- created_at TEXT NOT NULL,
- updated_at TEXT NOT NULL,
- UNIQUE(source_id, target_id, relation)
- );
- CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
- CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
- `);
- // Additive migrations for graphs created before the CRDT columns existed.
- this.addColumnIfMissing("nodes", "summary_updated_at", "TEXT");
- this.addColumnIfMissing("nodes", "observation_sources", "TEXT NOT NULL DEFAULT '{}'");
- this.addColumnIfMissing("edges", "description_updated_at", "TEXT");
- this.addColumnIfMissing("edges", "observation_sources", "TEXT NOT NULL DEFAULT '{}'");
- }
-
- private addColumnIfMissing(table: string, column: string, ddl: string): void {
- const cols = this.db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
- if (!cols.some((c) => c.name === column)) {
- this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${ddl}`);
- }
- }
-
- // --- documents ---
-
- async getDocumentByHash(hash: string): Promise<GraphDocument | undefined> {
- const row = this.db.prepare(`SELECT * FROM documents WHERE hash = ?`).get(hash) as
- | (GraphDocument & { created_at: string })
- | undefined;
- return row ? this.rowToDocument(row as unknown as Record<string, unknown>) : undefined;
- }
-
- async getDocumentById(id: string): Promise<GraphDocument | undefined> {
- const row = this.db.prepare(`SELECT * FROM documents WHERE id = ?`).get(id) as
- | Record<string, unknown>
- | undefined;
- return row ? this.rowToDocument(row) : undefined;
- }
-
- async documentsBySource(source: string): Promise<GraphDocument[]> {
- const rows = this.db
- .prepare(`SELECT * FROM documents WHERE source = ? ORDER BY created_at DESC`)
- .all(source) as Array<Record<string, unknown>>;
- return rows.map((r) => this.rowToDocument(r));
- }
-
- async deleteDocument(id: string): Promise<void> {
- // Chunks cascade via the document_id foreign key.
- this.db.prepare(`DELETE FROM documents WHERE id = ?`).run(id);
- }
-
- async insertDocument(doc: GraphDocument): Promise<void> {
- this.db
- .prepare(
- `INSERT OR IGNORE INTO documents (id, title, source, hash, created_at)
- VALUES (@id, @title, @source, @hash, @createdAt)`,
- )
- .run(doc);
- }
-
- async allDocuments(): Promise<GraphDocument[]> {
- const rows = this.db
- .prepare(`SELECT * FROM documents ORDER BY created_at DESC`)
- .all() as Array<Record<string, unknown>>;
- return rows.map((r) => this.rowToDocument(r));
- }
-
- private rowToDocument(r: Record<string, unknown>): GraphDocument {
- return {
- id: r.id as string,
- title: r.title as string,
- source: r.source as string,
- hash: r.hash as string,
- createdAt: r.created_at as string,
- };
- }
-
- async documentTitle(documentId: string): Promise<string> {
- const row = this.db
- .prepare(`SELECT title FROM documents WHERE id = ?`)
- .get(documentId) as { title: string } | undefined;
- return row?.title ?? "unknown";
- }
-
- // --- chunks ---
-
- async insertChunk(chunk: Chunk): Promise<void> {
- this.db
- .prepare(
- `INSERT OR IGNORE INTO chunks (id, document_id, ordinal, text, embedding, created_at)
- VALUES (@id, @documentId, @ordinal, @text, @embedding, @createdAt)`,
- )
- .run({
- ...chunk,
- embedding: chunk.embedding ? JSON.stringify(chunk.embedding) : null,
- });
- }
-
- async getChunksByIds(ids: string[]): Promise<Chunk[]> {
- if (ids.length === 0) return [];
- const placeholders = ids.map(() => "?").join(",");
- const rows = this.db
- .prepare(`SELECT * FROM chunks WHERE id IN (${placeholders})`)
- .all(...ids) as ChunkRow[];
- return rows.map(this.rowToChunk);
- }
-
- async allEmbeddedChunks(): Promise<Chunk[]> {
- const rows = this.db
- .prepare(`SELECT * FROM chunks WHERE embedding IS NOT NULL`)
- .all() as ChunkRow[];
- return rows.map(this.rowToChunk);
- }
-
- async allChunks(): Promise<Chunk[]> {
- const rows = this.db.prepare(`SELECT * FROM chunks`).all() as ChunkRow[];
- return rows.map(this.rowToChunk);
- }
-
- private rowToChunk(row: ChunkRow): Chunk {
- return {
- id: row.id,
- documentId: row.document_id,
- ordinal: row.ordinal,
- text: row.text,
- embedding: row.embedding ? JSON.parse(row.embedding) : undefined,
- createdAt: row.created_at,
- };
- }
-
- // --- nodes ---
-
- async getNodeById(id: string): Promise<GraphNode | undefined> {
- const row = this.db.prepare(`SELECT * FROM nodes WHERE id = ?`).get(id) as
- | NodeRow
- | undefined;
- return row ? this.rowToNode(row) : undefined;
- }
-
- async getNodesByIds(ids: string[]): Promise<GraphNode[]> {
- if (ids.length === 0) return [];
- const placeholders = ids.map(() => "?").join(",");
- const rows = this.db
- .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
- .all(...ids) as NodeRow[];
- return rows.map((r) => this.rowToNode(r));
- }
-
- async findNodesByName(normalizedName: string): Promise<GraphNode[]> {
- // Match either the canonical normalized name or any alias. Aliases are
- // stored normalized in a JSON array, so we match the quoted element form
- // (e.g. `"oauth"`) to avoid partial-substring false positives.
- const rows = this.db
- .prepare(
- `SELECT * FROM nodes
- WHERE norm_name = ?
- OR aliases LIKE ?`,
- )
- .all(normalizedName, `%${JSON.stringify(normalizedName)}%`) as NodeRow[];
- return rows.map((r) => this.rowToNode(r));
- }
-
- async allEmbeddedNodes(): Promise<GraphNode[]> {
- const rows = this.db
- .prepare(`SELECT * FROM nodes WHERE embedding IS NOT NULL`)
- .all() as NodeRow[];
- return rows.map((r) => this.rowToNode(r));
- }
-
- async allNodes(): Promise<GraphNode[]> {
- const rows = this.db.prepare(`SELECT * FROM nodes`).all() as NodeRow[];
- return rows.map((r) => this.rowToNode(r));
- }
-
- async upsertNode(node: GraphNode): Promise<void> {
- this.db
- .prepare(
- `INSERT INTO nodes
- (id, name, norm_name, type, summary, summary_updated_at, aliases, confidence,
- observations, observation_sources, embedding, provenance, created_at, updated_at)
- VALUES
- (@id, @name, @norm_name, @type, @summary, @summary_updated_at, @aliases, @confidence,
- @observations, @observation_sources, @embedding, @provenance, @created_at, @updated_at)
- ON CONFLICT(id) DO UPDATE SET
- name = excluded.name,
- norm_name = excluded.norm_name,
- type = excluded.type,
- summary = excluded.summary,
- summary_updated_at = excluded.summary_updated_at,
- aliases = excluded.aliases,
- confidence = excluded.confidence,
- observations = excluded.observations,
- observation_sources = excluded.observation_sources,
- embedding = excluded.embedding,
- provenance = excluded.provenance,
- updated_at = excluded.updated_at`,
- )
- .run({
- id: node.id,
- name: node.name,
- norm_name: normalizeName(node.name),
- type: node.type,
- summary: node.summary,
- summary_updated_at: node.summaryUpdatedAt,
- aliases: JSON.stringify(node.aliases),
- confidence: node.confidence,
- observations: node.observations,
- observation_sources: JSON.stringify(node.observationSources),
- embedding: node.embedding ? JSON.stringify(node.embedding) : null,
- provenance: JSON.stringify(node.provenance),
- created_at: node.createdAt,
- updated_at: node.updatedAt,
- });
- }
-
- async deleteNode(id: string): Promise<void> {
- // Incident edges cascade via the source_id/target_id foreign keys
- // (foreign_keys = ON, set in the constructor).
- this.db.prepare(`DELETE FROM nodes WHERE id = ?`).run(id);
- }
-
- private rowToNode(row: NodeRow): GraphNode {
- const observationSources = parseCounter(row.observation_sources, row.observations);
- return {
- id: row.id,
- name: row.name,
- type: row.type,
- summary: row.summary,
- summaryUpdatedAt: row.summary_updated_at ?? row.updated_at,
- aliases: JSON.parse(row.aliases),
- confidence: row.confidence,
- observations: totalObservations(observationSources),
- observationSources,
- embedding: row.embedding ? JSON.parse(row.embedding) : undefined,
- provenance: JSON.parse(row.provenance),
- createdAt: row.created_at,
- updatedAt: row.updated_at,
- };
- }
-
- // --- edges ---
-
- async findEdge(
- sourceId: string,
- targetId: string,
- relation: string,
- ): Promise<GraphEdge | undefined> {
- const row = this.db
- .prepare(
- `SELECT * FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?`,
- )
- .get(sourceId, targetId, relation) as EdgeRow | undefined;
- return row ? this.rowToEdge(row) : undefined;
- }
-
- async upsertEdge(edge: GraphEdge): Promise<void> {
- this.db
- .prepare(
- `INSERT INTO edges
- (id, source_id, target_id, relation, description, description_updated_at, confidence,
- observations, observation_sources, provenance, created_at, updated_at)
- VALUES
- (@id, @source_id, @target_id, @relation, @description, @description_updated_at, @confidence,
- @observations, @observation_sources, @provenance, @created_at, @updated_at)
- ON CONFLICT(source_id, target_id, relation) DO UPDATE SET
- description = excluded.description,
- description_updated_at = excluded.description_updated_at,
- confidence = excluded.confidence,
- observations = excluded.observations,
- observation_sources = excluded.observation_sources,
- provenance = excluded.provenance,
- updated_at = excluded.updated_at`,
- )
- .run({
- id: edge.id,
- source_id: edge.sourceId,
- target_id: edge.targetId,
- relation: edge.relation,
- description: edge.description,
- description_updated_at: edge.descriptionUpdatedAt,
- confidence: edge.confidence,
- observations: edge.observations,
- observation_sources: JSON.stringify(edge.observationSources),
- provenance: JSON.stringify(edge.provenance),
- created_at: edge.createdAt,
- updated_at: edge.updatedAt,
- });
- }
-
- async deleteEdge(id: string): Promise<void> {
- this.db.prepare(`DELETE FROM edges WHERE id = ?`).run(id);
- }
-
- async edgesForNodes(nodeIds: string[]): Promise<GraphEdge[]> {
- if (nodeIds.length === 0) return [];
- const placeholders = nodeIds.map(() => "?").join(",");
- const rows = this.db
- .prepare(
- `SELECT * FROM edges
- WHERE source_id IN (${placeholders}) OR target_id IN (${placeholders})`,
- )
- .all(...nodeIds, ...nodeIds) as EdgeRow[];
- return rows.map((r) => this.rowToEdge(r));
- }
-
- async allEdges(): Promise<GraphEdge[]> {
- const rows = this.db.prepare(`SELECT * FROM edges`).all() as EdgeRow[];
- return rows.map((r) => this.rowToEdge(r));
- }
-
- private rowToEdge(row: EdgeRow): GraphEdge {
- const observationSources = parseCounter(row.observation_sources, row.observations);
- return {
- id: row.id,
- sourceId: row.source_id,
- targetId: row.target_id,
- relation: row.relation,
- description: row.description,
- descriptionUpdatedAt: row.description_updated_at ?? row.updated_at,
- confidence: row.confidence,
- observations: totalObservations(observationSources),
- observationSources,
- provenance: JSON.parse(row.provenance),
- createdAt: row.created_at,
- updatedAt: row.updated_at,
- };
- }
-
- // --- misc ---
-
- async stats(): Promise<GraphStats> {
- const count = (table: string): number =>
- (this.db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
- return {
- documents: count("documents"),
- nodes: count("nodes"),
- edges: count("edges"),
- chunks: count("chunks"),
- };
- }
-
- async close(): Promise<void> {
- this.db.close();
- }
-}
-
-/**
- * Parse a stored observation counter. Graphs created before the CRDT columns
- * existed have an empty counter but a real scalar `observations`; seed a single
- * "legacy" bucket so their totals survive the migration.
- */
-function parseCounter(raw: string | null, legacyObservations: number): ObservationCounter {
- const parsed = raw ? (JSON.parse(raw) as ObservationCounter) : {};
- if (Object.keys(parsed).length === 0 && legacyObservations > 0) {
- return { legacy: legacyObservations };
- }
- return parsed;
-}
diff --git a/src/graph/store.ts b/src/graph/store.ts
deleted file mode 100644
index fb6d0093..00000000
--- a/src/graph/store.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import type {
- Chunk,
- GraphDocument,
- GraphEdge,
- GraphNode,
- GraphStats,
-} from "./types.js";
-
-/**
- * Storage backend for the context graph.
- *
- * The engine talks to the graph exclusively through this interface, so the
- * default local SQLite backend can be swapped for another store — a
- * Postgres/pgvector service, a remote replica, or an in-memory store — without
- * touching engine logic.
- *
- * All methods are **async**. The local `better-sqlite3` store is synchronous
- * under the hood and simply resolves immediately; a networked store needs the
- * async surface to talk to its remote.
- */
-export interface GraphStore {
- // --- documents ---
- getDocumentByHash(hash: string): Promise<GraphDocument | undefined>;
- getDocumentById(id: string): Promise<GraphDocument | undefined>;
- /** All documents recorded with the given source (path/URL/label), newest first. */
- documentsBySource(source: string): Promise<GraphDocument[]>;
- insertDocument(doc: GraphDocument): Promise<void>;
- /**
- * Delete a document and its chunks (e.g. when re-ingesting a changed file).
- * Nodes/edges extracted from it keep their observations — the grow-only CRDT
- * counters never shrink.
- */
- deleteDocument(id: string): Promise<void>;
- /** Every ingested document, newest first (for UI listings). */
- allDocuments(): Promise<GraphDocument[]>;
-
- // --- chunks ---
- insertChunk(chunk: Chunk): Promise<void>;
- getChunksByIds(ids: string[]): Promise<Chunk[]>;
- /** All chunks that have an embedding, for in-memory vector search. */
- allEmbeddedChunks(): Promise<Chunk[]>;
- /** Every chunk in the graph (for serialization / export). */
- allChunks(): Promise<Chunk[]>;
-
- // --- nodes ---
- getNodeById(id: string): Promise<GraphNode | undefined>;
- getNodesByIds(ids: string[]): Promise<GraphNode[]>;
- /** Nodes whose canonical name or an alias matches (normalized, exact). */
- findNodesByName(normalizedName: string): Promise<GraphNode[]>;
- /** All nodes that have an embedding, for in-memory vector search & dedup. */
- allEmbeddedNodes(): Promise<GraphNode[]>;
- /** Every node in the graph (for export/visualization). */
- allNodes(): Promise<GraphNode[]>;
- upsertNode(node: GraphNode): Promise<void>;
- /**
- * Delete a node and (via the edge foreign keys) every edge incident to it.
- * Used by the pruning path when a node's last supporting source disappears.
- */
- deleteNode(id: string): Promise<void>;
-
- // --- edges ---
- /** Existing edge with the same (source, target, relation), if any. */
- findEdge(sourceId: string, targetId: string, relation: string): Promise<GraphEdge | undefined>;
- upsertEdge(edge: GraphEdge): Promise<void>;
- /** Delete a single edge by id (used when its last supporting source disappears). */
- deleteEdge(id: string): Promise<void>;
- /** All edges incident to any of the given node ids. */
- edgesForNodes(nodeIds: string[]): Promise<GraphEdge[]>;
- /** Every edge in the graph (for export/visualization). */
- allEdges(): Promise<GraphEdge[]>;
-
- // --- misc ---
- documentTitle(documentId: string): Promise<string>;
- stats(): Promise<GraphStats>;
- close(): Promise<void>;
-}
diff --git a/src/graph/types.ts b/src/graph/types.ts
deleted file mode 100644
index 09014412..00000000
--- a/src/graph/types.ts
+++ /dev/null
@@ -1,162 +0,0 @@
-/**
- * Core data model for the context graph.
- *
- * The graph has three primary record kinds:
- * - {@link GraphNode} — an entity or concept ("what things are")
- * - {@link GraphEdge} — a typed relationship between two nodes ("how things relate")
- * - {@link Chunk} — a passage of source text that grounds nodes/edges in evidence
- *
- * Nodes and edges carry a `confidence` and `observations` count. Every time an
- * agent re-observes the same fact, `observations` is incremented and confidence
- * is reinforced — this is what lets the graph "get smarter over time".
- */
-
-/** A source document that was ingested into the graph. */
-export interface GraphDocument {
- id: string;
- /** Human-readable title. */
- title: string;
- /** Where this came from: a file path, URL, or free-form label. */
- source: string;
- /** Content hash, used to skip re-ingesting identical documents. */
- hash: string;
- createdAt: string;
-}
-
-/**
- * A conflict-free observation counter: maps a *unique observation key* (the id
- * of the document/contribution that observed the fact) to how many times that
- * single observation event reinforced it. Because keys are globally unique per
- * event, merging two counters is an element-wise **max** — commutative,
- * associative, and idempotent. That is what makes re-importing the same records
- * safe: replaying an observation never double-counts. See {@link ../graph/crdt}.
- */
-export type ObservationCounter = Record<string, number>;
-
-/** An entity or concept in the graph. */
-export interface GraphNode {
- id: string;
- /** Canonical display name, e.g. "OAuth 2.0". */
- name: string;
- /** Coarse category, e.g. "concept", "system", "person", "api", "policy". */
- type: string;
- /** A short natural-language description of the node, synthesized from evidence. */
- summary: string;
- /**
- * Wall-clock stamp of when `summary` was last set. Used as a last-writer-wins
- * tiebreaker when reconciling two replicas that hold different summaries.
- */
- summaryUpdatedAt: string;
- /** Alternate names / surface forms that map to this node. */
- aliases: string[];
- /**
- * 0..1 confidence that this node is real and correctly described. **Derived**
- * (a pure function of the observation total), never mutated in place, so it
- * converges deterministically no matter how records are merged.
- */
- confidence: number;
- /**
- * How many times this entity has been observed. **Derived** as the sum of
- * {@link observationSources}; stored denormalized so existing readers keep
- * working without recomputing.
- */
- observations: number;
- /** The CRDT observation counter that {@link observations} is derived from. */
- observationSources: ObservationCounter;
- /** Vector embedding of `name + summary`, used for semantic matching & dedup. */
- embedding?: number[];
- /** Where this knowledge came from (document ids, agent ids) — a grow-only set. */
- provenance: string[];
- createdAt: string;
- updatedAt: string;
-}
-
-/** A directed, typed relationship between two nodes. */
-export interface GraphEdge {
- id: string;
- sourceId: string;
- targetId: string;
- /** The predicate, e.g. "depends_on", "authenticates_with", "part_of". */
- relation: string;
- /** Optional natural-language description of the relationship. */
- description: string;
- /** Last-writer-wins stamp for `description` (see {@link GraphNode.summaryUpdatedAt}). */
- descriptionUpdatedAt: string;
- /** **Derived** from the observation total (see {@link GraphNode.confidence}). */
- confidence: number;
- /** **Derived** as the sum of {@link observationSources}. */
- observations: number;
- /** The CRDT observation counter that {@link observations} is derived from. */
- observationSources: ObservationCounter;
- provenance: string[];
- createdAt: string;
- updatedAt: string;
-}
-
-/** A passage of source text, used as retrieval evidence. */
-export interface Chunk {
- id: string;
- documentId: string;
- /** Ordinal position within the document. */
- ordinal: number;
- text: string;
- embedding?: number[];
- createdAt: string;
-}
-
-/** A single extracted entity, before it is merged into the graph. */
-export interface ExtractedEntity {
- name: string;
- type: string;
- summary: string;
- aliases?: string[];
-}
-
-/** A single extracted relationship, before it is merged into the graph. */
-export interface ExtractedRelation {
- source: string;
- target: string;
- relation: string;
- description?: string;
-}
-
-/** The result of running extraction over a piece of text. */
-export interface Extraction {
- entities: ExtractedEntity[];
- relations: ExtractedRelation[];
-}
-
-/** A node returned from retrieval, annotated with why it was surfaced. */
-export interface RetrievedNode extends GraphNode {
- /** Relevance score in 0..1 (semantic similarity or traversal-derived). */
- score: number;
- /** How this node entered the result: direct semantic hit, or graph expansion. */
- via: "semantic" | "expanded";
-}
-
-/** A chunk returned from retrieval. */
-export interface RetrievedChunk extends Chunk {
- score: number;
- documentTitle: string;
-}
-
-/** The structured context bundle an agent reads before doing work. */
-export interface ContextBundle {
- query: string;
- /** Entities relevant to the query, most-relevant first. */
- nodes: RetrievedNode[];
- /** Relationships connecting the surfaced nodes. */
- edges: GraphEdge[];
- /** Supporting source passages. */
- chunks: RetrievedChunk[];
- /** A ready-to-inject, human/LLM-readable rendering of the above. */
- prompt: string;
-}
-
-/** Summary counts describing the current graph. */
-export interface GraphStats {
- documents: number;
- nodes: number;
- edges: number;
- chunks: number;
-}
diff --git a/src/index.ts b/src/index.ts
index a208dfcc..ecd5beb8 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,79 +1,34 @@
/**
* Context Graph Engine — public API.
*
+ * The graph is a folder of linked markdown files (`.context/`) committed to the
+ * repo. Build it from code, then check it stays in sync.
+ *
* @example
* ```ts
* import { ContextGraphEngine } from "context-graph-engine";
*
* const engine = new ContextGraphEngine();
- * await engine.ingest(myDocs, { title: "Onboarding" });
- *
- * const ctx = await engine.read("how does auth work?");
- * console.log(ctx.prompt); // inject into your agent
+ * await engine.init("."); // writes .context/*.md + manifest.json
*
- * await engine.contribute("The auth service rotates tokens every 15 minutes.", {
- * agentId: "code-reviewer",
- * });
+ * const result = engine.check("."); // { ok: boolean, ...drift }
+ * if (!result.ok) process.exitCode = 1;
* ```
*/
export { ContextGraphEngine, CODE_EXTENSIONS } from "./engine.js";
-export type {
- IngestOptions,
- IngestResult,
- ContributeOptions,
- ContributeResult,
- PruneResult,
- RepoIngestOptions,
- RepoIngestResult,
- WatchedDir,
-} from "./engine.js";
+export type { InitOptions, CheckRunOptions, BuildResult, BuildProgress, CheckResult } from "./engine.js";
-export { DOC_EXTENSIONS } from "./ingest/fs.js";
-export { GraphWatcher } from "./watch.js";
-export type { WatchOptions, WatchEvent } from "./watch.js";
+export { buildContext } from "./context/build.js";
+export type { BuildOptions } from "./context/build.js";
+export { checkContext, formatCheckReport } from "./context/check.js";
+export type { CheckOptions } from "./context/check.js";
+export type { ContextNode, NodeLink, SourceRef, Manifest } from "./context/node-file.js";
-export type {
- EngineConfig,
- ResolvedConfig,
- Embedder,
- Extractor,
-} from "./ai/providers.js";
+export type { EngineConfig, ResolvedConfig } from "./ai/providers.js";
export { resolveConfig, DEFAULTS } from "./ai/providers.js";
-export type { RetrieveOptions } from "./retrieval/retriever.js";
-export { retrieve, renderPrompt } from "./retrieval/retriever.js";
-
-export type { GraphStore } from "./graph/store.js";
-export { SqliteStore } from "./graph/sqlite-store.js";
-export { mergeExtraction, mergeNodeRecords, mergeEdgeRecords } from "./graph/merge.js";
-export {
- confidenceFromObservations,
- mergeObservationCounters,
- totalObservations,
-} from "./graph/crdt.js";
-export { serializeGraph, importGraph, GRAPH_FILE_FORMAT } from "./graph/serialize.js";
-export type { ImportResult, SerializeOptions } from "./graph/serialize.js";
-export type { GraphExport } from "./graph/export.js";
-export { buildGraphExport, toHtml, toMermaid } from "./graph/export.js";
-
-export type {
- GraphNode,
- GraphEdge,
- GraphDocument,
- Chunk,
- ObservationCounter,
- ContextBundle,
- RetrievedNode,
- RetrievedChunk,
- GraphStats,
- Extraction,
- ExtractedEntity,
- ExtractedRelation,
-} from "./graph/types.js";
-
// Providers, for advanced/custom setups.
-export { OpenRouterExtractor } from "./ai/openrouter.js";
-export { OpenAIEmbedder } from "./ai/openai.js";
-export { LocalEmbedder, OllamaExtractor } from "./ai/local.js";
+export { OpenRouterSynthesizer, OllamaSynthesizer } from "./ai/synthesize.js";
+export type { Synthesizer, SynthNode, SynthLink, FileSummary } from "./ai/synthesize.js";
export { OpenRouterSummarizer, OllamaSummarizer } from "./ai/summarize.js";
export type { Summarizer } from "./ai/summarize.js";
diff --git a/src/ingest/chunker.ts b/src/ingest/chunker.ts
deleted file mode 100644
index f2567ad4..00000000
--- a/src/ingest/chunker.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-/**
- * Split a document into overlapping chunks for embedding and extraction.
- *
- * The splitter is paragraph-aware: it accumulates whole paragraphs up to the
- * target size, and only hard-splits a paragraph that is larger than the target
- * on its own. Adjacent chunks share `overlap` characters so context that spans
- * a boundary is not lost.
- */
-export function chunkText(
- text: string,
- targetSize: number,
- overlap: number,
-): string[] {
- const clean = text.replace(/\r\n/g, "\n").trim();
- if (clean.length === 0) return [];
- if (clean.length <= targetSize) return [clean];
-
- const paragraphs = clean.split(/\n{2,}/);
- const chunks: string[] = [];
- let current = "";
-
- const flush = () => {
- const trimmed = current.trim();
- if (trimmed.length > 0) chunks.push(trimmed);
- // Seed the next chunk with the tail of this one for overlap.
- current = overlap > 0 ? trimmed.slice(-overlap) : "";
- };
-
- for (const para of paragraphs) {
- if (para.length > targetSize) {
- // Paragraph too big on its own: flush, then hard-split by sentence.
- if (current.trim().length > 0) flush();
- for (const piece of hardSplit(para, targetSize, overlap)) chunks.push(piece);
- current = overlap > 0 ? (chunks[chunks.length - 1] ?? "").slice(-overlap) : "";
- continue;
- }
- if (current.length + para.length + 2 > targetSize && current.trim().length > 0) {
- flush();
- }
- current += (current.length > 0 ? "\n\n" : "") + para;
- }
- if (current.trim().length > 0) chunks.push(current.trim());
-
- // De-dup consecutive identical chunks that overlap-seeding can produce.
- return chunks.filter((c, i) => i === 0 || c !== chunks[i - 1]);
-}
-
-/** Split a single oversized block by sentence boundaries into <= size pieces. */
-function hardSplit(block: string, size: number, overlap: number): string[] {
- const sentences = block.split(/(?<=[.!?])\s+/);
- const out: string[] = [];
- let cur = "";
- for (const s of sentences) {
- if (cur.length + s.length + 1 > size && cur.length > 0) {
- out.push(cur.trim());
- cur = overlap > 0 ? cur.slice(-overlap) : "";
- }
- cur += (cur.length > 0 ? " " : "") + s;
- }
- if (cur.trim().length > 0) out.push(cur.trim());
- return out;
-}
diff --git a/src/ingest/fs.ts b/src/ingest/fs.ts
index c58749cf..f39682db 100644
--- a/src/ingest/fs.ts
+++ b/src/ingest/fs.ts
@@ -1,14 +1,10 @@
/**
- * Filesystem walking/filtering rules shared by directory ingestion and the
- * auto-watch daemon, so both always agree on which files are knowledge.
+ * Filesystem walking used by `init`/`check` to enumerate a repo's source files.
*/
import { readdirSync, statSync } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { join } from "node:path";
-/** Extensions treated as documents by `ingestDir` and the watcher. */
-export const DOC_EXTENSIONS = [".pdf", ".md", ".markdown", ".txt"];
-
-/** Directories that are dependency/build output, never knowledge. */
+/** Directories that are dependency/build output, never source. */
export const SKIP_DIRS = new Set([
"node_modules",
"dist",
@@ -21,7 +17,7 @@ export const SKIP_DIRS = new Set([
"venv",
]);
-/** Files above this size are generated/vendored in practice, not written docs or code. */
+/** Files above this size are generated/vendored in practice, not hand-written code. */
export const MAX_FILE_BYTES = 1_000_000;
/**
@@ -47,49 +43,3 @@ export function walkDir(dir: string): string[] {
}
return out;
}
-
-/** True if any path segment is a dot-entry or a SKIP_DIRS directory. */
-function hasSkippedSegment(path: string): boolean {
- return path
- .split(sep)
- .some((seg) => seg.length > 0 && (seg.startsWith(".") || SKIP_DIRS.has(seg)));
-}
-
-/**
- * True if this path passes the same rules {@link walkDir} applies below
- * `root`: a matching extension, no dot-file/dot-dir or SKIP_DIRS segment
- * under the root, and at most 1 MB. The root itself is exempt from the
- * segment rules — watching `~/.notes` is legitimate, just as `walkDir` never
- * inspects the directory it was pointed at.
- */
-export function isIngestablePath(
- path: string,
- root: string,
- extensions: string[] = DOC_EXTENSIONS,
-): boolean {
- if (hasSkippedSegment(relative(root, path))) return false;
- const lower = path.toLowerCase();
- if (!extensions.some((e) => lower.endsWith(e))) return false;
- try {
- if (statSync(path).size > MAX_FILE_BYTES) return false;
- } catch {
- return false;
- }
- return true;
-}
-
-/**
- * Predicate for a file watcher's `ignored` option: true for dot/SKIP_DIRS
- * entries below `root` (so they are never descended into) and for oversized
- * files. Extension filtering is left to the event handler — watchers hand us
- * stats only sometimes, and directories have no extension to test.
- */
-export function shouldIgnorePath(
- path: string,
- root: string,
- stats?: { isDirectory(): boolean; size: number },
-): boolean {
- if (hasSkippedSegment(relative(root, path))) return true;
- if (stats && !stats.isDirectory() && stats.size > MAX_FILE_BYTES) return true;
- return false;
-}
diff --git a/src/ingest/pdf.ts b/src/ingest/pdf.ts
deleted file mode 100644
index 99198aec..00000000
--- a/src/ingest/pdf.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { readFile } from "node:fs/promises";
-
-/**
- * Extract plain text from a PDF file.
- *
- * Uses `unpdf` (a pure-JS build of pdf.js) so there are no native binaries to
- * compile — it works anywhere Node runs, which keeps the `curl | sh` install
- * story honest. Pages are merged into a single string for chunking.
- */
-export async function extractPdfText(path: string): Promise<string> {
- const buffer = await readFile(path);
- return extractPdfTextFromData(new Uint8Array(buffer));
-}
-
-/**
- * Extract plain text from PDF bytes already in memory — used for browser
- * uploads, where there is no file on the server's disk to read.
- */
-export async function extractPdfTextFromData(data: Uint8Array): Promise<string> {
- const { extractText, getDocumentProxy } = await import("unpdf");
- const pdf = await getDocumentProxy(data);
- const { text } = await extractText(pdf, { mergePages: true });
- return Array.isArray(text) ? text.join("\n\n") : text;
-}
-
-/** True if the path looks like a PDF (by extension). */
-export function isPdfPath(path: string): boolean {
- return /\.pdf$/i.test(path);
-}
diff --git a/src/mcp.ts b/src/mcp.ts
deleted file mode 100644
index c9fe558a..00000000
--- a/src/mcp.ts
+++ /dev/null
@@ -1,504 +0,0 @@
-#!/usr/bin/env node
-/**
- * MCP server exposing the context graph to any MCP client (Claude Code, Cursor,
- * etc.). Agents `context_read` before doing work and `context_contribute` what
- * they learn — mirroring the "shared skill / durable memory" integration model.
- *
- * The tool registrations are packaged as {@link createContextGraphMcpServer} so
- * the same server can be driven over stdio (`context-graph-mcp`, below) or over
- * Streamable HTTP by the unified `context-graph serve` command — both sharing a
- * single engine and watcher.
- *
- * Run: context-graph-mcp (configure the db via CONTEXT_GRAPH_DB)
- */
-import "dotenv/config";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { fileURLToPath } from "node:url";
-import { resolve } from "node:path";
-import { writeFileSync, readFileSync, existsSync } from "node:fs";
-import { ContextGraphEngine } from "./engine.js";
-import { GraphWatcher, type WatchEvent } from "./watch.js";
-import { toHtml } from "./graph/export.js";
-
-/** Dependencies a context-graph MCP server binds to. Shared across transports. */
-export interface McpDeps {
- /** The (shared) engine every tool operates on. */
- engine: ContextGraphEngine;
- /** Ensure/return the watcher used by `context_watch_dir`. */
- getWatcher: () => GraphWatcher;
- /** Peek at the watcher without creating one (status/unwatch). Defaults to a non-creating view. */
- peekWatcher?: () => GraphWatcher | undefined;
- /** Point the watcher's catch-up progress at a sink for the duration of a watch call. */
- setProgressSink: (sink: ((event: WatchEvent) => void) | undefined) => void;
-}
-
-/**
- * Build an {@link McpServer} with the context-graph tools registered against the
- * given dependencies. Every transport (stdio, Streamable HTTP) gets its own
- * server instance, but they can all share one engine + watcher via `deps`.
- */
-export function createContextGraphMcpServer(deps: McpDeps): McpServer {
- const { engine } = deps;
- const peekWatcher = deps.peekWatcher ?? (() => undefined);
-
- const server = new McpServer({
- name: "context-graph-engine",
- version: "0.1.0",
- });
-
- server.registerTool(
- "context_read",
- {
- title: "Read shared context",
- description:
- "Read the shared context graph for a query BEFORE doing work. Returns relevant entities, relationships, and supporting sources as a ready-to-use context block.",
- inputSchema: {
- query: z.string().describe("What you need context about."),
- maxNodes: z.number().int().min(1).max(50).optional().describe("Max entities (default 8)."),
- maxChunks: z.number().int().min(0).max(50).optional().describe("Max source passages (default 6)."),
- },
- },
- async ({ query, maxNodes, maxChunks }) => {
- const bundle = await engine.read(query, { maxNodes, maxChunks });
- return { content: [{ type: "text", text: bundle.prompt }] };
- },
- );
-
- server.registerTool(
- "context_contribute",
- {
- title: "Contribute a learning",
- description:
- "Contribute something you learned back into the shared context graph so future agents benefit. It is deduplicated and merged with existing knowledge.",
- inputSchema: {
- learning: z.string().describe("The fact or insight to record, in plain language."),
- agentId: z.string().optional().describe("Your agent identifier (default 'agent')."),
- },
- },
- async ({ learning, agentId }) => {
- const r = await engine.contribute(learning, { agentId });
- return {
- content: [
- {
- type: "text",
- text: `Recorded. +${r.nodesCreated} new entities, ${r.nodesUpdated} reinforced; +${r.edgesCreated} new relationships, ${r.edgesUpdated} reinforced.`,
- },
- ],
- };
- },
- );
-
- server.registerTool(
- "context_ingest",
- {
- title: "Ingest a document",
- description: "Ingest a document (raw text) into the shared context graph.",
- inputSchema: {
- text: z.string().describe("The document text to ingest."),
- title: z.string().optional().describe("A title for the document."),
- },
- },
- async ({ text, title }) => {
- const r = await engine.ingest(text, { title });
- return {
- content: [
- {
- type: "text",
- text: r.skipped
- ? "Document already ingested; skipped."
- : `Ingested "${r.title}": ${r.chunks} chunks, +${r.nodesCreated} entities, +${r.edgesCreated} relationships.`,
- },
- ],
- };
- },
- );
-
- server.registerTool(
- "context_ingest_file",
- {
- title: "Ingest a file (incl. PDFs)",
- description:
- "Ingest one or more files from disk into the shared context graph. PDF files are parsed to text automatically. Accepts absolute paths.",
- inputSchema: {
- paths: z
- .array(z.string())
- .min(1)
- .describe("Absolute file paths to ingest (e.g. PDFs)."),
- },
- },
- async ({ paths }) => {
- const lines: string[] = [];
- for (const path of paths) {
- try {
- const r = await engine.ingestFile(path);
- lines.push(
- r.skipped
- ? `• ${r.title}: already ingested, skipped`
- : `✓ ${r.title}: ${r.chunks} chunks, +${r.nodesCreated} entities (${r.nodesUpdated} reinforced), +${r.edgesCreated} relationships`,
- );
- } catch (err) {
- lines.push(`✗ ${path}: ${err instanceof Error ? err.message : String(err)}`);
- }
- }
- return { content: [{ type: "text", text: lines.join("\n") }] };
- },
- );
-
- server.registerTool(
- "context_ingest_dir",
- {
- title: "Ingest a directory",
- description:
- "Ingest every supported document (.pdf, .md, .markdown, .txt) in a directory, recursively, into the shared context graph. Point this at a folder of docs and it builds the graph in one call.",
- inputSchema: {
- dir: z.string().describe("Absolute path to the directory of documents to ingest."),
- extensions: z
- .array(z.string())
- .optional()
- .describe('File extensions to include (e.g. [".md", ".rst"]). Default: .pdf .md .markdown .txt'),
- },
- },
- async ({ dir, extensions }, extra) => {
- // Report progress per file. If the client supplied a progressToken (and
- // resets its request timeout on progress, as Claude Code does), this keeps
- // long multi-file ingests from tripping the default 60s tool timeout.
- const progressToken = extra?._meta?.progressToken;
- const onProgress = progressToken
- ? ({ index, total, file }: { index: number; total: number; file: string }) => {
- void extra.sendNotification({
- method: "notifications/progress",
- params: {
- progressToken,
- progress: index,
- total,
- message: `Ingesting ${file.split("/").pop()} (${index + 1}/${total})`,
- },
- });
- }
- : undefined;
- const results = await engine.ingestDir(dir, { extensions, onProgress });
- if (results.length === 0) {
- return { content: [{ type: "text", text: `No supported files found under ${dir}.` }] };
- }
- const created = results.reduce((a, r) => a + r.nodesCreated, 0);
- const edges = results.reduce((a, r) => a + r.edgesCreated, 0);
- const lines = results.map((r) =>
- r.skipped ? `• ${r.title}: skipped (already ingested)` : `✓ ${r.title}: +${r.nodesCreated} entities, +${r.edgesCreated} relationships`,
- );
- lines.push(`\nTotal: ${results.length} files → +${created} entities, +${edges} relationships.`);
- return { content: [{ type: "text", text: lines.join("\n") }] };
- },
- );
-
- server.registerTool(
- "context_ingest_repo",
- {
- title: "Ingest a code repository (as summaries)",
- description:
- "Ingest a code repository into the shared context graph. Each source file is summarized " +
- "into prose (purpose, key exports, dependencies, design decisions) and the summaries are " +
- "ingested — raw code is never fed to the extractor. Incremental: re-running only " +
- "re-summarizes files whose content changed.",
- inputSchema: {
- dir: z.string().describe("Absolute path to the repository root."),
- extensions: z
- .array(z.string())
- .optional()
- .describe('File extensions to treat as code (default: common languages, e.g. ".ts", ".py", ".go").'),
- },
- },
- async ({ dir, extensions }, extra) => {
- const progressToken = extra?._meta?.progressToken;
- const onProgress = progressToken
- ? ({ phase, index, total, file }: { phase: string; index: number; total: number; file: string }) => {
- void extra.sendNotification({
- method: "notifications/progress",
- params: {
- progressToken,
- progress: index,
- total,
- message: `${phase === "summarize" ? "Summarizing" : "Ingesting"} ${file} (${index + 1}/${total})`,
- },
- });
- }
- : undefined;
- const r = await engine.ingestRepo(dir, { extensions, onProgress });
- const lines = [
- `Repo ingested: ${r.files} code files → ${r.summarized} summarized, ${r.cached} unchanged (cache hits).`,
- ...r.modules.map((m) =>
- m.skipped
- ? `• ${m.title}: unchanged, skipped`
- : `✓ ${m.title}: ${m.chunks} chunks, +${m.nodesCreated} entities, +${m.edgesCreated} relationships`,
- ),
- ...r.errors.map((e) => `✗ ${e}`),
- ];
- return { content: [{ type: "text", text: lines.join("\n") }] };
- },
- );
-
- server.registerTool(
- "context_watch_dir",
- {
- title: "Watch a folder (evolving graph)",
- description:
- "Connect a folder to the graph and keep it evolving: existing documents are ingested now, " +
- "and any file added or edited later is re-ingested automatically for as long as this session " +
- "lives. The folder is registered, so `context-graph watch` (or `context-graph serve`) " +
- "resumes it in future sessions.",
- inputSchema: {
- dir: z.string().describe("Absolute path to the folder to watch."),
- extensions: z
- .array(z.string())
- .optional()
- .describe('File extensions to include (e.g. [".md", ".rst"]). Default: .pdf .md .markdown .txt'),
- },
- },
- async ({ dir, extensions }, extra) => {
- const w = deps.getWatcher();
- // Extensions are fixed per watcher process; a custom set is recorded in
- // the registry and takes effect when a daemon starts from it.
- engine.addWatchedDir(dir, extensions);
-
- const progressToken = extra?._meta?.progressToken;
- const lines: string[] = [];
- let ingested = 0;
- let queued = 0;
- deps.setProgressSink((event) => {
- if (event.type === "queued") queued++;
- if (event.type === "ingested") {
- ingested++;
- lines.push(
- event.result.skipped
- ? `• ${event.result.title}: unchanged, skipped`
- : `✓ ${event.result.title}: +${event.result.nodesCreated} entities, +${event.result.edgesCreated} relationships`,
- );
- if (progressToken) {
- void extra.sendNotification({
- method: "notifications/progress",
- params: {
- progressToken,
- progress: ingested,
- total: queued,
- message: `Ingesting ${event.file.split("/").pop()} (${ingested}/${queued})`,
- },
- });
- }
- }
- if (event.type === "error") lines.push(`✗ ${event.file}: ${event.error}`);
- });
- try {
- await w.add(dir);
- await w.idle();
- } finally {
- deps.setProgressSink(undefined);
- }
- lines.push(
- `\nWatching ${dir} — new and edited files will be ingested automatically while this session lives.`,
- );
- return { content: [{ type: "text", text: lines.join("\n") }] };
- },
- );
-
- server.registerTool(
- "context_unwatch_dir",
- {
- title: "Stop watching a folder",
- description:
- "Stop auto-ingesting a folder and remove it from the watch registry. Knowledge already " +
- "learned from it stays in the graph.",
- inputSchema: {
- dir: z.string().describe("Absolute path of the watched folder to disconnect."),
- },
- },
- async ({ dir }) => {
- await peekWatcher()?.remove(dir);
- const removed = engine.removeWatchedDir(dir);
- return {
- content: [
- {
- type: "text",
- text: removed
- ? `Stopped watching ${dir}. Its knowledge remains in the graph.`
- : `${dir} was not being watched.`,
- },
- ],
- };
- },
- );
-
- server.registerTool(
- "context_watch_status",
- {
- title: "Watched folders",
- description:
- "List folders connected for auto-watching: registered folders, which are live in this session, and the ingest queue size.",
- inputSchema: {},
- },
- async () => {
- const registered = engine.listWatchedDirs();
- const w = peekWatcher();
- const live = new Set(w?.dirs() ?? []);
- if (registered.length === 0 && live.size === 0) {
- return {
- content: [
- { type: "text", text: "No watched folders. Connect one with context_watch_dir." },
- ],
- };
- }
- const lines = registered.map(
- (wd) => `${live.has(wd.dir) ? "● live" : "○ registered"} ${wd.dir}`,
- );
- for (const dir of live) {
- if (!registered.some((wd) => wd.dir === dir)) lines.push(`● live (unregistered) ${dir}`);
- }
- const pending = w?.pendingCount() ?? 0;
- if (pending > 0) lines.push(`\n${pending} file(s) queued for ingestion.`);
- return { content: [{ type: "text", text: lines.join("\n") }] };
- },
- );
-
- server.registerTool(
- "context_export",
- {
- title: "Export the graph as HTML",
- description:
- "Write the entire context graph to a self-contained, interactive HTML file that can be opened in a browser to visualize entities and relationships.",
- inputSchema: {
- path: z.string().describe("Absolute path to write the HTML file to (e.g. /tmp/context-graph.html)."),
- },
- },
- async ({ path }) => {
- const g = await engine.exportGraph();
- writeFileSync(path, toHtml(g));
- return {
- content: [
- {
- type: "text",
- text: `Wrote graph (${g.nodes.length} entities, ${g.edges.length} relationships) to ${path}. Open it in a browser to explore.`,
- },
- ],
- };
- },
- );
-
- server.registerTool(
- "context_stats",
- {
- title: "Graph statistics",
- description: "Report how much knowledge the shared context graph currently holds.",
- inputSchema: {},
- },
- async () => {
- const s = await engine.stats();
- return {
- content: [
- {
- type: "text",
- text: `documents: ${s.documents}, entities: ${s.nodes}, relationships: ${s.edges}, source passages: ${s.chunks}`,
- },
- ],
- };
- },
- );
-
- server.registerTool(
- "context_sync",
- {
- title: "Sync the graph (git mode)",
- description:
- "Team sync (Mode A): import + re-merge the committed graph file, then write the merged graph back so it can be committed. Idempotent — safe to run repeatedly. Uses graph.jsonl next to the db unless a path is given.",
- inputSchema: {
- file: z
- .string()
- .optional()
- .describe("Path to the graph JSONL file (default: graph.jsonl next to the db)."),
- },
- },
- async ({ file }) => {
- const path = file ?? engine.graphFilePath;
- if (!path) {
- return {
- content: [{ type: "text", text: "This graph is in-memory and can't be synced to a file." }],
- };
- }
- const lines: string[] = [];
- if (existsSync(path)) {
- const r = await engine.importJsonl(readFileSync(path, "utf8"));
- for (const w of r.warnings) lines.push(`⚠ ${w}`);
- lines.push(
- `Merged in: +${r.nodesCreated} entities (${r.nodesUpdated} reinforced), ` +
- `+${r.edgesCreated} relationships (${r.edgesUpdated} reinforced).`,
- );
- }
- writeFileSync(path, await engine.exportJsonl());
- const s = await engine.stats();
- lines.push(`Wrote merged graph (${s.nodes} entities, ${s.edges} relationships) to ${path}.`);
- return { content: [{ type: "text", text: lines.join("\n") }] };
- },
- );
-
- return server;
-}
-
-/** Standalone `context-graph-mcp` (stdio) entry point. */
-async function main(): Promise<void> {
- const engine = new ContextGraphEngine();
-
- // One lazily-created watcher for the life of this MCP process. Folders added
- // via context_watch_dir keep updating the graph in the background for as long
- // as the client session (and thus this process) lives.
- let watcher: GraphWatcher | undefined;
- let progressSink: ((event: WatchEvent) => void) | undefined;
- const getWatcher = (): GraphWatcher =>
- (watcher ??= new GraphWatcher(engine, {
- onEvent: (event) => {
- // stderr only — stdout is the JSON-RPC channel.
- if (event.type === "error") console.error(`watch: ✗ ${event.file}: ${event.error}`);
- else if (event.type === "ingested" && !event.result.skipped) {
- console.error(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);
- }
- progressSink?.(event);
- },
- }));
-
- const server = createContextGraphMcpServer({
- engine,
- getWatcher,
- peekWatcher: () => watcher,
- setProgressSink: (sink) => {
- progressSink = sink;
- },
- });
-
- const transport = new StdioServerTransport();
- await server.connect(transport);
- // Log to stderr so we don't corrupt the stdio JSON-RPC channel.
- console.error("context-graph-engine MCP server running on stdio");
-
- // Opt-in: resume registered folders in the background. Off by default —
- // every client session spawns its own MCP process, and silent LLM spend on
- // file saves should be something the user chose.
- if (process.env.CONTEXT_GRAPH_AUTOWATCH === "1") {
- const dirs = engine.listWatchedDirs();
- if (dirs.length > 0) {
- const w = getWatcher();
- for (const wd of dirs) {
- w.add(wd.dir).catch((err) =>
- console.error(`watch: ✗ ${wd.dir}: ${err instanceof Error ? err.message : String(err)}`),
- );
- }
- console.error(`auto-watching ${dirs.length} registered folder(s)`);
- }
- }
-}
-
-// Run the stdio server only when invoked directly (as the `context-graph-mcp`
-// bin), not when imported by `serve`.
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
- main().catch((err) => {
- console.error(err);
- process.exit(1);
- });
-}
diff --git a/src/retrieval/retriever.ts b/src/retrieval/retriever.ts
deleted file mode 100644
index dcb79713..00000000
--- a/src/retrieval/retriever.ts
+++ /dev/null
@@ -1,149 +0,0 @@
-import type { GraphStore } from "../graph/store.js";
-import type { Embedder } from "../ai/providers.js";
-import type {
- ContextBundle,
- GraphEdge,
- GraphNode,
- RetrievedChunk,
- RetrievedNode,
-} from "../graph/types.js";
-import { topK } from "../util/similarity.js";
-
-export interface RetrieveOptions {
- /** Max entities to surface via direct semantic match. Default: 8. */
- maxNodes?: number;
- /** Max supporting source passages to include. Default: 6. */
- maxChunks?: number;
- /** Whether to expand one hop out from the semantically-matched nodes. Default: true. */
- expand?: boolean;
- /** Drop semantic node hits scoring below this cosine value. Default: 0.15. */
- minNodeScore?: number;
-}
-
-/**
- * Read the graph for a query: semantic-match entities and passages, then expand
- * one hop across relationships to pull in connected context. Returns a
- * structured {@link ContextBundle} plus a ready-to-inject `prompt` rendering.
- */
-export async function retrieve(
- store: GraphStore,
- embedder: Embedder,
- query: string,
- opts: RetrieveOptions = {},
-): Promise<ContextBundle> {
- const maxNodes = opts.maxNodes ?? 8;
- const maxChunks = opts.maxChunks ?? 6;
- const expand = opts.expand ?? true;
- const minNodeScore = opts.minNodeScore ?? 0.15;
-
- const [queryVec] = await embedder.embed([query]);
-
- // 1) Direct semantic matches over entities.
- const nodeHits = topK(queryVec, await store.allEmbeddedNodes(), (n) => n.embedding, maxNodes)
- .filter((h) => h.score >= minNodeScore);
-
- const nodesById = new Map<string, RetrievedNode>();
- for (const { item, score } of nodeHits) {
- nodesById.set(item.id, { ...item, score, via: "semantic" });
- }
-
- // 2) One-hop graph expansion from the matched entities.
- let edges: GraphEdge[] = [];
- if (expand && nodesById.size > 0) {
- const seedIds = [...nodesById.keys()];
- edges = await store.edgesForNodes(seedIds);
-
- const neighborIds = new Set<string>();
- for (const e of edges) {
- if (!nodesById.has(e.sourceId)) neighborIds.add(e.sourceId);
- if (!nodesById.has(e.targetId)) neighborIds.add(e.targetId);
- }
- const neighbors = await store.getNodesByIds([...neighborIds]);
- const seedScore = new Map(nodeHits.map((h) => [h.item.id, h.score]));
- for (const n of neighbors) {
- // Score an expanded node by the best edge that reached it.
- const best = bestEdgeScore(n.id, edges, seedScore);
- nodesById.set(n.id, { ...n, score: best, via: "expanded" });
- }
- }
-
- // Keep only edges whose endpoints are both in the final node set.
- const finalNodes = [...nodesById.values()].sort((a, b) => b.score - a.score);
- const nodeIdSet = new Set(finalNodes.map((n) => n.id));
- edges = edges.filter((e) => nodeIdSet.has(e.sourceId) && nodeIdSet.has(e.targetId));
-
- // 3) Supporting source passages.
- const chunkHits = topK(queryVec, await store.allEmbeddedChunks(), (c) => c.embedding, maxChunks);
- const chunks: RetrievedChunk[] = await Promise.all(
- chunkHits.map(async ({ item, score }) => ({
- ...item,
- score,
- documentTitle: await store.documentTitle(item.documentId),
- })),
- );
-
- const bundle: ContextBundle = {
- query,
- nodes: finalNodes,
- edges,
- chunks,
- prompt: "",
- };
- bundle.prompt = renderPrompt(bundle);
- return bundle;
-}
-
-function bestEdgeScore(
- nodeId: string,
- edges: GraphEdge[],
- seedScore: Map<string, number>,
-): number {
- let best = 0;
- for (const e of edges) {
- const other =
- e.sourceId === nodeId ? e.targetId : e.targetId === nodeId ? e.sourceId : null;
- if (other === null) continue;
- const seed = seedScore.get(other);
- if (seed === undefined) continue;
- best = Math.max(best, seed * e.confidence);
- }
- return best;
-}
-
-/** Render a bundle into a compact, LLM-friendly context block. */
-export function renderPrompt(bundle: ContextBundle): string {
- const lines: string[] = [];
- lines.push(`# Context for: ${bundle.query}`);
-
- if (bundle.nodes.length > 0) {
- lines.push("\n## Relevant entities");
- for (const n of bundle.nodes) {
- const conf = `${Math.round(n.confidence * 100)}%`;
- lines.push(`- **${n.name}** (${n.type}, confidence ${conf}): ${n.summary}`);
- }
- }
-
- if (bundle.edges.length > 0) {
- const byId = new Map(bundle.nodes.map((n) => [n.id, n.name]));
- lines.push("\n## Relationships");
- for (const e of bundle.edges) {
- const s = byId.get(e.sourceId) ?? e.sourceId;
- const t = byId.get(e.targetId) ?? e.targetId;
- const desc = e.description ? ` — ${e.description}` : "";
- lines.push(`- ${s} —[${e.relation}]→ ${t}${desc}`);
- }
- }
-
- if (bundle.chunks.length > 0) {
- lines.push("\n## Supporting sources");
- for (const c of bundle.chunks) {
- lines.push(`- (${c.documentTitle}) ${c.text.replace(/\s+/g, " ").slice(0, 400)}`);
- }
- }
-
- if (bundle.nodes.length === 0 && bundle.chunks.length === 0) {
- lines.push("\n_No relevant context found in the graph yet._");
- }
-
- return lines.join("\n");
-}
diff --git a/src/serve.ts b/src/serve.ts
deleted file mode 100644
index 46afdd31..00000000
--- a/src/serve.ts
+++ /dev/null
@@ -1,288 +0,0 @@
-#!/usr/bin/env node
-/**
- * `context-graph serve` — the whole engine in one process on one port.
- *
- * Runs a single {@link ContextGraphEngine}, a single {@link GraphWatcher}, the
- * web UI, and the MCP server (over Streamable HTTP) together. This is the
- * supported way to run everything at once: because there is exactly one engine
- * and one watcher, it sidesteps the "one watcher per db" footgun you hit when
- * running `context-graph-web` and a `context-graph watch` daemon side by side
- * (concurrent writers whose merges aren't transactional).
- *
- * Routing on the single HTTP server:
- * - `/mcp` → MCP over Streamable HTTP (POST to call, GET to stream)
- * - everything else → the web UI + `/api/*` (see {@link createWebApp})
- *
- * Env mirrors `context-graph-web`: CONTEXT_GRAPH_DB, PORT (4680), HOST
- * (127.0.0.1), CONTEXT_GRAPH_WEB_TOKEN (also gates `/mcp` when exposed).
- */
-import "dotenv/config";
-import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
-import { randomUUID } from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { resolve } from "node:path";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { ContextGraphEngine } from "./engine.js";
-import { GraphWatcher, type WatchEvent } from "./watch.js";
-import { resolveConfig, type EngineConfig } from "./ai/providers.js";
-import { createWebApp } from "./web.js";
-import { createContextGraphMcpServer } from "./mcp.js";
-
-export interface ServeOptions {
- /** Host to bind (default 127.0.0.1; a token guards /api and /mcp when non-loopback). */
- host?: string;
- /** Port to bind (default 4680; 0 picks a free port — handy for tests). */
- port?: number;
- /** Resume registered watch folders (and watch `dirs`) at startup. Default true. */
- watch?: boolean;
- /** Extra folders to register and watch, on top of the persisted registry. */
- dirs?: string[];
- /** Extensions the watcher ingests (default {@link DOC_EXTENSIONS}). */
- extensions?: string[];
- /** Engine config override (tests pass `:memory:` + fake providers here). */
- engineConfig?: EngineConfig;
- /** Provide an engine directly (tests); takes precedence over `engineConfig`. */
- engine?: ContextGraphEngine;
-}
-
-export interface RunningServer {
- /** Local URL the server is listening on. */
- url: string;
- /** The bound port (resolved even when `port: 0` was requested). */
- port: number;
- /** The shared engine, for tests/embedding. */
- engine: ContextGraphEngine;
- /** Stop everything: MCP transports, watcher, HTTP server, then the engine. */
- close: () => Promise<void>;
-}
-
-/** Read and JSON-parse a request body (for MCP POST bodies). */
-function readJson(req: IncomingMessage, maxBytes = 50_000_000): Promise<unknown> {
- return new Promise((res, rej) => {
- let data = "";
- req.on("data", (c) => {
- data += c;
- if (data.length > maxBytes) rej(new Error("body too large"));
- });
- req.on("end", () => {
- try {
- res(data ? JSON.parse(data) : undefined);
- } catch (e) {
- rej(e);
- }
- });
- req.on("error", rej);
- });
-}
-
-/**
- * Log a watcher event. A `default` branch deliberately swallows event types this
- * command doesn't know about, so a new {@link WatchEvent} variant (e.g. a
- * significance-skip added elsewhere) can never break `serve`.
- */
-function logWatchEvent(event: WatchEvent): void {
- switch (event.type) {
- case "ingested":
- if (!event.result.skipped) {
- console.log(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);
- }
- break;
- case "deleted": {
- const p = event.pruned;
- console.log(
- p
- ? `watch: • ${event.file} deleted (−${p.nodesRemoved} entities, −${p.edgesRemoved} relationships)`
- : `watch: • ${event.file} deleted`,
- );
- break;
- }
- case "error":
- console.error(`watch: ✗ ${event.file}: ${event.error}`);
- break;
- default:
- break;
- }
-}
-
-/**
- * Start the unified server. Resolves once it is listening; call the returned
- * {@link RunningServer.close} to shut it down.
- */
-export async function startServe(opts: ServeOptions = {}): Promise<RunningServer> {
- const host = opts.host ?? process.env.HOST ?? "127.0.0.1";
- const wantPort = opts.port ?? Number(process.env.PORT ?? 4680);
- const engineConfig = opts.engineConfig ?? {};
- const cfg = resolveConfig(engineConfig);
- const engine = opts.engine ?? new ContextGraphEngine(engineConfig);
-
- // One shared watcher. Its events are logged and also forwarded to whatever
- // MCP tool call is currently reporting catch-up progress.
- let currentProgressSink: ((event: WatchEvent) => void) | undefined;
- const watcher = new GraphWatcher(engine, {
- extensions: opts.extensions,
- onEvent: (event) => {
- logWatchEvent(event);
- currentProgressSink?.(event);
- },
- });
-
- const app = createWebApp({
- engine,
- cfg,
- host,
- port: wantPort,
- ensureWatcher: () => watcher,
- getWatcher: () => watcher,
- });
-
- // --- MCP over Streamable HTTP: one transport (and server) per client session ---
- const transports: Record<string, StreamableHTTPServerTransport> = {};
-
- async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<void> {
- // Same browser hardening as the web handler: on a loopback bind, reject
- // foreign Host/Origin headers (DNS-rebinding / CSRF) before doing anything.
- // /mcp routes around app.handler, so this guard must be applied explicitly.
- if (app.rejectForeignRequest(req, res)) return;
-
- // Gate /mcp with the same bearer token the web /api uses when exposed.
- if (app.exposed && !app.isAuthorized(req)) {
- res.writeHead(401, { "content-type": "application/json" });
- res.end(JSON.stringify({ error: "access token required" }));
- return;
- }
-
- const sid = req.headers["mcp-session-id"] as string | undefined;
-
- if (req.method === "POST") {
- const body = await readJson(req);
- let transport = sid ? transports[sid] : undefined;
- if (!transport) {
- // A new session must open with an `initialize` request and no session id.
- if (sid || !isInitializeRequest(body)) {
- res.writeHead(400, { "content-type": "application/json" });
- res.end(
- JSON.stringify({
- jsonrpc: "2.0",
- error: { code: -32000, message: "Bad Request: no valid session" },
- id: null,
- }),
- );
- return;
- }
- transport = new StreamableHTTPServerTransport({
- sessionIdGenerator: () => randomUUID(),
- onsessioninitialized: (id) => {
- transports[id] = transport!;
- },
- });
- transport.onclose = () => {
- const id = transport!.sessionId;
- if (id) delete transports[id];
- };
- const mcp = createContextGraphMcpServer({
- engine,
- getWatcher: () => watcher,
- peekWatcher: () => watcher,
- setProgressSink: (sink) => {
- currentProgressSink = sink;
- },
- });
- await mcp.connect(transport);
- }
- await transport.handleRequest(req, res, body);
- return;
- }
-
- // GET (SSE stream) and DELETE (end session) require an established session.
- if (!sid || !transports[sid]) {
- res.writeHead(400, { "content-type": "application/json" });
- res.end(JSON.stringify({ error: "invalid or missing mcp-session-id" }));
- return;
- }
- await transports[sid].handleRequest(req, res);
- }
-
- const server: Server = createServer((req, res) => {
- const url = new URL(req.url ?? "/", `http://localhost:${wantPort}`);
- if (url.pathname === "/mcp") {
- void handleMcp(req, res).catch((e) => {
- if (!res.headersSent) {
- res.writeHead(500, { "content-type": "application/json" });
- res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
- }
- });
- return;
- }
- void app.handler(req, res);
- });
-
- // Resume registered watch folders (and any passed on the CLI) in the
- // background — the catch-up scan is a cheap hash-dedup pass for already-known
- // content, so we don't hold up listening on it.
- if (opts.watch !== false) {
- for (const d of opts.dirs ?? []) engine.addWatchedDir(d, opts.extensions);
- const registered = engine.listWatchedDirs();
- for (const wd of registered) {
- watcher.add(wd.dir).catch((err) =>
- console.error(`watch: ✗ ${wd.dir}: ${err instanceof Error ? err.message : String(err)}`),
- );
- }
- }
-
- await new Promise<void>((res) => server.listen(wantPort, host, res));
- const addr = server.address();
- const port = typeof addr === "object" && addr ? addr.port : wantPort;
- const url = `http://${host}:${port}`;
-
- const close = async (): Promise<void> => {
- for (const t of Object.values(transports)) {
- try {
- await t.close();
- } catch {
- /* ignore */
- }
- }
- await watcher.close();
- await new Promise<void>((res) => server.close(() => res()));
- await engine.close();
- };
-
- return { url, port, engine, close };
-}
-
-/** Standalone `context-graph-serve` entry point. */
-async function main(): Promise<void> {
- const running = await startServe();
- const cfg = resolveConfig();
- const watchedCount = running.engine.listWatchedDirs().length;
-
- console.log(`Context Graph → ${running.url}`);
- console.log(` web UI: ${running.url}`);
- console.log(` MCP (HTTP): ${running.url}/mcp`);
- console.log(` graph db: ${resolve(cfg.dbPath)}`);
- console.log(
- ` extraction: ${cfg.openrouterApiKey && !cfg.forceLocal ? `openrouter (${cfg.openrouterModel})` : `ollama (${cfg.ollamaModel})`}`,
- );
- console.log(` embeddings: ${cfg.openaiApiKey && !cfg.forceLocal ? "openai" : "local"}`);
- if (watchedCount > 0) console.log(` watching: ${watchedCount} registered folder(s)`);
-
- let stopping = false;
- const stop = async () => {
- if (stopping) return;
- stopping = true;
- console.log("\nstopping…");
- await running.close();
- process.exit(0);
- };
- process.on("SIGINT", () => void stop());
- process.on("SIGTERM", () => void stop());
-}
-
-// Run only when invoked directly (the `context-graph-serve` bin / `serve` cmd).
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
- main().catch((err) => {
- console.error(err);
- process.exit(1);
- });
-}
diff --git a/src/util/similarity.ts b/src/util/similarity.ts
deleted file mode 100644
index 27dad453..00000000
--- a/src/util/similarity.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-/** Cosine similarity of two equal-length vectors. Returns a value in [-1, 1]. */
-export function cosineSimilarity(a: number[], b: number[]): number {
- if (a.length !== b.length || a.length === 0) return 0;
- let dot = 0;
- let normA = 0;
- let normB = 0;
- for (let i = 0; i < a.length; i++) {
- dot += a[i] * b[i];
- normA += a[i] * a[i];
- normB += b[i] * b[i];
- }
- if (normA === 0 || normB === 0) return 0;
- return dot / (Math.sqrt(normA) * Math.sqrt(normB));
-}
-
-/** Rank `items` by cosine similarity of `getVec(item)` to `query`, returning the top `k`. */
-export function topK<T>(
- query: number[],
- items: T[],
- getVec: (item: T) => number[] | undefined,
- k: number,
-): Array<{ item: T; score: number }> {
- const scored: Array<{ item: T; score: number }> = [];
- for (const item of items) {
- const vec = getVec(item);
- if (!vec) continue;
- scored.push({ item, score: cosineSimilarity(query, vec) });
- }
- scored.sort((x, y) => y.score - x.score);
- return scored.slice(0, k);
-}
diff --git a/src/watch.ts b/src/watch.ts
deleted file mode 100644
index c2613cf9..00000000
--- a/src/watch.ts
+++ /dev/null
@@ -1,340 +0,0 @@
-/**
- * Auto-watch: keep the graph evolving as connected folders change.
- *
- * A {@link GraphWatcher} watches document folders and keeps the graph tracking
- * them without manual re-runs of `ingest-dir`. It is *smart* about change in
- * two ways:
- *
- * - **Significance gate.** A save that only reformats a file (whitespace,
- * blank lines, line endings) leaves its normalized content unchanged, so it
- * is skipped without an LLM call. Only meaningful edits are re-ingested.
- * - **Pruning on delete.** Deleting a watched file forgets what it taught: its
- * documents are removed and the observations they contributed are pruned, so
- * facts that lose their last source decay out of the graph (see
- * {@link ContextGraphEngine.forgetSource}). Facts still supported elsewhere
- * survive.
- *
- * Rapid saves are absorbed by a per-file debounce, and files are processed by a
- * single serial worker — each ingest already fans out to concurrent LLM
- * extraction internally, so one document at a time keeps spend predictable.
- * Deletes flow through the same worker, so a delete can never race an in-flight
- * ingest of the same file.
- */
-import { watch, type FSWatcher } from "chokidar";
-import { readFileSync, type Stats } from "node:fs";
-import { basename, resolve, sep } from "node:path";
-import type { ContextGraphEngine, IngestResult, PruneResult } from "./engine.js";
-import { DOC_EXTENSIONS, isIngestablePath, shouldIgnorePath, walkDir } from "./ingest/fs.js";
-import { isPdfPath } from "./ingest/pdf.js";
-import { contentHash } from "./util/id.js";
-
-export interface WatchOptions {
- /** Extensions to ingest. Default: {@link DOC_EXTENSIONS}. */
- extensions?: string[];
- /** Quiet time after a file's last event before it is ingested. Default 1500ms. */
- debounceMs?: number;
- /** Catch up on the folder's current contents when it is added. Default true. */
- initialScan?: boolean;
- /** Called for every lifecycle event, for progress UIs and logging. */
- onEvent?: (event: WatchEvent) => void;
-}
-
-export type WatchEvent =
- | { type: "watching"; dir: string; files: number }
- | { type: "queued"; file: string; reason: "add" | "change" | "initial" }
- | { type: "ingested"; file: string; result: IngestResult }
- | { type: "deleted"; file: string; pruned?: PruneResult & { documentsRemoved: number } }
- | { type: "error"; file: string; error: string };
-
-/**
- * Watches folders and streams their document changes into an engine.
- *
- * One watcher process per db is the supported mode — concurrent graph writes
- * from multiple processes are safe (WAL) but their merges are not transactional.
- */
-export class GraphWatcher {
- private watchers = new Map<string, FSWatcher>();
- private debounces = new Map<string, NodeJS.Timeout>();
- private pending = new Set<string>();
- /** Deleted files awaiting a prune pass, drained by the same serial worker. */
- private pendingDeletes = new Set<string>();
- /** Per-path normalized-content hash of the last ingested version (significance gate). */
- private contentHashes = new Map<string, string>();
- private inFlight?: string;
- private working = false;
- private closed = false;
- private idleResolvers: Array<() => void> = [];
-
- constructor(
- private engine: ContextGraphEngine,
- private opts: WatchOptions = {},
- ) {}
-
- private get extensions(): string[] {
- return this.opts.extensions ?? DOC_EXTENSIONS;
- }
-
- private get debounceMs(): number {
- return this.opts.debounceMs ?? 1500;
- }
-
- private emit(event: WatchEvent): void {
- this.opts.onEvent?.(event);
- }
-
- /** Watch a folder. Resolves once watching is established (and the initial catch-up scan is queued). */
- async add(dir: string): Promise<void> {
- const root = resolve(dir);
- if (this.watchers.has(root)) return;
-
- const watcher = watch(root, {
- ignored: (path: string, stats?: Stats) => shouldIgnorePath(path, root, stats),
- ignoreInitial: true,
- // Don't ingest a file mid-write: wait for its size to hold still, so a
- // large PDF that takes a moment to save arrives whole.
- awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
- });
- this.watchers.set(root, watcher);
-
- const onFile = (reason: "add" | "change") => (path: string) => {
- if (this.closed || !isIngestablePath(path, root, this.extensions)) return;
- this.debounce(path, reason);
- };
- watcher.on("add", onFile("add"));
- watcher.on("change", onFile("change"));
- watcher.on("unlink", (path: string) => {
- if (this.closed) return;
- // Only files we would have ingested are worth forgetting. (unlink has no
- // stats to hand shouldIgnorePath, so match on extension + ignore rules.)
- if (!this.extensions.some((e) => path.toLowerCase().endsWith(e))) return;
- if (shouldIgnorePath(path, root)) return;
- // The file is gone: cancel any queued (re-)ingest and queue a prune.
- const timer = this.debounces.get(path);
- if (timer) clearTimeout(timer);
- this.debounces.delete(path);
- this.pending.delete(path);
- this.pendingDeletes.add(path);
- this.kick();
- });
- watcher.on("error", (err) => {
- this.emit({ type: "error", file: root, error: err instanceof Error ? err.message : String(err) });
- });
-
- await new Promise<void>((res, rej) => {
- watcher.once("ready", res);
- watcher.once("error", rej);
- });
-
- let files = 0;
- if (this.opts.initialScan !== false) {
- for (const file of walkDir(root)) {
- if (!isIngestablePath(file, root, this.extensions)) continue;
- files++;
- this.pending.add(file);
- this.emit({ type: "queued", file, reason: "initial" });
- }
- this.kick();
- }
- this.emit({ type: "watching", dir: root, files });
- }
-
- /** Stop watching a folder and drop its queued (not in-flight) files. */
- async remove(dir: string): Promise<void> {
- const root = resolve(dir);
- const watcher = this.watchers.get(root);
- if (!watcher) return;
- this.watchers.delete(root);
- await watcher.close();
- const under = (path: string) => path === root || path.startsWith(root + sep);
- for (const [path, timer] of this.debounces) {
- if (under(path)) {
- clearTimeout(timer);
- this.debounces.delete(path);
- }
- }
- for (const path of this.pending) {
- if (under(path)) this.pending.delete(path);
- }
- for (const path of this.pendingDeletes) {
- if (under(path)) this.pendingDeletes.delete(path);
- }
- this.checkIdle();
- }
-
- /** Folders currently being watched. */
- dirs(): string[] {
- return [...this.watchers.keys()];
- }
-
- /** Files queued (ingest or delete) or being processed right now. */
- pendingCount(): number {
- return (
- this.pending.size +
- this.pendingDeletes.size +
- this.debounces.size +
- (this.inFlight ? 1 : 0)
- );
- }
-
- /** Resolves once every queued and debouncing file has been ingested. */
- idle(): Promise<void> {
- if (this.pendingCount() === 0) return Promise.resolve();
- return new Promise((res) => this.idleResolvers.push(res));
- }
-
- /** Stop watching everything, drop queued work, and wait out the in-flight ingest. */
- async close(): Promise<void> {
- this.closed = true;
- await Promise.all([...this.watchers.values()].map((w) => w.close()));
- this.watchers.clear();
- for (const timer of this.debounces.values()) clearTimeout(timer);
- this.debounces.clear();
- this.pending.clear();
- this.pendingDeletes.clear();
- await this.idle();
- }
-
- private debounce(path: string, reason: "add" | "change"): void {
- const existing = this.debounces.get(path);
- if (existing) clearTimeout(existing);
- else this.emit({ type: "queued", file: path, reason });
- this.debounces.set(
- path,
- setTimeout(() => {
- this.debounces.delete(path);
- if (this.closed) return this.checkIdle();
- // A fresh add/change wins over a pending delete for the same path
- // (e.g. an editor's delete-then-rename save).
- this.pendingDeletes.delete(path);
- this.pending.add(path);
- this.kick();
- }, this.debounceMs),
- );
- }
-
- private checkIdle(): void {
- if (this.pendingCount() > 0) return;
- const resolvers = this.idleResolvers;
- this.idleResolvers = [];
- for (const res of resolvers) res();
- }
-
- private kick(): void {
- if (this.working) return;
- this.working = true;
- void this.work().finally(() => {
- this.working = false;
- this.checkIdle();
- });
- }
-
- private async work(): Promise<void> {
- for (;;) {
- // Drain deletes ahead of ingests so a removed file's knowledge is
- // forgotten promptly, before we spend effort re-reading anything.
- const del = this.takeNextDelete();
- if (del) {
- this.inFlight = del;
- try {
- const pruned = await this.engine.forgetSource(del);
- this.contentHashes.delete(del);
- this.emit({ type: "deleted", file: del, pruned });
- } catch (err) {
- this.emit({ type: "error", file: del, error: err instanceof Error ? err.message : String(err) });
- } finally {
- this.inFlight = undefined;
- }
- continue;
- }
-
- const next = this.takeNext();
- if (!next) break;
- this.inFlight = next;
- try {
- const result = await this.ingestWithSignificance(next);
- this.emit({ type: "ingested", file: next, result });
- } catch (err) {
- // The file vanished between the event and the ingest — that's a delete.
- if ((err as NodeJS.ErrnoException).code === "ENOENT") {
- const pruned = await this.engine.forgetSource(next).catch(() => undefined);
- this.contentHashes.delete(next);
- this.emit({ type: "deleted", file: next, pruned });
- } else {
- this.emit({ type: "error", file: next, error: err instanceof Error ? err.message : String(err) });
- }
- } finally {
- this.inFlight = undefined;
- }
- }
- }
-
- /**
- * Ingest a file, skipping the LLM pass when the change is insignificant.
- *
- * For text files we compare the *normalized* content (whitespace/line-ending
- * collapsed) against the last version ingested in this session; an unchanged
- * normalization means the save only reformatted the file, so we report it as
- * skipped without re-extracting. Meaningful edits go through the normal ingest
- * path (which itself dedups on exact content and prunes superseded facts).
- * PDFs skip the gate — extracting their text to hash it costs as much as
- * ingesting — and rely on the engine's exact-content dedup.
- */
- private async ingestWithSignificance(path: string): Promise<IngestResult> {
- if (isPdfPath(path)) return this.engine.ingestFile(path);
-
- let text: string;
- try {
- text = readFileSync(path, "utf8");
- } catch {
- // Let the normal path surface the real error (or ENOENT → delete).
- return this.engine.ingestFile(path);
- }
-
- const nhash = contentHash(normalizeForSignificance(text));
- if (this.contentHashes.get(path) === nhash) {
- return {
- documentId: "",
- title: basename(path),
- skipped: true,
- chunks: 0,
- nodesCreated: 0,
- nodesUpdated: 0,
- edgesCreated: 0,
- edgesUpdated: 0,
- };
- }
-
- const result = await this.engine.ingest(text, { title: basename(path), source: path });
- this.contentHashes.set(path, nhash);
- return result;
- }
-
- private takeNext(): string | undefined {
- const next = this.pending.values().next().value as string | undefined;
- if (next !== undefined) this.pending.delete(next);
- return next;
- }
-
- private takeNextDelete(): string | undefined {
- const next = this.pendingDeletes.values().next().value as string | undefined;
- if (next !== undefined) this.pendingDeletes.delete(next);
- return next;
- }
-}
-
-/**
- * Collapse formatting-only differences so a reformat hashes identically to the
- * original: normalize line endings, strip trailing whitespace, collapse runs of
- * blank lines and inner whitespace, and trim. Deliberately conservative — it
- * only ignores layout, never content.
- */
-function normalizeForSignificance(text: string): string {
- return text
- .replace(/\r\n?/g, "\n")
- .split("\n")
- .map((line) => line.replace(/[ \t]+$/g, ""))
- .join("\n")
- .replace(/\n{3,}/g, "\n\n")
- .replace(/[ \t]+/g, " ")
- .trim();
-}
diff --git a/src/web.ts b/src/web.ts
deleted file mode 100644
index 8c677718..00000000
--- a/src/web.ts
+++ /dev/null
@@ -1,538 +0,0 @@
-#!/usr/bin/env node
-/**
- * `context-graph-web` — the Team Brain web UI.
- *
- * A zero-dependency HTTP server (node:http) over the ContextGraphEngine:
- * ask questions with cited, confidence-scored answers; watch the graph grow
- * as documents are ingested; contribute learnings back. Serves a single
- * self-contained page from ./web/ui.html.
- *
- * The request handling is packaged as {@link createWebApp} so the unified
- * `context-graph serve` command can mount it alongside the MCP-over-HTTP
- * endpoint on one port, sharing a single engine and watcher. Run directly
- * (`context-graph-web`) it keeps its original standalone behavior.
- *
- * Env: CONTEXT_GRAPH_DB (graph file), PORT (default 4680),
- * HOST (default 127.0.0.1 — set 0.0.0.0 to expose on a network, e.g. Docker),
- * CONTEXT_GRAPH_WEB_TOKEN (access token for /api; auto-generated and
- * printed at startup whenever the server is exposed beyond loopback),
- * OPENROUTER_API_KEY (optional — enables synthesized answers + ingest
- * extraction; without it retrieval and the graph view stay fully local).
- */
-import "dotenv/config";
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
-import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from "node:fs";
-import { networkInterfaces } from "node:os";
-import { fileURLToPath } from "node:url";
-import { resolve, dirname, join } from "node:path";
-import OpenAI from "openai";
-import { ContextGraphEngine } from "./engine.js";
-import { GraphWatcher } from "./watch.js";
-import { resolveConfig, type ResolvedConfig } from "./ai/providers.js";
-import { extractPdfTextFromData, isPdfPath } from "./ingest/pdf.js";
-
-const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
-
-// --- pure helpers (no module state) ---
-
-function readBody(req: IncomingMessage, maxBytes = 10_000_000): Promise<string> {
- return new Promise((res, rej) => {
- let data = "";
- req.on("data", (c) => {
- data += c;
- if (data.length > maxBytes) rej(new Error("body too large"));
- });
- req.on("end", () => res(data));
- req.on("error", rej);
- });
-}
-
-function json(res: ServerResponse, status: number, body: unknown): void {
- const payload = JSON.stringify(body);
- res.writeHead(status, { "content-type": "application/json" });
- res.end(payload);
-}
-
-/** Best-guess LAN address, to print a ready-to-share URL at startup. */
-function lanAddress(): string | undefined {
- for (const addrs of Object.values(networkInterfaces())) {
- for (const a of addrs ?? []) {
- if (a.family === "IPv4" && !a.internal) return a.address;
- }
- }
- return undefined;
-}
-
-function hostnameOf(headerValue: string | undefined): string | undefined {
- if (!headerValue) return undefined;
- try {
- return new URL(
- headerValue.includes("://") ? headerValue : `http://${headerValue}`,
- ).hostname;
- } catch {
- return undefined;
- }
-}
-
-/** Which extraction/answer/embedding providers are live, for the UI to display honestly. */
-export interface ProviderStatus {
- extraction: string;
- embeddings: string;
- canSynthesize: boolean;
- model: string;
- db: string;
-}
-
-export interface WebAppOptions {
- /** The (shared) engine backing the UI. */
- engine: ContextGraphEngine;
- /** Resolved config; defaults to {@link resolveConfig}. */
- cfg?: ResolvedConfig;
- /** Host the server binds to — decides whether an access token is required. */
- host: string;
- /** Port the server listens on — used only to render share links. */
- port: number;
- /** Lazily create (or return) the watcher used for in-process auto-watch. */
- ensureWatcher: () => GraphWatcher;
- /** Peek at the live watcher without creating one (for status endpoints). */
- getWatcher?: () => GraphWatcher | undefined;
-}
-
-export interface WebApp {
- /** node:http request handler for the UI + /api/* endpoints. */
- handler: (req: IncomingMessage, res: ServerResponse) => void;
- /** True if a presented bearer token authorizes /api access (always true when unguarded). */
- isAuthorized: (req: IncomingMessage) => boolean;
- /**
- * Browser-facing hardening (DNS-rebinding / CSRF): returns true and writes an
- * error response if the request should be rejected. Callers that route around
- * {@link WebApp.handler} (e.g. `serve`'s `/mcp`) must run this first.
- */
- rejectForeignRequest: (req: IncomingMessage, res: ServerResponse) => boolean;
- /** Whether the server is exposed beyond loopback (a token is then required). */
- exposed: boolean;
- /** The active access token, if any. */
- webToken?: string;
- /** Path of the human-readable share-link file, if written. */
- sharePath?: string;
- /** Which extraction/answer/embedding providers are live. */
- providerStatus: () => ProviderStatus;
-}
-
-/**
- * Build the web request handler over a given engine. The handler is transport
- * agnostic: `context-graph-web`'s `main()` wraps it in its own HTTP server, and
- * `context-graph serve` mounts it behind a router that also serves `/mcp`.
- */
-export function createWebApp(opts: WebAppOptions): WebApp {
- const { engine, host, port, ensureWatcher } = opts;
- const cfg = opts.cfg ?? resolveConfig();
- const getWatcher = opts.getWatcher ?? (() => undefined);
- const uiPath = new URL("./web/ui.html", import.meta.url);
- const EXPOSED = !LOCAL_HOSTNAMES.has(host);
-
- /** Which extraction/answer provider is live, so the UI can say so honestly. */
- function providerStatus(): ProviderStatus {
- return {
- extraction: cfg.openrouterApiKey && !cfg.forceLocal ? "openrouter" : "ollama",
- embeddings: cfg.openaiApiKey && !cfg.forceLocal ? "openai" : "local",
- canSynthesize: Boolean(cfg.openrouterApiKey && !cfg.forceLocal),
- model: cfg.openrouterApiKey ? cfg.openrouterModel : cfg.ollamaModel,
- db: resolve(cfg.dbPath),
- };
- }
-
- /** Synthesize a grounded natural-language answer from a retrieval bundle. */
- async function synthesizeAnswer(
- question: string,
- prompt: string,
- sourceTitles: string[],
- ): Promise<string> {
- const client = new OpenAI({
- apiKey: cfg.openrouterApiKey,
- baseURL: cfg.openrouterBaseUrl,
- defaultHeaders: { "X-Title": "Context Graph Web" },
- });
- const response = await client.chat.completions.create({
- model: cfg.openrouterModel,
- temperature: 0,
- messages: [
- {
- role: "system",
- content:
- "You answer questions using ONLY the provided context from a team knowledge graph. " +
- "Be direct and specific. Cite sources inline with bracketed numbers like [1], [2] " +
- "matching the numbered source list. If the context does not contain the answer, say " +
- "exactly what is missing — never invent facts.",
- },
- {
- role: "user",
- content: `${prompt}\n\n## Numbered sources\n${sourceTitles
- .map((t, i) => `[${i + 1}] ${t}`)
- .join("\n")}\n\n## Question\n${question}`,
- },
- ],
- });
- return response.choices[0]?.message?.content ?? "";
- }
-
- /**
- * Directory that holds durable server state (the graph db, and the persisted
- * access token). Defaults next to the SQLite file so it rides the same mounted
- * volume in Docker. Undefined for an in-memory db — nothing to persist.
- */
- function dataDir(): string | undefined {
- if (cfg.dbPath === ":memory:") return undefined;
- return dirname(resolve(cfg.dbPath));
- }
-
- /**
- * Resolve the access token, persisting a generated one so it survives restarts.
- *
- * Precedence: an explicit CONTEXT_GRAPH_WEB_TOKEN always wins (and is never
- * written to disk). Otherwise, when exposed, reuse a previously persisted token
- * or mint one and save it (owner-only) beside the db — so a `docker compose
- * restart` no longer invalidates every teammate's saved link. Also drops a
- * human-readable share-link.txt so the deployer never has to grep the logs.
- */
- function resolveWebToken(): { token?: string; sharePath?: string } {
- const explicit = process.env.CONTEXT_GRAPH_WEB_TOKEN?.trim();
- if (explicit) return { token: explicit };
- if (!EXPOSED) return {};
-
- const dir = dataDir();
- if (!dir) return { token: randomBytes(18).toString("base64url") };
-
- const tokenPath = join(dir, ".web-token");
- let token: string;
- try {
- token = existsSync(tokenPath) ? readFileSync(tokenPath, "utf8").trim() : "";
- if (!token) {
- token = randomBytes(18).toString("base64url");
- mkdirSync(dir, { recursive: true });
- writeFileSync(tokenPath, token + "\n", { mode: 0o600 });
- }
- } catch {
- // Read-only volume or similar — fall back to an in-memory token so the
- // server still starts (it'll just change on restart, as before).
- return { token: randomBytes(18).toString("base64url") };
- }
-
- // Best-effort human-readable share file; failure here must not block startup.
- let sharePath: string | undefined;
- try {
- const lan = lanAddress();
- const base = lan ? `http://${lan}:${port}` : `http://<this-machine>:${port}`;
- const share = join(dir, "share-link.txt");
- writeFileSync(
- share,
- `Context Graph — team access\n\n` +
- `Access token:\n ${token}\n\n` +
- `Share this link with your team (opens the UI already signed in):\n ${base}/#token=${token}\n\n` +
- `On this machine, use:\n http://localhost:${port}/#token=${token}\n`,
- { mode: 0o600 },
- );
- sharePath = share;
- } catch {
- /* ignore */
- }
- return { token, sharePath };
- }
-
- const { token: WEB_TOKEN, sharePath: SHARE_PATH } = resolveWebToken();
-
- function isAuthorized(req: IncomingMessage): boolean {
- if (!WEB_TOKEN) return true;
- const header = req.headers.authorization ?? "";
- const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
- // Hash both sides so timingSafeEqual gets equal-length buffers.
- const a = createHash("sha256").update(presented).digest();
- const b = createHash("sha256").update(WEB_TOKEN).digest();
- return timingSafeEqual(a, b);
- }
-
- /**
- * Browser-facing hardening for a loopback server: a malicious webpage must not
- * be able to drive state-changing endpoints (CSRF) or read responses via DNS
- * rebinding. When host is loopback (the default), only localhost Host headers
- * are accepted; POSTs must be application/json and, if a browser sent an
- * Origin, it must be a localhost origin too.
- */
- function rejectForeignRequest(req: IncomingMessage, res: ServerResponse): boolean {
- const boundToLoopback = LOCAL_HOSTNAMES.has(host);
- if (boundToLoopback) {
- const h = hostnameOf(req.headers.host);
- if (!h || !LOCAL_HOSTNAMES.has(h)) {
- json(res, 403, { error: "forbidden: unexpected Host header" });
- return true;
- }
- }
- if (req.method === "POST") {
- if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {
- json(res, 415, { error: "content-type must be application/json" });
- return true;
- }
- const origin = hostnameOf(req.headers.origin);
- if (boundToLoopback && req.headers.origin && (!origin || !LOCAL_HOSTNAMES.has(origin))) {
- json(res, 403, { error: "forbidden: cross-origin request" });
- return true;
- }
- }
- return false;
- }
-
- const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
- const url = new URL(req.url ?? "/", `http://localhost:${port}`);
- try {
- if (rejectForeignRequest(req, res)) return;
- if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/index.html")) {
- // The page itself is public — it holds no data. All data flows through
- // /api/*, which is what the token gates.
- res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
- res.end(readFileSync(uiPath, "utf8"));
- return;
- }
-
- if (url.pathname.startsWith("/api/") && !isAuthorized(req)) {
- return json(res, 401, { error: "access token required" });
- }
-
- if (req.method === "GET" && url.pathname === "/api/stats") {
- json(res, 200, { ...(await engine.stats()), provider: providerStatus() });
- return;
- }
-
- if (req.method === "GET" && url.pathname === "/api/graph") {
- json(res, 200, await engine.exportGraph());
- return;
- }
-
- if (req.method === "GET" && url.pathname === "/api/documents") {
- json(res, 200, await engine.store.allDocuments());
- return;
- }
-
- if (req.method === "GET" && url.pathname === "/api/watched") {
- const live = getWatcher();
- json(res, 200, {
- registered: engine.listWatchedDirs(),
- live: live?.dirs() ?? [],
- pending: live?.pendingCount() ?? 0,
- });
- return;
- }
-
- if (req.method === "POST" && url.pathname === "/api/ask") {
- const { question } = JSON.parse(await readBody(req)) as { question?: string };
- if (!question?.trim()) return json(res, 400, { error: "question is required" });
-
- const bundle = await engine.read(question, { maxNodes: 8, maxChunks: 6 });
- let answer: string | null = null;
- if (providerStatus().canSynthesize && (bundle.nodes.length || bundle.chunks.length)) {
- try {
- answer = await synthesizeAnswer(
- question,
- bundle.prompt,
- bundle.chunks.map((c) => c.documentTitle),
- );
- } catch (e) {
- // Answer synthesis is an upgrade, not a requirement — degrade to the
- // structured bundle rather than failing the whole request.
- answer = null;
- }
- }
- json(res, 200, { answer, bundle });
- return;
- }
-
- if (req.method === "POST" && url.pathname === "/api/ingest-dir") {
- // Accepts a directory or a single file on the server's disk. With
- // watch:true the directory is also registered and watched in-process,
- // so future edits keep flowing into the graph while the server runs.
- const { dir, extensions, watch } = JSON.parse(await readBody(req)) as {
- dir?: string;
- extensions?: string[];
- watch?: boolean;
- };
- if (!dir?.trim()) return json(res, 400, { error: "dir is required" });
- const abs = resolve(dir);
- if (!existsSync(abs)) {
- return json(res, 400, { error: `no such file or directory: ${abs}` });
- }
- const isDir = statSync(abs).isDirectory();
-
- // Stream progress as NDJSON so the UI can narrate a long ingest live.
- res.writeHead(200, { "content-type": "application/x-ndjson", "cache-control": "no-store" });
- const emit = (event: unknown) => res.write(JSON.stringify(event) + "\n");
- try {
- const results = isDir
- ? await engine.ingestDir(abs, {
- extensions,
- onProgress: (info) => emit({ type: "progress", ...info }),
- })
- : [await engine.ingestFile(abs)];
- let watching = false;
- if (watch && isDir) {
- engine.addWatchedDir(abs, extensions);
- // The just-finished ingest makes the watcher's catch-up scan a
- // pure hash-dedup pass — no LLM calls. Don't hold the response.
- void ensureWatcher()
- .add(abs)
- .catch((e) => console.error(`watch: ✗ ${abs}: ${e instanceof Error ? e.message : String(e)}`));
- watching = true;
- }
- emit({ type: "done", results, watching, stats: await engine.stats() });
- } catch (e) {
- emit({ type: "error", error: e instanceof Error ? e.message : String(e) });
- }
- res.end();
- return;
- }
-
- if (req.method === "POST" && url.pathname === "/api/ingest-upload") {
- // One uploaded file at a time (the browser folder picker can't hand us a
- // server path, so it ships file contents instead). Text files arrive as
- // `text`; PDFs and other binaries arrive base64-encoded in `dataBase64`.
- // `relPath` (folder/sub/file.md) keys the document when present, so two
- // same-named files in different folders don't replace each other and a
- // synced folder's re-uploads update the right document.
- // 60 MB cap leaves room for a large PDF plus base64's ~33% overhead.
- const { name, relPath, text, dataBase64 } = JSON.parse(await readBody(req, 60_000_000)) as {
- name?: string;
- relPath?: string;
- text?: string;
- dataBase64?: string;
- };
- if (!name?.trim()) return json(res, 400, { error: "name is required" });
-
- let content: string;
- if (isPdfPath(name)) {
- if (!dataBase64) return json(res, 400, { error: "PDF upload needs dataBase64" });
- content = await extractPdfTextFromData(new Uint8Array(Buffer.from(dataBase64, "base64")));
- } else {
- content = text ?? "";
- }
- if (!content.trim()) return json(res, 200, { skipped: true, name, empty: true });
-
- const result = await engine.ingest(content, {
- title: name,
- source: relPath?.trim() || name,
- });
- json(res, 200, { result, stats: await engine.stats() });
- return;
- }
-
- if (req.method === "POST" && url.pathname === "/api/contribute") {
- const { learning, agentId } = JSON.parse(await readBody(req)) as {
- learning?: string;
- agentId?: string;
- };
- if (!learning?.trim()) return json(res, 400, { error: "learning is required" });
- const result = await engine.contribute(learning, { agentId: agentId || "web-user" });
- json(res, 200, { ...result, stats: await engine.stats() });
- return;
- }
-
- json(res, 404, { error: "not found" });
- } catch (e) {
- json(res, 500, { error: e instanceof Error ? e.message : String(e) });
- }
- };
-
- return {
- handler,
- isAuthorized,
- rejectForeignRequest,
- exposed: EXPOSED,
- webToken: WEB_TOKEN,
- sharePath: SHARE_PATH,
- providerStatus,
- };
-}
-
-/** Standalone `context-graph-web` entry point. */
-async function main(): Promise<void> {
- const PORT = Number(process.env.PORT ?? 4680);
- const HOST = process.env.HOST ?? "127.0.0.1";
- const engine = new ContextGraphEngine();
-
- // In-process auto-watch. Created lazily: by CONTEXT_GRAPH_WATCH=1 at startup
- // (resumes registered folders), or the first time the UI ingests a server
- // path with "keep watching" enabled.
- let webWatcher: GraphWatcher | undefined;
- const ensureWatcher = (): GraphWatcher =>
- (webWatcher ??= new GraphWatcher(engine, {
- onEvent: (event) => {
- if (event.type === "ingested" && !event.result.skipped) {
- console.log(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);
- } else if (event.type === "deleted") {
- const p = event.pruned;
- console.log(
- p
- ? `watch: • ${event.file} deleted (−${p.nodesRemoved} entities, −${p.edgesRemoved} relationships)`
- : `watch: • ${event.file} deleted`,
- );
- } else if (event.type === "error") {
- console.error(`watch: ✗ ${event.file}: ${event.error}`);
- }
- },
- }));
-
- const app = createWebApp({
- engine,
- host: HOST,
- port: PORT,
- ensureWatcher,
- getWatcher: () => webWatcher,
- });
-
- if (process.env.CONTEXT_GRAPH_WATCH === "1") {
- const dirs = engine.listWatchedDirs();
- if (dirs.length > 0) {
- for (const wd of dirs) {
- ensureWatcher()
- .add(wd.dir)
- .catch((err) =>
- console.error(`watch: ✗ ${wd.dir}: ${err instanceof Error ? err.message : String(err)}`),
- );
- }
- } else {
- console.log("CONTEXT_GRAPH_WATCH=1 but no folders are registered — run: context-graph watch <dir>");
- }
- }
-
- const server = createServer(app.handler);
- server.listen(PORT, HOST, () => {
- const p = app.providerStatus();
- console.log(`Context Graph web UI → http://localhost:${PORT}`);
- if (app.exposed && app.webToken) {
- const lan = lanAddress();
- console.log(` access token: ${app.webToken}`);
- // Token travels in the URL *fragment*: browsers never send fragments over
- // the network, so it can't leak into proxy or access logs.
- if (lan) console.log(` share with your team: http://${lan}:${PORT}/#token=${app.webToken}`);
- else console.log(` share: http://<this-machine>:${PORT}/#token=${app.webToken}`);
- // The same link is written to a file on the mounted volume, so the deployer
- // (who ran `docker compose up -d` and sees no logs) can just open it.
- if (app.sharePath) console.log(` share link also saved to: ${app.sharePath}`);
- }
- console.log(` graph db: ${p.db}`);
- console.log(` extraction: ${p.extraction} (${p.model})`);
- console.log(` embeddings: ${p.embeddings}`);
- if (!p.canSynthesize) {
- console.log(
- " note: no OPENROUTER_API_KEY — answers show structured context without LLM synthesis",
- );
- }
- });
-}
-
-// Run the standalone server only when invoked directly (as the
-// `context-graph-web` bin), not when imported by `serve`.
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
- main().catch((err) => {
- console.error(err);
- process.exit(1);
- });
-}
diff --git a/src/web/ui.html b/src/web/ui.html
deleted file mode 100644
index 80bbec8b..00000000
--- a/src/web/ui.html
+++ /dev/null
@@ -1,194 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>Context Graph — read the graph before you work</title>
-<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Ccircle cx='9' cy='9' r='4' fill='%232E6B4E'/%3E%3Ccircle cx='24' cy='13' r='3' fill='%231C2422'/%3E%3Ccircle cx='14' cy='24' r='3' fill='%231C2422'/%3E%3Cpath d='M12 11l9 2M11 12l3 9M23 16l-8 7' stroke='%239AA79F' stroke-width='1.5'/%3E%3C/svg%3E" />
-<style>
- :root {
- --paper: #f2f5f0;
- --panel: #fdfdfb;
- --ink: #1c2422;
- --ink-soft: #5c6862;
- --ink-faint: #8b968f;
- --line: #dde4dc;
- --verdant: #2e6b4e;
- --verdant-deep: #1f4f38;
- --verdant-soft: #e2ede4;
- --serif: "Charter", "Iowan Old Style", "Palatino", Georgia, serif;
- --sans: system-ui, -apple-system, "Segoe UI", sans-serif;
- --mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace;
- --s1: 4px; --s2: 8px; --s3: 12px; --s4: 16px;
- --s5: 24px; --s6: 32px; --s7: 48px; --s8: 64px;
- --r-sm: 4px; --r-md: 6px; --r-lg: 10px;
- --shadow-1: 0 1px 3px rgba(28,36,34,.06);
- --ease-out: cubic-bezier(.22,.7,.3,1);
- }
- * { box-sizing: border-box; margin: 0; padding: 0; }
- body {
- font-family: var(--sans);
- background: var(--paper);
- color: var(--ink);
- font-size: 15px;
- line-height: 1.5;
- -webkit-font-smoothing: antialiased;
- }
- @keyframes rise { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: none; } }
- .rise { animation: rise 480ms var(--ease-out) both; animation-delay: calc(var(--i, 0) * 70ms); }
- @media (prefers-reduced-motion: reduce) { .rise { animation: none; } }
-
- code { font-family: var(--mono); }
-
- /* ---------- masthead ---------- */
- .masthead {
- display: flex; align-items: baseline; gap: 14px; flex-wrap: wrap;
- padding: 14px 22px 12px;
- border-bottom: 1px solid var(--line);
- background: var(--panel);
- }
- .wordmark { font-weight: 700; font-size: 15px; letter-spacing: .14em; text-transform: uppercase; }
- .wordmark .dot { color: var(--verdant); }
- .tagline { font-family: var(--serif); font-style: italic; color: var(--ink-soft); font-size: 14.5px; }
-
- /* ---------- page ---------- */
- .page { max-width: 760px; margin: 0 auto; padding: var(--s8) var(--s5) var(--s8); }
- section { margin-bottom: var(--s8); }
-
- /* ---------- hero ---------- */
- .hero h1 {
- font-family: var(--serif); font-weight: 600; letter-spacing: -0.01em;
- font-size: clamp(30px, 6vw, 46px); line-height: 1.12; margin-bottom: var(--s5);
- }
- .hero-sub { color: var(--ink-soft); font-size: 18px; line-height: 1.6; max-width: 56ch; }
- .hero-sub b { color: var(--ink); font-weight: 600; }
-
- /* ---------- metric tiles ---------- */
- .metrics { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--s3); margin-top: var(--s6); }
- .metric {
- background: var(--panel); border: 1px solid var(--line); border-radius: var(--r-lg);
- padding: var(--s4) var(--s4) var(--s3); box-shadow: var(--shadow-1);
- }
- .metric .n { font-family: var(--serif); font-weight: 600; font-size: 34px; color: var(--verdant-deep); line-height: 1; }
- .metric .l { font-family: var(--mono); font-size: 11.5px; color: var(--ink-soft); margin-top: var(--s2); text-transform: uppercase; letter-spacing: .06em; }
-
- /* ---------- steps ---------- */
- h2.head {
- font-size: 12px; letter-spacing: .12em; text-transform: uppercase;
- color: var(--ink-faint); font-weight: 700; margin-bottom: var(--s5);
- border-bottom: 1px solid var(--line); padding-bottom: var(--s2);
- }
- .steps { list-style: none; display: flex; flex-direction: column; gap: var(--s5); }
- .steps li { display: flex; gap: var(--s4); align-items: flex-start; }
- .steps .num {
- font-family: var(--mono); font-size: 12px; font-weight: 700;
- color: var(--verdant-deep); background: var(--verdant-soft); border-radius: 50%;
- width: 26px; height: 26px; flex: none;
- display: inline-flex; align-items: center; justify-content: center; margin-top: 2px;
- }
- .steps .body { font-size: 16px; color: var(--ink-soft); line-height: 1.55; }
- .steps .body b { color: var(--ink); font-weight: 600; }
-
- /* ---------- code block ---------- */
- pre {
- background: var(--ink); color: #e7ede8; border-radius: var(--r-lg);
- padding: var(--s5); overflow-x: auto; font-family: var(--mono); font-size: 13.5px; line-height: 1.7;
- }
- pre .c { color: #7f9686; } /* comment */
- .after { color: var(--ink-soft); font-size: 15px; margin-top: var(--s4); line-height: 1.6; }
- .after code { background: var(--verdant-soft); color: var(--verdant-deep); border-radius: var(--r-sm); padding: 1px 5px; font-size: 13px; }
-
- /* ---------- prose ---------- */
- .prose { font-size: 16px; color: var(--ink-soft); line-height: 1.65; max-width: 62ch; }
- .prose + .prose { margin-top: var(--s3); }
- .prose b { color: var(--ink); font-weight: 600; }
-
- footer {
- border-top: 1px solid var(--line); padding: var(--s5) 0 0;
- color: var(--ink-faint); font-size: 13px;
- }
-
- @media (max-width: 560px) {
- .metrics { grid-template-columns: 1fr; }
- .page { padding: var(--s6) var(--s4) var(--s7); }
- }
-</style>
-</head>
-<body>
-
-<header class="masthead">
- <span class="wordmark">Context<span class="dot">·</span>Graph</span>
- <span class="tagline">read the graph before you work</span>
-</header>
-
-<main class="page">
-
- <section class="hero rise" style="--i:0">
- <h1>31% fewer tool calls.<br>23% less cost.<br>17% lower latency.</h1>
- <p class="hero-sub">That's what your agent gets from reading the repo's context graph before it
- starts working. The graph is a folder of plain markdown files in the repo — one per system,
- API, or concept, linked to each other. It stays in sync with the code through git, so
- <b>anyone who clones the repo has it, no setup.</b></p>
- <div class="metrics">
- <div class="metric"><div class="n">&minus;31%</div><div class="l">tool calls</div></div>
- <div class="metric"><div class="n">&minus;23%</div><div class="l">cost</div></div>
- <div class="metric"><div class="n">&minus;17%</div><div class="l">latency</div></div>
- </div>
- </section>
-
- <section class="rise" style="--i:1">
- <h2 class="head">How it works</h2>
- <ol class="steps">
- <li>
- <span class="num">1</span>
- <span class="body"><b>Point it at your repo.</b> It builds <code>.context/</code> — one
- markdown file per system, API, or concept, linked together. The files are the nodes, the
- links are the edges. That's the whole graph.</span>
- </li>
- <li>
- <span class="num">2</span>
- <span class="body"><b>Commit it.</b> The graph is just files in git, so git is the sync.
- Anyone who clones the repo has it, and CI keeps it fresh — when a change moves something,
- you see it in the graph diff right next to the code, in the same PR.</span>
- </li>
- <li>
- <span class="num">3</span>
- <span class="body"><b>Your agent reads it before doing work</b> — so it starts knowing the
- codebase instead of rediscovering it from scratch every time.</span>
- </li>
- </ol>
- </section>
-
- <section class="rise" style="--i:2">
- <h2 class="head">Setup</h2>
-<pre><span class="c"># in your repo</span>
-context-graph init <span class="c"># builds .context/ from your code</span>
-git add .context &amp;&amp; git commit
-
-<span class="c"># keep it honest — fails CI if the graph is stale</span>
-context-graph check</pre>
- <p class="after">That's it. Anyone who clones the repo gets <code>.context/</code> for free.
- Point your agent at it and it reads the graph before working.</p>
- </section>
-
- <section class="rise" style="--i:3">
- <h2 class="head">The proof</h2>
- <p class="prose">Same model, same tools, same tasks. The only difference is whether the agent
- got the graph first. On a real 344-file repo it cut tool calls 31%, cost 23%, and latency 17%.</p>
- <p class="prose">The graph isn't magic — it's just that reading a few linked files beats
- rediscovering the codebase from scratch every single time.</p>
- </section>
-
- <section class="rise" style="--i:4">
- <h2 class="head">Runs locally</h2>
- <p class="prose">Everything runs on your machine. No accounts, no cloud calls, no keys. Building
- the graph uses a local model (Ollama); if you'd rather use a cloud model for better summaries,
- set a key and it'll use it. Local stays the default.</p>
- </section>
-
- <footer>Context&middot;Graph &mdash; a context graph that lives in your repo.</footer>
-
-</main>
-
-</body>
-</html>
diff --git a/test/bench-paths.test.ts b/test/bench-paths.test.ts
deleted file mode 100644
index f0b89f1d..00000000
--- a/test/bench-paths.test.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * The benchmark agent's filesystem tools run model-chosen paths. safePath is
- * the confinement boundary — assert it rejects escapes and accepts in-root paths.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { tmpdir } from "node:os";
-import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { safePath } from "../bench/agent.js";
-
-const root = mkdtempSync(join(tmpdir(), "cge-safepath-"));
-mkdirSync(join(root, "sub"), { recursive: true });
-writeFileSync(join(root, "a.txt"), "hi");
-writeFileSync(join(root, "sub", "b.txt"), "yo");
-
-test("accepts paths inside the root", () => {
- assert.ok(safePath(root, "a.txt").endsWith("a.txt"));
- assert.ok(safePath(root, "sub/b.txt").endsWith("b.txt"));
- assert.ok(safePath(root, "./sub/../a.txt").endsWith("a.txt"));
-});
-
-test("rejects parent-directory escapes", () => {
- assert.throws(() => safePath(root, "../../etc/passwd"), /escapes root/);
- assert.throws(() => safePath(root, "sub/../../secret"), /escapes root/);
-});
-
-test("rejects absolute paths outside the root", () => {
- assert.throws(() => safePath(root, "/etc/passwd"), /escapes root/);
-});
diff --git a/test/context.test.ts b/test/context.test.ts
new file mode 100644
index 00000000..1c29ac05
--- /dev/null
+++ b/test/context.test.ts
@@ -0,0 +1,136 @@
+/**
+ * End-to-end tests for the markdown-graph pipeline (`init` → `check`), driven by
+ * offline test doubles so no LLM/network is needed.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { buildContext } from "../src/context/build.js";
+import { checkContext } from "../src/context/check.js";
+import { fakeProviders } from "./helpers.js";
+
+function makeFixture(): string {
+ const dir = mkdtempSync(join(tmpdir(), "ctxgraph-"));
+ writeFileSync(
+ join(dir, "auth.ts"),
+ `// [[Auth Service]] ==depends_on==> [[Token Store]]\nexport const auth = 1;\n`,
+ );
+ writeFileSync(
+ join(dir, "billing.ts"),
+ `// [[Billing]] ==uses==> [[Auth Service]]\nexport const billing = 2;\n`,
+ );
+ return dir;
+}
+
+function buildOpts() {
+ return { model: "fake", ...fakeProviders() };
+}
+
+test("init builds one markdown node per entity, with links and a manifest", async () => {
+ const dir = makeFixture();
+ try {
+ const r = await buildContext(dir, buildOpts());
+ // Auth Service, Token Store, Billing.
+ assert.equal(r.nodes, 3);
+ assert.equal(r.links, 2);
+ assert.equal(r.files, 2);
+
+ const ctx = join(dir, ".context");
+ assert.ok(existsSync(join(ctx, "auth-service.md")));
+ assert.ok(existsSync(join(ctx, "token-store.md")));
+ assert.ok(existsSync(join(ctx, "billing.md")));
+ assert.ok(existsSync(join(ctx, "manifest.json")));
+
+ // Auth Service is referenced from BOTH files → multi-source provenance.
+ const authMd = readFileSync(join(ctx, "auth-service.md"), "utf8");
+ assert.match(authMd, /path: auth\.ts/);
+ assert.match(authMd, /path: billing\.ts/);
+ // Its edge to Token Store is rendered as a wiki-link.
+ assert.match(authMd, /\[\[token-store\]\]/);
+
+ const manifest = JSON.parse(readFileSync(join(ctx, "manifest.json"), "utf8"));
+ assert.equal(manifest.files.length, 2);
+ assert.equal(manifest.nodes.length, 3);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("check passes immediately after init", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, buildOpts());
+ const r = checkContext(dir);
+ assert.equal(r.ok, true);
+ assert.equal(r.missing, false);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("check reports NO GRAPH when init never ran", () => {
+ const dir = mkdtempSync(join(tmpdir(), "ctxgraph-"));
+ try {
+ const r = checkContext(dir);
+ assert.equal(r.missing, true);
+ assert.equal(r.ok, false);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("check detects content drift when a source file changes", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, buildOpts());
+ writeFileSync(join(dir, "auth.ts"), `// [[Auth Service]]\nexport const auth = 999;\n`);
+ const r = checkContext(dir);
+ assert.equal(r.ok, false);
+ assert.equal(r.contentDrift.length, 1);
+ assert.equal(r.contentDrift[0].path, "auth.ts");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("check detects a new file not yet in the graph (coverage drift)", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, buildOpts());
+ writeFileSync(join(dir, "new.ts"), `// [[New Thing]]\nexport const n = 3;\n`);
+ const r = checkContext(dir);
+ assert.equal(r.ok, false);
+ assert.deepEqual(r.coverage, ["new.ts"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("re-running init clears drift", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, buildOpts());
+ writeFileSync(join(dir, "new.ts"), `// [[New Thing]]\nexport const n = 3;\n`);
+ assert.equal(checkContext(dir).ok, false);
+ await buildContext(dir, buildOpts());
+ assert.equal(checkContext(dir).ok, true);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("human notes below the generated block survive regeneration", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, buildOpts());
+ const path = join(dir, ".context", "billing.md");
+ const withNote = readFileSync(path, "utf8") + "\nHand-written note: watch out for retries.\n";
+ writeFileSync(path, withNote);
+ await buildContext(dir, buildOpts());
+ assert.match(readFileSync(path, "utf8"), /Hand-written note: watch out for retries\./);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
diff --git a/test/helpers.ts b/test/helpers.ts
index 4058c8b6..106c0c0d 100644
--- a/test/helpers.ts
+++ b/test/helpers.ts
@@ -1,53 +1,54 @@
/**
- * Offline, deterministic test doubles so the whole pipeline runs with no keys,
- * no Ollama, and no network — the same "bring your own components" seam the
- * engine exposes for production (see README → "Bring your own components").
+ * Offline, deterministic test doubles so the pipeline runs with no keys, no
+ * Ollama, and no network — the same "bring your own components" seam the engine
+ * exposes via EngineConfig.summarizer / .synthesizer.
*/
-import type { Embedder, Extractor } from "../src/index.js";
-import type { Extraction } from "../src/index.js";
+import type { Summarizer, Synthesizer, SynthNode, SynthLink, FileSummary } from "../src/index.js";
-/** Deterministic embedder: hashes tokens into a fixed-width, normalized vector. */
-export class FakeEmbedder implements Embedder {
- readonly dimensions: number;
- constructor(dimensions = 16) {
- this.dimensions = dimensions;
- }
- async embed(texts: string[]): Promise<number[][]> {
- return texts.map((t) => this.vec(t));
- }
- private vec(text: string): number[] {
- const v = new Array(this.dimensions).fill(0);
- for (const tok of text.toLowerCase().split(/\s+/).filter(Boolean)) {
- let h = 0;
- for (let i = 0; i < tok.length; i++) h = (h * 31 + tok.charCodeAt(i)) | 0;
- v[Math.abs(h) % this.dimensions] += 1;
- }
- const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
- return v.map((x) => x / norm);
+/** Summarizer that passes the source through unchanged, so tests control the text. */
+export class PassthroughSummarizer implements Summarizer {
+ async summarize(code: string): Promise<string> {
+ return code;
}
}
/**
- * Extractor driven by simple markup so tests fully control the graph shape:
- * - `[[Entity Name]]` → an entity
- * - `[[A]] ==relation==> [[B]]` → a relationship
+ * Synthesizer driven by simple markup so tests fully control the graph shape:
+ * - `[[Node Name]]` → a node grounded in the file it appears in
+ * - `[[A]] ==relation==> [[B]]` → an edge A→B
+ * Nodes are merged by name across the provided files (union of source files).
*/
-export class BracketExtractor implements Extractor {
- async extract(text: string): Promise<Extraction> {
- const names = new Set<string>();
- for (const m of text.matchAll(/\[\[([^\]]+)\]\]/g)) names.add(m[1].trim());
- const entities = [...names].map((name) => ({
+export class BracketSynthesizer implements Synthesizer {
+ async synthesize(files: FileSummary[]): Promise<SynthNode[]> {
+ const byName = new Map<string, { sources: Set<string>; links: Map<string, SynthLink> }>();
+ const ensure = (name: string) => {
+ let e = byName.get(name);
+ if (!e) {
+ e = { sources: new Set(), links: new Map() };
+ byName.set(name, e);
+ }
+ return e;
+ };
+ for (const f of files) {
+ for (const m of f.summary.matchAll(/\[\[([^\]]+)\]\]/g)) {
+ ensure(m[1].trim()).sources.add(f.path);
+ }
+ for (const m of f.summary.matchAll(/\[\[([^\]]+)\]\]\s*==([a-z_]+)==>\s*\[\[([^\]]+)\]\]/g)) {
+ const [, from, relation, to] = m;
+ ensure(to.trim()).sources.add(f.path);
+ ensure(from.trim()).links.set(`${to}|${relation}`, { to: to.trim(), relation });
+ }
+ }
+ return [...byName].map(([name, e]) => ({
name,
type: "concept",
summary: `${name} summary`,
+ sources: [...e.sources],
+ links: [...e.links.values()],
}));
- const relations = [...text.matchAll(/\[\[([^\]]+)\]\]\s*==([a-z_]+)==>\s*\[\[([^\]]+)\]\]/g)].map(
- (m) => ({ source: m[1].trim(), relation: m[2], target: m[3].trim() }),
- );
- return { entities, relations };
}
}
export function fakeProviders() {
- return { embedder: new FakeEmbedder(), extractor: new BracketExtractor() };
+ return { summarizer: new PassthroughSummarizer(), synthesizer: new BracketSynthesizer() };
}
diff --git a/test/merge.test.ts b/test/merge.test.ts
deleted file mode 100644
index 43ae865b..00000000
--- a/test/merge.test.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { ContextGraphEngine, confidenceFromObservations } from "../src/index.js";
-import { fakeProviders } from "./helpers.ts";
-
-function engine() {
- return new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
-}
-
-async function nodeByName(e: ContextGraphEngine, name: string) {
- const nodes = await e.store.findNodesByName(name.toLowerCase());
- return nodes[0];
-}
-
-test("confidence is a pure, saturating function of observations", () => {
- assert.equal(Math.round(confidenceFromObservations(1) * 1000), 600);
- assert.equal(Math.round(confidenceFromObservations(2) * 1000), 680);
- assert.equal(Math.round(confidenceFromObservations(3) * 1000), 744);
- assert.ok(confidenceFromObservations(50) <= 0.99);
- // Monotonic non-decreasing.
- assert.ok(confidenceFromObservations(5) > confidenceFromObservations(4));
-});
-
-test("live re-observation reinforces; confidence tracks the count", async () => {
- const e = engine();
- await e.ingest("[[Billing Service]] ==depends_on==> [[Payments Gateway]]", { title: "one" });
- let n = await nodeByName(e, "billing service");
- assert.equal(n.observations, 1);
- assert.equal(Math.round(n.confidence * 1000), 600);
-
- // A distinct document observing the same entity bumps the counter.
- await e.ingest("[[Billing Service]] charges customers", { title: "two" });
- n = await nodeByName(e, "billing service");
- assert.equal(n.observations, 2);
- assert.equal(Math.round(n.confidence * 1000), 680);
- // Two distinct observation sources are tracked.
- assert.equal(Object.keys(n.observationSources).length, 2);
- await e.close();
-});
-
-test("re-importing the same graph file is idempotent (no double-counting)", async () => {
- const source = engine();
- await source.ingest("[[Alpha]] ==relates_to==> [[Beta]]", { title: "doc-a" });
- await source.ingest("[[Alpha]] again", { title: "doc-b" }); // Alpha now observed twice
- const jsonl = await source.exportJsonl();
-
- const alphaSource = await nodeByName(source, "alpha");
- assert.equal(alphaSource.observations, 2);
-
- const target = engine();
- const first = await target.importJsonl(jsonl);
- assert.equal(first.nodesCreated, 2); // Alpha, Beta
- const alpha1 = await nodeByName(target, "alpha");
- assert.equal(alpha1.observations, 2);
- const conf1 = alpha1.confidence;
-
- // Import the exact same file again — must change nothing.
- const second = await target.importJsonl(jsonl);
- assert.equal(second.nodesCreated, 0);
- const alpha2 = await nodeByName(target, "alpha");
- assert.equal(alpha2.observations, 2, "re-import must not inflate observations");
- assert.equal(alpha2.confidence, conf1, "re-import must not inflate confidence");
-
- const stats = await target.stats();
- assert.equal(stats.nodes, 2);
- assert.equal(stats.edges, 1);
- await source.close();
- await target.close();
-});
-
-test("later summaries win by timestamp on merge", async () => {
- const e = engine();
- await e.ingest("[[Widget]] summary", { title: "one" });
- const jsonl = await e.exportJsonl();
- const older = JSON.parse(
- jsonl.split("\n").find((l) => l.includes('"kind":"node"')) as string,
- );
- // Craft an incoming record with a newer summary + timestamp.
- older.summary = "a much longer and newer widget description";
- older.summaryUpdatedAt = "2999-01-01T00:00:00.000Z";
- const target = engine();
- await target.importJsonl(jsonl); // seed original
- await target.importJsonl([JSON.stringify({ kind: "meta", format: 1, embeddingDimensions: 16 }), JSON.stringify({ kind: "node", ...older })].join("\n"));
- const n = await nodeByName(target, "widget");
- assert.equal(n.summary, "a much longer and newer widget description");
- await e.close();
- await target.close();
-});
diff --git a/test/repo.test.ts b/test/repo.test.ts
deleted file mode 100644
index a6a2b92b..00000000
--- a/test/repo.test.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { ContextGraphEngine, type Summarizer } from "../src/index.js";
-import { fakeProviders } from "./helpers.ts";
-
-/** Deterministic summarizer: counts calls, emits bracket markup the BracketExtractor understands. */
-class FakeSummarizer implements Summarizer {
- calls: string[] = [];
- async summarize(code: string, opts: { path: string }): Promise<string> {
- this.calls.push(opts.path);
- return `[[${opts.path}]] is a module in this repo. It contains: ${code.trim()}`;
- }
-}
-
-function repoFixture(): string {
- const dir = mkdtempSync(join(tmpdir(), "cge-repo-"));
- mkdirSync(join(dir, "src"));
- mkdirSync(join(dir, "lib"));
- mkdirSync(join(dir, "node_modules", "leftpad"), { recursive: true });
- writeFileSync(join(dir, "src", "a.ts"), "export const a = 1;\n");
- writeFileSync(join(dir, "src", "b.ts"), "export const b = 2;\n");
- writeFileSync(join(dir, "lib", "c.py"), "c = 3\n");
- writeFileSync(join(dir, "main.ts"), "console.log('hi');\n");
- writeFileSync(join(dir, "notes.md"), "# not code\n"); // ignored: not a code extension
- writeFileSync(join(dir, "node_modules", "leftpad", "index.js"), "junk"); // ignored: skip dir
- return dir;
-}
-
-test("ingest replaces a changed document with the same source", async () => {
- const e = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
- const v1 = await e.ingest("[[Alpha]] version one", { source: "docs/x.md" });
- assert.equal(v1.skipped, false);
-
- // Identical content → skipped, nothing replaced.
- const again = await e.ingest("[[Alpha]] version one", { source: "docs/x.md" });
- assert.equal(again.skipped, true);
- assert.equal((await e.store.allDocuments()).length, 1);
-
- // Changed content, same source → old document (and its chunks) replaced.
- const v2 = await e.ingest("[[Alpha]] version two", { source: "docs/x.md" });
- assert.equal(v2.skipped, false);
- const docs = await e.store.allDocuments();
- assert.equal(docs.length, 1);
- assert.equal(docs[0].id, v2.documentId);
- const chunks = await e.store.allChunks();
- assert.ok(chunks.every((c) => c.documentId === v2.documentId));
-
- // "inline" sources are exempt — unrelated pastes must not clobber each other.
- await e.ingest("[[Beta]] one thing");
- await e.ingest("[[Gamma]] another thing");
- assert.equal((await e.store.allDocuments()).length, 3);
- await e.close();
-});
-
-test("ingestRepo summarizes code files into module documents, incrementally", async () => {
- const dir = repoFixture();
- const summarizer = new FakeSummarizer();
- const e = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders(), summarizer });
- try {
- const r1 = await e.ingestRepo(dir);
- // 4 code files (a.ts, b.ts, c.py, main.ts) — .md and node_modules excluded.
- assert.equal(r1.files, 4);
- assert.equal(r1.summarized, 4);
- assert.equal(r1.cached, 0);
- assert.deepEqual(r1.errors, []);
- // 3 modules: src, lib, and (root) for main.ts.
- assert.equal(r1.modules.length, 3);
- assert.ok(r1.modules.every((m) => !m.skipped));
- // Summaries flowed through extraction into the graph.
- const nodes = await e.store.findNodesByName(join("src", "a.ts").toLowerCase());
- assert.equal(nodes.length, 1);
-
- // Unchanged re-run: all cache hits, all module docs skipped by hash dedup.
- const r2 = await e.ingestRepo(dir);
- assert.equal(r2.summarized, 0);
- assert.equal(r2.cached, 4);
- assert.ok(r2.modules.every((m) => m.skipped));
- assert.equal(summarizer.calls.length, 4);
-
- // Touch one file: only it is re-summarized; only its module re-ingests.
- writeFileSync(join(dir, "src", "a.ts"), "export const a = 42;\n");
- const r3 = await e.ingestRepo(dir);
- assert.equal(r3.summarized, 1);
- assert.equal(r3.cached, 3);
- assert.equal(r3.modules.filter((m) => !m.skipped).length, 1);
- // The changed module document replaced its predecessor (no stale duplicate).
- const srcDocs = (await e.store.allDocuments()).filter((d) => d.source.endsWith("#src"));
- assert.equal(srcDocs.length, 1);
- } finally {
- await e.close();
- rmSync(dir, { recursive: true, force: true });
- }
-});
diff --git a/test/serve.test.ts b/test/serve.test.ts
deleted file mode 100644
index b26fff80..00000000
--- a/test/serve.test.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * The unified `context-graph serve` server: one process exposing the web UI,
- * the `/api/*` endpoints, and the MCP server over Streamable HTTP — all on one
- * port over a single shared engine. Runs fully offline on the fake providers.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { request } from "node:http";
-import { ContextGraphEngine } from "../src/index.js";
-import { startServe } from "../src/serve.js";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { fakeProviders } from "./helpers.ts";
-
-test("serve exposes the web UI, /api, and MCP-over-HTTP on one port", async () => {
- const engine = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
- await engine.ingest("[[Auth Service]] ==uses==> [[OAuth]]", { title: "auth", source: "auth.md" });
-
- // port 0 → a free port; watch:false so no folder resume in the test.
- const server = await startServe({ engine, host: "127.0.0.1", port: 0, watch: false });
- try {
- // 1) The web UI is served at the root.
- const home = await fetch(`${server.url}/`);
- assert.equal(home.status, 200);
- assert.match(await home.text(), /<!doctype html|<html/i);
-
- // 2) The JSON API works on the same port.
- const statsRes = await fetch(`${server.url}/api/stats`);
- assert.equal(statsRes.status, 200);
- const stats = (await statsRes.json()) as { documents: number; nodes: number };
- assert.ok(stats.documents >= 1, "ingested document is visible via /api/stats");
-
- // 3) MCP over Streamable HTTP: full handshake with the real SDK client.
- const client = new Client({ name: "serve-test", version: "0.0.0" });
- const transport = new StreamableHTTPClientTransport(new URL(`${server.url}/mcp`));
- await client.connect(transport);
-
- const tools = await client.listTools();
- const names = tools.tools.map((t) => t.name);
- assert.ok(names.includes("context_read"), "context_read tool is exposed over HTTP");
- assert.ok(names.includes("context_contribute"), "context_contribute tool is exposed over HTTP");
-
- // The MCP server reads the SAME engine the web API saw.
- const read = (await client.callTool({
- name: "context_read",
- arguments: { query: "auth" },
- })) as { content: Array<{ type: string; text: string }> };
- const text = read.content.map((c) => c.text).join("\n");
- assert.match(text, /Auth Service|OAuth/i, "context_read returns the ingested entities");
-
- await client.close();
- } finally {
- await server.close();
- }
-});
-
-test("serve requires no token on loopback and 404s unknown paths", async () => {
- const engine = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
- const server = await startServe({ engine, host: "127.0.0.1", port: 0, watch: false });
- try {
- const missing = await fetch(`${server.url}/api/nope`);
- assert.equal(missing.status, 404);
-
- // A POST to /mcp that isn't an initialize (and carries no session) is a 400,
- // not a crash — proves the session guard is wired.
- const bad = await fetch(`${server.url}/mcp`, {
- method: "POST",
- headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
- body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 1 }),
- });
- assert.equal(bad.status, 400);
- } finally {
- await server.close();
- }
-});
-
-test("serve rejects /mcp requests with a foreign Host header (DNS-rebinding defense)", async () => {
- const engine = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
- const server = await startServe({ engine, host: "127.0.0.1", port: 0, watch: false });
- try {
- // fetch() forbids setting Host, so drive a raw request with a spoofed host —
- // the shape a DNS-rebinding attack takes (browser rebinds evil.com → 127.0.0.1).
- const status = await new Promise<number>((resolve, reject) => {
- const req = request(
- {
- host: "127.0.0.1",
- port: server.port,
- path: "/mcp",
- method: "POST",
- headers: {
- host: "evil.example.com",
- "content-type": "application/json",
- accept: "application/json, text/event-stream",
- },
- },
- (res) => {
- res.resume();
- resolve(res.statusCode ?? 0);
- },
- );
- req.on("error", reject);
- req.end(JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }));
- });
- assert.equal(status, 403, "a foreign Host header is rejected on /mcp, not just /api");
- } finally {
- await server.close();
- }
-});
diff --git a/test/sync.test.ts b/test/sync.test.ts
deleted file mode 100644
index abbf81a3..00000000
--- a/test/sync.test.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { ContextGraphEngine } from "../src/index.js";
-import { fakeProviders } from "./helpers.ts";
-
-function engine() {
- return new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
-}
-
-async function names(e: ContextGraphEngine): Promise<string[]> {
- return (await e.store.allNodes()).map((n) => n.name).sort();
-}
-
-test("two machines converge to the same graph after cross-import (Mode A)", async () => {
- // Alice and Bob each learn different facts about a shared entity.
- const alice = engine();
- const bob = engine();
- await alice.ingest("[[Auth Service]] ==uses==> [[OAuth]]", { title: "alice" });
- await bob.ingest("[[Auth Service]] ==rotates==> [[Tokens]]", { title: "bob" });
-
- const aliceFile = await alice.exportJsonl();
- const bobFile = await bob.exportJsonl();
-
- // Exchange files.
- await alice.importJsonl(bobFile);
- await bob.importJsonl(aliceFile);
-
- // Both now know all three entities and both edges.
- const expected = ["Auth Service", "OAuth", "Tokens"].sort();
- assert.deepEqual(await names(alice), expected);
- assert.deepEqual(await names(bob), expected);
-
- const aStats = await alice.stats();
- const bStats = await bob.stats();
- assert.equal(aStats.nodes, bStats.nodes);
- assert.equal(aStats.edges, bStats.edges);
- assert.equal(aStats.edges, 2);
-
- // "Auth Service" was observed once on each machine → 2 distinct sources.
- const aAuth = (await alice.store.findNodesByName("auth service"))[0];
- assert.equal(aAuth.observations, 2, "shared entity sums both machines' observations");
- await alice.close();
- await bob.close();
-});
-
-test("import order does not change the result (commutativity)", async () => {
- const a = engine();
- const b = engine();
- await a.ingest("[[X]] ==r==> [[Y]]", { title: "a" });
- await b.ingest("[[Y]] ==r==> [[Z]]", { title: "b" });
- const af = await a.exportJsonl();
- const bf = await b.exportJsonl();
-
- const left = engine();
- await left.importJsonl(af);
- await left.importJsonl(bf);
-
- const right = engine();
- await right.importJsonl(bf);
- await right.importJsonl(af);
-
- assert.deepEqual(await names(left), await names(right));
- const ls = await left.stats();
- const rs = await right.stats();
- assert.deepEqual([ls.nodes, ls.edges], [rs.nodes, rs.edges]);
- await a.close();
- await b.close();
- await left.close();
- await right.close();
-});
diff --git a/test/watch.test.ts b/test/watch.test.ts
deleted file mode 100644
index fe55eb9d..00000000
--- a/test/watch.test.ts
+++ /dev/null
@@ -1,312 +0,0 @@
-/**
- * Auto-watch: the graph evolves as a connected folder changes. All tests run
- * on the offline fake providers; FS events come from real chokidar watchers on
- * temp directories, so generous polling deadlines absorb platform latency.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { ContextGraphEngine, GraphWatcher, type WatchEvent } from "../src/index.js";
-import { fakeProviders } from "./helpers.ts";
-
-function engine() {
- return new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });
-}
-
-function tempDir(): string {
- return mkdtempSync(join(tmpdir(), "cg-watch-"));
-}
-
-/** Poll until `cond` holds — FS events arrive with platform-dependent latency. */
-async function waitFor(cond: () => boolean, what: string, ms = 10_000): Promise<void> {
- const start = Date.now();
- while (!cond()) {
- if (Date.now() - start > ms) throw new Error(`timed out waiting for ${what}`);
- await new Promise((r) => setTimeout(r, 50));
- }
-}
-
-function collector() {
- const events: WatchEvent[] = [];
- const of = (type: WatchEvent["type"]) => events.filter((e) => e.type === type);
- return { events, of, onEvent: (e: WatchEvent) => events.push(e) };
-}
-
-test("initial scan ingests existing files; a second watcher skips them all", async () => {
- const dir = tempDir();
- const e = engine();
- writeFileSync(join(dir, "auth.md"), "[[Auth Service]] ==uses==> [[OAuth]]");
- writeFileSync(join(dir, "deploy.md"), "[[Deploys]] ==run_on==> [[CI]]");
-
- const first = collector();
- const w1 = new GraphWatcher(e, { debounceMs: 50, onEvent: first.onEvent });
- await w1.add(dir);
- await w1.idle();
- await w1.close();
-
- assert.equal(first.of("ingested").length, 2);
- assert.ok(first.of("ingested").every((ev) => ev.type === "ingested" && !ev.result.skipped));
- assert.equal((await e.stats()).documents, 2);
-
- // A fresh watcher over the same unchanged folder is a cheap no-op.
- const second = collector();
- const w2 = new GraphWatcher(e, { debounceMs: 50, onEvent: second.onEvent });
- await w2.add(dir);
- await w2.idle();
- await w2.close();
-
- assert.equal(second.of("ingested").length, 2);
- assert.ok(second.of("ingested").every((ev) => ev.type === "ingested" && ev.result.skipped));
- assert.equal((await e.stats()).documents, 2);
-
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("a file created after watching starts is ingested automatically", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- const w = new GraphWatcher(e, { debounceMs: 50, onEvent: c.onEvent });
- await w.add(dir);
-
- writeFileSync(join(dir, "new.md"), "[[Billing]] ==bills==> [[Customers]]");
- await waitFor(() => c.of("ingested").length === 1, "the new file to be ingested");
-
- assert.equal((await e.stats()).documents, 1);
- const [node] = await e.store.findNodesByName("billing");
- assert.ok(node, "entity from the new file reached the graph");
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("rapid successive saves are debounced into one ingest", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- const w = new GraphWatcher(e, { debounceMs: 400, onEvent: c.onEvent });
- await w.add(dir);
-
- const file = join(dir, "notes.md");
- writeFileSync(file, "[[Draft]] v1");
- writeFileSync(file, "[[Draft]] v2");
- writeFileSync(file, "[[Draft]] final version");
- await waitFor(() => c.of("ingested").length >= 1, "the burst of saves to be ingested");
- // Give any straggler event time to (wrongly) trigger a second ingest.
- await new Promise((r) => setTimeout(r, 700));
- await w.idle();
-
- assert.equal(c.of("ingested").length, 1, "one ingest for the whole burst");
- const docs = await e.store.documentsBySource(file);
- assert.equal(docs.length, 1);
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("editing a file replaces its document instead of piling up copies", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- const w = new GraphWatcher(e, { debounceMs: 50, onEvent: c.onEvent });
- const file = join(dir, "auth.md");
- writeFileSync(file, "[[Auth Service]] ==uses==> [[OAuth]]");
- await w.add(dir);
- await w.idle();
- const before = await e.store.documentsBySource(file);
- assert.equal(before.length, 1);
-
- writeFileSync(file, "[[Auth Service]] ==rotates==> [[Tokens]] every 15 minutes");
- await waitFor(() => c.of("ingested").length === 2, "the edited file to be re-ingested");
-
- const after = await e.store.documentsBySource(file);
- assert.equal(after.length, 1, "still one document for the source");
- assert.notEqual(after[0].hash, before[0].hash, "the document reflects the new content");
- assert.equal((await e.stats()).documents, 1);
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("deleting a file prunes the facts only it supported", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- const w = new GraphWatcher(e, { debounceMs: 50, onEvent: c.onEvent });
- const file = join(dir, "legacy.md");
- writeFileSync(file, "[[Legacy System]] ==replaced_by==> [[New System]]");
- await w.add(dir);
- await w.idle();
- assert.equal((await e.store.findNodesByName("legacy system")).length, 1);
-
- rmSync(file);
- await waitFor(() => c.of("deleted").length === 1, "the deletion to be observed");
- await w.idle();
-
- // The file was the only source for both entities and the relationship, so
- // all of it decays out of the graph.
- assert.equal((await e.store.findNodesByName("legacy system")).length, 0, "entity pruned");
- assert.equal((await e.store.findNodesByName("new system")).length, 0, "entity pruned");
- assert.deepEqual(await e.stats(), { documents: 0, nodes: 0, edges: 0, chunks: 0 });
- assert.equal(c.of("ingested").length, 1, "the delete triggered no ingest");
-
- const deleted = c.of("deleted")[0];
- assert.ok(deleted.type === "deleted" && deleted.pruned, "delete reports a prune result");
- assert.equal(deleted.pruned.documentsRemoved, 1);
- assert.equal(deleted.pruned.nodesRemoved, 2);
- assert.equal(deleted.pruned.edgesRemoved, 1);
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("a shared fact survives when one of its sources is deleted", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- const w = new GraphWatcher(e, { debounceMs: 50, onEvent: c.onEvent });
- writeFileSync(join(dir, "a.md"), "[[Shared Service]] ==owns==> [[Cache]]");
- writeFileSync(join(dir, "b.md"), "[[Shared Service]] ==owns==> [[Queue]]");
- await w.add(dir);
- await w.idle();
- const shared = (await e.store.findNodesByName("shared service"))[0];
- assert.equal(shared.observations, 2, "seen in both files");
-
- rmSync(join(dir, "a.md"));
- await waitFor(() => c.of("deleted").length === 1, "the deletion to be observed");
- await w.idle();
-
- // Shared Service and Queue live on (b.md still asserts them); Cache is gone.
- assert.equal((await e.store.findNodesByName("shared service")).length, 1, "shared entity kept");
- assert.equal((await e.store.findNodesByName("queue")).length, 1);
- assert.equal((await e.store.findNodesByName("cache")).length, 0, "orphaned entity pruned");
- const after = (await e.store.findNodesByName("shared service"))[0];
- assert.equal(after.observations, 1, "confidence decayed to the remaining source");
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("a formatting-only save is skipped without re-extraction", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- const w = new GraphWatcher(e, { debounceMs: 50, onEvent: c.onEvent });
- const file = join(dir, "notes.md");
- writeFileSync(file, "[[Payments]] ==charges==> [[Card]]");
- await w.add(dir);
- await w.idle();
- assert.equal(c.of("ingested").filter((ev) => ev.type === "ingested" && !ev.result.skipped).length, 1);
-
- // Reformat only: extra spaces, trailing whitespace, blank lines — same content.
- writeFileSync(file, " [[Payments]] ==charges==> [[Card]] \n\n\n");
- await waitFor(() => c.of("ingested").length === 2, "the reformat to be processed");
- await w.idle();
-
- const second = c.of("ingested")[1];
- assert.ok(second.type === "ingested" && second.result.skipped, "reformat skipped, no LLM pass");
- assert.equal((await e.stats()).documents, 1, "no new document");
- assert.equal((await e.store.findNodesByName("payments"))[0].observations, 1, "not re-observed");
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("a meaningful edit decays facts dropped from the new version", async () => {
- const e = engine();
- await e.ingest("[[Alpha]] ==uses==> [[Beta]]", { source: "spec.md" });
- await e.ingest("[[Alpha]] ==needs==> [[Gamma]]", { source: "spec.md" });
-
- // Alpha appears in both versions and survives; Beta was dropped and decays;
- // Gamma is new.
- assert.equal((await e.store.findNodesByName("alpha")).length, 1, "kept across versions");
- assert.equal((await e.store.findNodesByName("beta")).length, 0, "dropped fact pruned");
- assert.equal((await e.store.findNodesByName("gamma")).length, 1, "new fact present");
- assert.equal((await e.store.findNodesByName("alpha"))[0].observations, 1, "decayed to the live version");
-
- const alphaId = (await e.store.findNodesByName("alpha"))[0].id;
- const gammaId = (await e.store.findNodesByName("gamma"))[0].id;
- assert.ok(await e.store.findEdge(alphaId, gammaId, "needs"), "new relationship exists");
- assert.equal((await e.stats()).documents, 1, "still one document for the source");
-
- await e.close();
-});
-
-test("pruning can be disabled, restoring grow-only behavior", async () => {
- const e = new ContextGraphEngine({ dbPath: ":memory:", pruneSuperseded: false, ...fakeProviders() });
- await e.ingest("[[One]] ==links==> [[Two]]", { source: "doc.md" });
- await e.ingest("[[One]] ==links==> [[Three]]", { source: "doc.md" });
-
- // With pruning off, the superseded "Two" lingers as before.
- assert.equal((await e.store.findNodesByName("two")).length, 1, "stale fact retained when pruning is off");
- assert.equal((await e.store.findNodesByName("three")).length, 1);
-
- await e.close();
-});
-
-test("wrong extensions, oversized files, and skip-dirs are ignored", async () => {
- const dir = tempDir();
- const e = engine();
- const c = collector();
- writeFileSync(join(dir, "keep.md"), "[[Kept]]");
- writeFileSync(join(dir, "skip.log"), "[[Log Noise]]");
- writeFileSync(join(dir, "huge.md"), "x".repeat(1_000_001));
- mkdirSync(join(dir, "node_modules"));
- writeFileSync(join(dir, "node_modules", "readme.md"), "[[Vendored]]");
-
- const w = new GraphWatcher(e, { debounceMs: 50, onEvent: c.onEvent });
- await w.add(dir);
- await w.idle();
-
- assert.equal(c.of("ingested").length, 1);
- assert.equal((await e.stats()).documents, 1);
- assert.equal((await e.store.findNodesByName("log noise")).length, 0);
- assert.equal((await e.store.findNodesByName("vendored")).length, 0);
-
- // Live events under a skip-dir are ignored too.
- writeFileSync(join(dir, "node_modules", "later.md"), "[[Vendored Later]]");
- writeFileSync(join(dir, "later.txt"), "[[Arrived Later]]");
- await waitFor(() => c.of("ingested").length === 2, "only the valid live file to be ingested");
- await w.idle();
- assert.equal((await e.store.findNodesByName("vendored later")).length, 0);
-
- await w.close();
- await e.close();
- rmSync(dir, { recursive: true, force: true });
-});
-
-test("the watch registry survives engine restarts", async () => {
- const home = tempDir();
- const dbPath = join(home, "graph.db");
- const notes = join(home, "notes");
- mkdirSync(notes);
-
- const e1 = new ContextGraphEngine({ dbPath, ...fakeProviders() });
- const added = e1.addWatchedDir(notes, [".md"]);
- assert.equal(added.dir, notes);
- // Re-registering is idempotent and keeps the original timestamp.
- assert.equal(e1.addWatchedDir(notes).addedAt, added.addedAt);
- await e1.close();
-
- const e2 = new ContextGraphEngine({ dbPath, ...fakeProviders() });
- const listed = e2.listWatchedDirs();
- assert.equal(listed.length, 1);
- assert.equal(listed[0].dir, notes);
- assert.deepEqual(listed[0].extensions, [".md"]);
-
- assert.equal(e2.removeWatchedDir(notes), true);
- assert.equal(e2.removeWatchedDir(notes), false);
- assert.equal(e2.listWatchedDirs().length, 0);
- await e2.close();
-
- rmSync(home, { recursive: true, force: true });
-});
diff --git a/tsconfig.json b/tsconfig.json
index 71f6a484..e2794502 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -4,6 +4,7 @@
"module": "NodeNext",
"moduleResolution": "NodeNext",
"lib": ["ES2022"],
+ "types": ["node"],
"outDir": "./dist",
"rootDir": "./src",
"declaration": true,