@rahmantech/knl-view 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +194 -261
- package/bin/knl-view.js +162 -0
- package/package.json +1 -1
- package/server/consensus.js +0 -4
- package/server/graph/modules_builder.js +300 -0
- package/server/graph/modules_catalog.js +329 -0
- package/server/graph/sources.js +1 -2
- package/server/graph/syntax.js +54 -17
- package/server/scaffold.js +14 -3
package/README.md
CHANGED
|
@@ -1,79 +1,43 @@
|
|
|
1
1
|
# knl-view
|
|
2
2
|
|
|
3
|
-
A local viewer for `.knowledges` knowledge bases: a CLI that serves a small web
|
|
4
|
-
app over a plain folder of Markdown files. The disk is the source of truth;
|
|
5
|
-
`map.json` is optional decoration.
|
|
3
|
+
A local viewer and graph engine for `.knowledges` knowledge bases: a CLI that serves a small web app over a plain folder of Markdown files and tracks project architecture lineage. The disk is the source of truth; `map.json` is optional decoration.
|
|
6
4
|
|
|
7
|
-
```
|
|
5
|
+
```sh
|
|
8
6
|
knl-view --port 8086 --path=.knowledges
|
|
9
7
|
```
|
|
10
8
|
|
|
11
|
-
##
|
|
9
|
+
## Collaboration Model: Human, AI, and AnchorDB
|
|
12
10
|
|
|
13
|
-
-
|
|
14
|
-
step for your content, no account.
|
|
15
|
-
- Sidebar tree with a fixed `index` entry (the root `README.md`) and a
|
|
16
|
-
`contents` entry that lists the whole base on one page.
|
|
17
|
-
- Folders open their own `README.md`, rendered the same way as a normal document.
|
|
18
|
-
- `map.json` (optional) relabels, reorders, or hides entries in the menu. It
|
|
19
|
-
never creates, moves, or deletes files. Entries pointing at paths that are not
|
|
20
|
-
on disk are ignored silently.
|
|
21
|
-
- Markdown with GFM tables, and triple-backtick fences tagged `mermaid` rendered
|
|
22
|
-
as diagrams. The mermaid bundle is served locally and loaded only when a
|
|
23
|
-
document contains a diagram; nothing is fetched from a CDN.
|
|
24
|
-
- Per-diagram controls: toggle between diagram and source, and a zoom modal
|
|
25
|
-
(wheel zoom, drag to pan, +/−/Reset, Esc to close).
|
|
26
|
-
- Table of contents per document, breadcrumb, and a filter box in the sidebar
|
|
27
|
-
that narrows the index by file title or path.
|
|
28
|
-
- Interface in English or Indonesian, switchable in the top bar. English is the
|
|
29
|
-
default.
|
|
30
|
-
- Whole-project dependency and symbol call graph extraction via WebAssembly
|
|
31
|
-
Tree-Sitter for JavaScript, TypeScript, Go, Python, and Rust.
|
|
32
|
-
|
|
33
|
-
## Requirements
|
|
11
|
+
`knl-view` is built around a practical three-way collaboration model that aligns AI coding agents with human intent while keeping context windows clean and efficient:
|
|
34
12
|
|
|
35
|
-
|
|
36
|
-
-
|
|
37
|
-
|
|
13
|
+
### 1. The Human Foundation (`.knowledges`)
|
|
14
|
+
- **Single Source of Truth**: The human architect defines the system architecture, domain constraints, feature roadmaps, and audit notes in `.knowledges/`.
|
|
15
|
+
- **Human-in-the-Loop**: AI agents can assist in drafting and organizing documentation, but the human validates and approves business logic and architectural boundaries. This ensures coding agents have an unambiguous reference rather than guessing intent.
|
|
38
16
|
|
|
39
|
-
|
|
17
|
+
### 2. Decision History (`decision-history`)
|
|
18
|
+
- **Traceable Decision Records**: Major architectural choices, technical trade-offs, and strategic pivots are recorded as append-only records using the [`decision-history`](https://github.com/rachmanzz/decisionskills) skill.
|
|
19
|
+
- **Context Continuity**: Future AI agent sessions read these records to understand *why* specific patterns exist, preventing agents from re-introducing rejected approaches or modifying agreed-upon architectures without context.
|
|
40
20
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
21
|
+
### 3. Graph Storage & Dependency Efficiency (`AnchorDB`)
|
|
22
|
+
- **Structured Dependency Graphs**: AnchorDB stores indexed relationships for project source code (`sources`) and third-party libraries (`modules-npm`, `modules-go`, etc.) as nodes and edges.
|
|
23
|
+
- **Targeted Lineage Queries**: Instead of dumping large code files or entire dependency trees into LLM context, AI agents query specific caller/callee and import relationships via `knl-view sources trace` and `knl-view modules trace`.
|
|
24
|
+
- **Pre-Edit Impact Analysis**: Agents identify the exact blast radius of changes before modifying code, speeding up dependency analysis and conserving context tokens without guessing.
|
|
44
25
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
```sh
|
|
50
|
-
ln -s "$(npm prefix -g)/bin/knl-view" ~/.local/bin/knl-view
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
The published tarball ships the built `dist/`, so the install compiles
|
|
54
|
-
nothing.
|
|
55
|
-
|
|
56
|
-
Run it once without installing:
|
|
26
|
+
### 4. Autonomous Agent Execution
|
|
27
|
+
- Standardized operating rules are seeded into `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and project skills via `knl-view setup`.
|
|
28
|
+
- AI coding agents (Antigravity, Claude Code, Cursor, OpenCode) execute graph traces before editing, build module graphs on-demand, and sync changes back to AnchorDB autonomously. Developers assign tasks normally while agents manage graph operations in the background.
|
|
57
29
|
|
|
58
|
-
|
|
59
|
-
npx @rahmantech/knl-view
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Or install from source, for a local checkout or an unreleased commit:
|
|
63
|
-
|
|
64
|
-
```sh
|
|
65
|
-
git clone https://github.com/rachmanzz/knl-view.git
|
|
66
|
-
cd knl-view
|
|
67
|
-
npm install
|
|
68
|
-
npm run build
|
|
69
|
-
npm link
|
|
70
|
-
```
|
|
30
|
+
## What it does
|
|
71
31
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
`
|
|
75
|
-
|
|
76
|
-
|
|
32
|
+
- Serves a web viewer over any folder of Markdown files. No database, no build step for your content, no account.
|
|
33
|
+
- Sidebar tree with a fixed `index` entry (the root `README.md`) and a `contents` entry that lists the whole base on one page.
|
|
34
|
+
- Folders open their own `README.md`, rendered the same way as a normal document.
|
|
35
|
+
- `map.json` (optional) relabels, reorders, or hides entries in the menu. It never creates, moves, or deletes files. Entries pointing at paths that are not on disk are ignored silently.
|
|
36
|
+
- Markdown with GFM tables, and triple-backtick fences tagged `mermaid` rendered as diagrams. The mermaid bundle is served locally and loaded only when a document contains a diagram; nothing is fetched from a CDN.
|
|
37
|
+
- Per-diagram controls: toggle between diagram and source, and a zoom modal (wheel zoom, drag to pan, +/−/Reset, Esc to close).
|
|
38
|
+
- Table of contents per document, breadcrumb, and a filter box in the sidebar that narrows the index by file title or path.
|
|
39
|
+
- Interface in English or Indonesian, switchable in the top bar. English is the default.
|
|
40
|
+
- Whole-project dependency and symbol call graph extraction via WebAssembly Tree-Sitter for JavaScript, TypeScript, Go, Python, and Rust.
|
|
77
41
|
|
|
78
42
|
## How to Set Up
|
|
79
43
|
|
|
@@ -104,6 +68,45 @@ After setup, start the viewer immediately:
|
|
|
104
68
|
knl-view
|
|
105
69
|
```
|
|
106
70
|
|
|
71
|
+
## Requirements & Installation
|
|
72
|
+
|
|
73
|
+
### Requirements
|
|
74
|
+
|
|
75
|
+
- Node.js 20.19 or newer.
|
|
76
|
+
- A built frontend. `dist/` is committed to this repository, so an install from GitHub already has it. The CLI refuses to start without it and tells you so.
|
|
77
|
+
|
|
78
|
+
### Install
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
npm install -g @rahmantech/knl-view
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
That puts the `knl-view` command into Node's global bin, `$(npm prefix -g)/bin`. If that directory is not on your PATH, link the command somewhere that is:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
ln -s "$(npm prefix -g)/bin/knl-view" ~/.local/bin/knl-view
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The published tarball ships the built `dist/`, so the install compiles nothing.
|
|
91
|
+
|
|
92
|
+
Run it once without installing:
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
npx @rahmantech/knl-view
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Or install from source, for a local checkout or an unreleased commit:
|
|
99
|
+
|
|
100
|
+
```sh
|
|
101
|
+
git clone https://github.com/rachmanzz/knl-view.git
|
|
102
|
+
cd knl-view
|
|
103
|
+
npm install
|
|
104
|
+
npm run build
|
|
105
|
+
npm link
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`npm link` puts `knl-view` on your PATH from the checkout. To install a GitHub commit without cloning, run `npm install -g github:rachmanzz/knl-view --install-links`; without `--install-links`, npm 11 links against a temporary clone it deletes afterwards, which leaves a broken install.
|
|
109
|
+
|
|
107
110
|
## Usage
|
|
108
111
|
|
|
109
112
|
```sh
|
|
@@ -136,107 +139,9 @@ knl-view --seed-skill=knl-view --dir=global --yes
|
|
|
136
139
|
| `--help`, `-h` | | Show help |
|
|
137
140
|
| `--version`, `-v` | | Show version |
|
|
138
141
|
|
|
139
|
-
The server binds to `127.0.0.1` by default, so it is reachable only from your
|
|
140
|
-
machine unless you pass `--host` yourself. There is no authentication; treat
|
|
141
|
-
`--host 0.0.0.0` as a decision you are making on purpose.
|
|
142
|
-
|
|
143
|
-
## Configuration
|
|
144
|
-
|
|
145
|
-
Two optional config files. A missing file is never an error; a broken file is
|
|
146
|
-
ignored with one warning on stderr. CLI flags always win over config values.
|
|
147
|
-
|
|
148
|
-
**Global (`~/.knlview/knl-config.json`)**: shared by every project on the
|
|
149
|
-
machine. Holds the `anchordb` block. Without it, AnchorDB stays completely
|
|
150
|
-
off and the viewer runs fully local:
|
|
151
|
-
|
|
152
|
-
```json
|
|
153
|
-
{
|
|
154
|
-
"anchordb": {
|
|
155
|
-
"url": "wire://127.0.0.1:17448",
|
|
156
|
-
"token": "your-token",
|
|
157
|
-
"sync": true,
|
|
158
|
-
"deamon": "podman",
|
|
159
|
-
"container_name": "anchordb-knlview",
|
|
160
|
-
"container_id": "56519e7acbaa...",
|
|
161
|
-
"container_created_on": "2026-10-31 14:08:48..."
|
|
162
|
-
}
|
|
163
|
-
}
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
**Per project: `knl-config.json` at the project root** (gitignored):
|
|
167
|
-
`path`, `port`, `host`, `models`, and optional `include` / `exclude` patterns:
|
|
168
|
-
|
|
169
|
-
```json
|
|
170
|
-
{
|
|
171
|
-
"port": 8091,
|
|
172
|
-
"models": {
|
|
173
|
-
"knowledges": "vez0vqrp",
|
|
174
|
-
"consensus": "n0qrnmsz"
|
|
175
|
-
},
|
|
176
|
-
"include": ["dist/bundle.js"],
|
|
177
|
-
"exclude": ["legacy/**", "*.tmp"]
|
|
178
|
-
}
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
- `exclude`: Hard exclude that strictly filters files and folders from graph analysis and knowledge tree. Always takes precedence over defaults and includes.
|
|
182
|
-
- `include`: Whitelists files and folders. Overrides default directory exclusions (e.g. including files from `dist/` or dot-folders).
|
|
183
|
-
|
|
184
|
-
Model names are owned by the `models` map: role → name, and the name can
|
|
185
|
-
be anything (random names are fine; the map records what each name is
|
|
186
|
-
*for*). Names stay stable even if the project folder is renamed. knl-view
|
|
187
|
-
never invents names by itself: create them with
|
|
188
|
-
`knl-view model new <role>` (writes the map and the global registry), and
|
|
189
|
-
inspect ownership with `knl-view model check`.
|
|
190
|
-
|
|
191
|
-
The global registry `~/.knlview/models.json` records every name's owner
|
|
192
|
-
(project, role, path) and warns when two projects claim the same name. A
|
|
193
|
-
project whose map has no entry for a role runs fully local: AnchorDB is
|
|
194
|
-
touched only once the role is mapped.
|
|
195
|
-
|
|
196
|
-
## Operating System Support & Installing AnchorDB
|
|
197
|
-
|
|
198
|
-
### Operating System Support
|
|
199
|
-
|
|
200
|
-
| OS | Core Viewer (`knl-view`) | Global Config Location | AnchorDB Backend |
|
|
201
|
-
| --- | --- | --- | --- |
|
|
202
|
-
| **Linux** | Native (Node.js >= 20.19) | `~/.knlview/knl-config.json` | **Native Binary** (`amd64`, `arm64`) or Container |
|
|
203
|
-
| **macOS** | Native (Node.js >= 20.19) | `~/.knlview/knl-config.json` | **Container**: **Podman (Recommended)** or Docker |
|
|
204
|
-
| **Windows** | Native (Node.js >= 20.19) | `%APPDATA%\knlview\knl-config.json` | **Container**: **Podman (Recommended)** or Docker |
|
|
205
|
-
|
|
206
|
-
---
|
|
207
|
-
|
|
208
|
-
### Installing AnchorDB (Optional)
|
|
209
|
-
|
|
210
|
-
AnchorDB is an optional layer. Without it, the viewer runs 100% locally with zero external dependencies: document browsing, full-text search, the Markdown graph engine, and `knl-view graph trace` all work immediately. Installing AnchorDB adds persistent multi-hop causal tracing across sessions, whole-project source code dependency syncing, and shared multi-machine graphs.
|
|
211
|
-
|
|
212
|
-
Run `knl-view install anchordb` to install AnchorDB and write the `anchordb` block into your global configuration:
|
|
142
|
+
The server binds to `127.0.0.1` by default, so it is reachable only from your machine unless you pass `--host` yourself. There is no authentication; treat `--host 0.0.0.0` as a decision you are making on purpose.
|
|
213
143
|
|
|
214
|
-
|
|
215
|
-
- Native binaries are published on [GitHub Releases](https://github.com/rachmanzz/anchordb/releases) for Linux architectures:
|
|
216
|
-
- `linux_amd64` (x86_64)
|
|
217
|
-
- `linux_arm64` (aarch64)
|
|
218
|
-
- On Linux, `knl-view install anchordb` automatically:
|
|
219
|
-
- Fetches the latest release asset and verifies it against the official `SHA256SUMS.txt`.
|
|
220
|
-
- Installs `anchordb-server` and `anchordb` into `~/.knlview/bin/` with secure file permissions (`0o700` / `0o755`).
|
|
221
|
-
- Starts `anchordb-server` detached as a background process daemon (logs in `~/.knlview/anchordb.log`, data in `~/.knlview/anchordb-data`).
|
|
222
|
-
- You can also explicitly opt for containers on Linux using `--method=container`.
|
|
223
|
-
|
|
224
|
-
#### 2. Windows & macOS (Container via Podman or Docker)
|
|
225
|
-
- AnchorDB relies on Linux kernel primitives (`mmap` memory mapping and POSIX file locking). Native binaries are not yet published for Windows or macOS.
|
|
226
|
-
- For Windows and macOS, AnchorDB is currently deployed via a lightweight container image (`ghcr.io/rachmanzz/anchordb`):
|
|
227
|
-
- **Podman (Recommended)**: Rootless, daemonless, lightweight, and requires no administrative privileges or background daemons.
|
|
228
|
-
- **Docker**: Supported via Docker Desktop or Docker Engine (`--runtime=docker`).
|
|
229
|
-
- `knl-view install anchordb` automatically detects installed container runtimes. If both are found, it prompts you to select **Podman (Recommended)** or **Docker**. If neither is installed, it halts with clear installation guidance.
|
|
230
|
-
|
|
231
|
-
#### Flags & Automation (CI / Scripts)
|
|
232
|
-
- Non-interactive mode: add `--yes` (accepts all defaults).
|
|
233
|
-
- Force install method: `--method=binary` or `--method=container`.
|
|
234
|
-
- Specify container engine: `--runtime=podman` (recommended) or `--runtime=docker`.
|
|
235
|
-
- Custom token: `--token=<text>` (default: cryptographic 32-byte hex token).
|
|
236
|
-
- Port conflict handling: automatically detects if port 17448 is occupied and suggests alternative free ports.
|
|
237
|
-
- Data safety: if a container named `anchordb-knlview` already exists, the installer stops rather than overwriting existing data.
|
|
238
|
-
|
|
239
|
-
## How a base is read
|
|
144
|
+
## How a Knowledge Base is Read
|
|
240
145
|
|
|
241
146
|
A base is an ordinary folder:
|
|
242
147
|
|
|
@@ -251,9 +156,7 @@ A base is an ordinary folder:
|
|
|
251
156
|
auth.md
|
|
252
157
|
```
|
|
253
158
|
|
|
254
|
-
Reading order: the root `README.md`, then `map.json` when present, then the
|
|
255
|
-
structure on disk. Without `map.json`, menu labels fall back to the first
|
|
256
|
-
`# heading` of each file, then to the plain file name (files before folders).
|
|
159
|
+
Reading order: the root `README.md`, then `map.json` when present, then the structure on disk. Without `map.json`, menu labels fall back to the first `# heading` of each file, then to the plain file name (files before folders).
|
|
257
160
|
|
|
258
161
|
### map.json
|
|
259
162
|
|
|
@@ -285,12 +188,9 @@ Every entry is decoration. Nothing in it can invent a file that is not on disk.
|
|
|
285
188
|
| `order` | any entry | Ascending menu order; entries without `order` follow, files before folders |
|
|
286
189
|
| `ignore` (or `hidden`) | any entry | `true` hides it from the menu, lists, search, home, and contents |
|
|
287
190
|
|
|
288
|
-
Paths are relative to the `.knowledges` root, use `/` separators, and must
|
|
289
|
-
match the on-disk path exactly, for example `features/auth.md`. `ignore` is
|
|
290
|
-
view-only: the file stays on disk. Remove the flag to bring it back.
|
|
191
|
+
Paths are relative to the `.knowledges` root, use `/` separators, and must match the on-disk path exactly, for example `features/auth.md`. `ignore` is view-only: the file stays on disk. Remove the flag to bring it back.
|
|
291
192
|
|
|
292
|
-
The full field reference lives in the bundled skill:
|
|
293
|
-
`.agents/skills/knl-view/SKILL.md`.
|
|
193
|
+
The full field reference lives in the bundled skill: `.agents/skills/knl-view/SKILL.md`.
|
|
294
194
|
|
|
295
195
|
## AI Graph & Decision Tracing
|
|
296
196
|
|
|
@@ -300,53 +200,28 @@ The full field reference lives in the bundled skill:
|
|
|
300
200
|
- **Decision Lineage Tracking**: Automatically discovers `supersedes`, `related_to`, and `affects_knowledge` edges from `decisionskills` decision blocks.
|
|
301
201
|
- **Low-Token Subgraphs for AI**: Instead of loading an entire knowledge base into LLM context, query exact $N$-hop subgraphs in sub-milliseconds (< 1 ms).
|
|
302
202
|
|
|
303
|
-
This engine is fully local: it needs no AnchorDB and no network. AnchorDB
|
|
304
|
-
(see the optional install above) adds persistence on top: edges survive
|
|
305
|
-
across sessions, are synced incrementally, and can be traced from any
|
|
306
|
-
machine pointing at the same server.
|
|
203
|
+
This engine is fully local: it needs no AnchorDB and no network. AnchorDB (see the optional install below) adds persistence on top: edges survive across sessions, are synced incrementally, and can be traced from any machine pointing at the same server.
|
|
307
204
|
|
|
308
205
|
### Two-way lineage
|
|
309
206
|
|
|
310
|
-
Traces walk in a mechanically defined direction relative to the edges,
|
|
311
|
-
never interpreted as cause and effect (`depends_on` edges *leave* a
|
|
312
|
-
decision while pointing at its upstream, so up/down labels would lie):
|
|
207
|
+
Traces walk in a mechanically defined direction relative to the edges, never interpreted as cause and effect (`depends_on` edges *leave* a decision while pointing at its upstream, so up/down labels would lie):
|
|
313
208
|
|
|
314
|
-
- `direction=out`: edges leaving the target: what it supersedes,
|
|
315
|
-
|
|
316
|
-
- `direction=
|
|
317
|
-
replaces it.
|
|
318
|
-
- `direction=both`: the default for the local graph trace; the full
|
|
319
|
-
neighborhood.
|
|
209
|
+
- `direction=out`: edges leaving the target: what it supersedes, `depends_on`, or affects.
|
|
210
|
+
- `direction=in`: edges entering the target: what references or replaces it.
|
|
211
|
+
- `direction=both`: the default for the local graph trace; the full neighborhood.
|
|
320
212
|
|
|
321
|
-
Every returned node carries `via` (`center`, `in`, `out`, or `in+out`)
|
|
322
|
-
telling how it connects to the trace center.
|
|
213
|
+
Every returned node carries `via` (`center`, `in`, `out`, or `in+out`) telling how it connects to the trace center.
|
|
323
214
|
|
|
324
|
-
CLI: `knl-view graph trace --target=<id> --direction=out`
|
|
215
|
+
CLI: `knl-view graph trace --target=<id> --direction=out`
|
|
325
216
|
HTTP: `GET /api/graph/trace?target=<id>&direction=in`
|
|
326
217
|
|
|
327
|
-
The AnchorDB endpoint adds the same parameter,
|
|
328
|
-
`GET /api/anchordb/trace?target=<id>&direction=in|out|both` (default
|
|
329
|
-
`out`): `out` is scored server-side via `causalChain`; `in` is walked
|
|
330
|
-
backwards from the local sync mirror; the wire protocol has no reverse
|
|
331
|
-
query, and the mirror holds every edge this project ever linked, so it
|
|
332
|
-
is exactly the inbound map for this project's model. Mirror results
|
|
333
|
-
carry score 1 and the response reports `mirrored: true`/`false` so
|
|
334
|
-
consumers know which half came from where.
|
|
218
|
+
The AnchorDB endpoint adds the same parameter, `GET /api/anchordb/trace?target=<id>&direction=in|out|both` (default `out`): `out` is scored server-side via `causalChain`; `in` is walked backwards from the local sync mirror; the wire protocol has no reverse query, and the mirror holds every edge this project ever linked, so it is exactly the inbound map for this project's model. Mirror results carry score 1 and the response reports `mirrored: true`/`false` so consumers know which half came from where.
|
|
335
219
|
|
|
336
220
|
### Consensus (claims)
|
|
337
221
|
|
|
338
|
-
A second AnchorDB model, the `consensus` role in the project's models map,
|
|
339
|
-
holds agreement and conflict between *claims*: short statements that are
|
|
340
|
-
content-addressed (`c-` + 16 hex chars of the statement's hash), so the same
|
|
341
|
-
text is the same claim on every machine. Claims relate only to other claims,
|
|
342
|
-
through two fixed relation types: `agrees_with` and `contradicts`. The
|
|
343
|
-
consensus structure lives purely in AnchorDB; the local artifacts (claim
|
|
344
|
-
index in `~/.knlview/claims/`, edge mirror in `~/.knlview/sync-state/`) are
|
|
345
|
-
caches that degrade convenience, never the data.
|
|
222
|
+
A second AnchorDB model, the `consensus` role in the project's models map, holds agreement and conflict between *claims*: short statements that are content-addressed (`c-` + 16 hex chars of the statement's hash), so the same text is the same claim on every machine. Claims relate only to other claims, through two fixed relation types: `agrees_with` and `contradicts`. The consensus structure lives purely in AnchorDB; the local artifacts (claim index in `~/.knlview/claims/`, edge mirror in `~/.knlview/sync-state/`) are caches that degrade convenience, never the data.
|
|
346
223
|
|
|
347
|
-
A claim's status is derived from who points at it: any incoming `contradicts`
|
|
348
|
-
makes it `disputed`, otherwise any incoming `agrees_with` makes it
|
|
349
|
-
`consensus`, otherwise it is `uncontested`.
|
|
224
|
+
A claim's status is derived from who points at it: any incoming `contradicts` makes it `disputed`, otherwise any incoming `agrees_with` makes it `consensus`, otherwise it is `uncontested`.
|
|
350
225
|
|
|
351
226
|
```sh
|
|
352
227
|
knl-view consensus claim "We use bcrypt for password hashing"
|
|
@@ -357,48 +232,23 @@ knl-view consensus status c-437ff9f10f83edde
|
|
|
357
232
|
knl-view consensus list
|
|
358
233
|
```
|
|
359
234
|
|
|
360
|
-
Mutations are CLI-only on purpose: one write path, one mirror kept honest.
|
|
361
|
-
The read-only HTTP endpoint answers "is this claim settled?":
|
|
235
|
+
Mutations are CLI-only on purpose: one write path, one mirror kept honest. The read-only HTTP endpoint answers "is this claim settled?":
|
|
362
236
|
|
|
363
|
-
`GET /api/consensus?target=<claimId>` returns the claim's `status`,
|
|
364
|
-
`supporters`, `objectors`, its own `stance`, `mirrored` (whether a valid
|
|
365
|
-
local mirror backs the inbound half), and a `statements` map of the
|
|
366
|
-
claim texts involved. Returns `503` when AnchorDB is off or the
|
|
367
|
-
`consensus` role is not mapped.
|
|
237
|
+
`GET /api/consensus?target=<claimId>` returns the claim's `status`, `supporters`, `objectors`, its own `stance`, `mirrored` (whether a valid local mirror backs the inbound half), and a `statements` map of the claim texts involved. Returns `503` when AnchorDB is off or the `consensus` role is not mapped.
|
|
368
238
|
|
|
369
239
|
### Sources graph (whole project)
|
|
370
240
|
|
|
371
|
-
A third AnchorDB model, the `sources` role in the models map, holds the
|
|
372
|
-
dependency graph of the whole project, not just `.knowledges`. Every file
|
|
373
|
-
becomes a node (id = repo-relative path; hidden folders are skipped except
|
|
374
|
-
`.github`, and `node_modules`, `dist`, and `.gitignore` patterns are
|
|
375
|
-
ignored). Import edges are extracted with tree-sitter syntax parsing
|
|
376
|
-
(JavaScript, TypeScript/TSX, Go, Python, and Rust, one grammar package per
|
|
377
|
-
language family) and stored in both directions (`imports`, `imported_by`) so
|
|
378
|
-
lineage works without any local mirror: sync is server-authoritative, enumerating
|
|
379
|
-
the server's own records and edges before applying the difference from a fresh
|
|
380
|
-
disk scan.
|
|
241
|
+
A third AnchorDB model, the `sources` role in the models map, holds the dependency graph of the whole project, not just `.knowledges`. Every file becomes a node (id = repo-relative path; hidden folders are skipped except `.github`, and `node_modules`, `dist`, and `.gitignore` patterns are ignored). Import edges are extracted with tree-sitter syntax parsing (JavaScript, TypeScript/TSX, Go, Python, and Rust, one grammar package per language family) and stored in both directions (`imports`, `imported_by`) so lineage works without any local mirror: sync is server-authoritative, enumerating the server's own records and edges before applying the difference from a fresh disk scan.
|
|
381
242
|
|
|
382
243
|
Each file also defines **symbol nodes**, extracted from the same parse:
|
|
383
244
|
|
|
384
|
-
- Symbol ids are `<path>#<name>`; class methods are `Class.method`. A name
|
|
385
|
-
defined more than once in one file gets a line suffix
|
|
386
|
-
(`<path>#<name>@<line>`), so duplicate helpers stay distinct records.
|
|
245
|
+
- Symbol ids are `<path>#<name>`; class methods are `Class.method`. A name defined more than once in one file gets a line suffix (`<path>#<name>@<line>`), so duplicate helpers stay distinct records.
|
|
387
246
|
- Kinds: `function`, `class`, `method`, `type`, `interface`, `enum`, `struct`, `trait`.
|
|
388
|
-
- Edges: `defines`/`defined_in` (file → symbol) and `calls`/`called_by`
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
project-wide (same package directory preferred in Go). A receiver-qualified
|
|
394
|
-
call (`obj.Method()`) resolves only when the receiver is an import
|
|
395
|
-
binding of the file, otherwise it is skipped, never guessed.
|
|
396
|
-
- Label text (symbol names and kinds; AnchorDB attributes are
|
|
397
|
-
numeric-only) is written to `.knowledges/.knl-data/<path>.md`, one file
|
|
398
|
-
per source file that has symbols; override the location with `labelDir`
|
|
399
|
-
in the project config. Labels are regenerated and pruned on every sync.
|
|
400
|
-
|
|
401
|
-
#### Supported Languages (v0.2.0)
|
|
247
|
+
- Edges: `defines`/`defined_in` (file → symbol) and `calls`/`called_by` (symbol → symbol), each stored in both directions because causalChain walks forward only.
|
|
248
|
+
- Call resolution is conservative: a call belongs to its innermost enclosing symbol, and the callee must match exactly one definition project-wide (same package directory preferred in Go). A receiver-qualified call (`obj.Method()`) resolves only when the receiver is an import binding of the file, otherwise it is skipped, never guessed.
|
|
249
|
+
- Label text (symbol names and kinds; AnchorDB attributes are numeric-only) is written to `.knowledges/.knl-data/<path>.md`, one file per source file that has symbols; override the location with `labelDir` in the project config. Labels are regenerated and pruned on every sync.
|
|
250
|
+
|
|
251
|
+
#### Supported Languages (v0.3.1)
|
|
402
252
|
|
|
403
253
|
Tree-sitter WASM grammars run in-memory within Node.js without requiring host compilers:
|
|
404
254
|
|
|
@@ -428,20 +278,23 @@ knl-view sources trace --target=server/index.js --direction=out --hops=2
|
|
|
428
278
|
knl-view sources trace --target=server/index.js#handleTrace --direction=in
|
|
429
279
|
```
|
|
430
280
|
|
|
431
|
-
`sync` is idempotent: run it again after refactoring and only the
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
281
|
+
`sync` is idempotent: run it again after refactoring and only the difference is applied. A target containing `#` traces symbol lineage over `calls`/`called_by`; a plain path traces file lineage over `imports`/`imported_by`. Records the disk no longer has are archived with the native lifecycle opcode 2 (TOMBSTONE: the server hides them from list and lookups) after their edges are unlinked, and the `tombstone = 2` attribute stays as a marker for servers that predate opcode support. `sync` then asks the REST collector to purge those records physically (scoped to the model); run `knl-view sources collect` by hand if the REST endpoint was unreachable at that moment. A reappearing file revives the record with a normal save and relinks its edges. Sync reports `ORPHAN EDGES` when an edge endpoint failed to save, so a broken sync is never silent. The read-only HTTP endpoint answers the same queries: `GET /api/sources/trace?target=<id>&direction=in|out|both&hops=N`.
|
|
282
|
+
|
|
283
|
+
### External Modules Graph (On-Demand Module Boundary)
|
|
284
|
+
|
|
285
|
+
AI agents can parse, index, and trace third-party dependencies on-demand into dedicated global AnchorDB models (`modules-npm`, `modules-go`, `modules-cargo`, `modules-pypi`) without polluting the local project graph or re-syncing across projects:
|
|
286
|
+
|
|
287
|
+
```sh
|
|
288
|
+
# Build & sync external module graph on-demand
|
|
289
|
+
knl-view modules build-graph npm::express
|
|
290
|
+
knl-view modules build-graph go::github.com/gin-gonic/gin
|
|
291
|
+
|
|
292
|
+
# Trace definitions and call hierarchy within the module
|
|
293
|
+
knl-view modules trace npm::express Router --hops=1
|
|
294
|
+
|
|
295
|
+
# List locally indexed modules in ~/.knlview/modules
|
|
296
|
+
knl-view modules list
|
|
297
|
+
```
|
|
445
298
|
|
|
446
299
|
### CLI Query
|
|
447
300
|
|
|
@@ -460,24 +313,104 @@ When `knl-view` is running as a local server:
|
|
|
460
313
|
- `GET /api/consensus?target=<claimId>`: Read-only consensus status for one claim (requires AnchorDB and a mapped `consensus` role). Returns `503` when AnchorDB is off or the role is unmapped, `400` without a target.
|
|
461
314
|
- `GET /api/sources/trace?target=<path>&direction=in|out&hops=2`: Read-only file lineage over the whole-project sources graph (requires AnchorDB and a mapped `sources` role). Returns `503` when unavailable, `400` without a target or with a bad direction.
|
|
462
315
|
|
|
316
|
+
## Operating System Support & Installing AnchorDB
|
|
317
|
+
|
|
318
|
+
### Operating System Support
|
|
319
|
+
|
|
320
|
+
| OS | Core Viewer (`knl-view`) | Global Config Location | AnchorDB Backend |
|
|
321
|
+
| --- | --- | --- | --- |
|
|
322
|
+
| **Linux** | Native (Node.js >= 20.19) | `~/.knlview/knl-config.json` | **Native Binary** (`amd64`, `arm64`) or Container |
|
|
323
|
+
| **macOS** | Native (Node.js >= 20.19) | `~/.knlview/knl-config.json` | **Container**: **Podman (Recommended)** or Docker |
|
|
324
|
+
| **Windows** | Native (Node.js >= 20.19) | `%APPDATA%\knlview\knl-config.json` | **Container**: **Podman (Recommended)** or Docker |
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
### Installing AnchorDB (Optional)
|
|
329
|
+
|
|
330
|
+
AnchorDB is an optional layer. Without it, the viewer runs 100% locally with zero external dependencies: document browsing, full-text search, the Markdown graph engine, and `knl-view graph trace` all work immediately. Installing AnchorDB adds persistent multi-hop causal tracing across sessions, whole-project source code dependency syncing, and shared multi-machine graphs.
|
|
331
|
+
|
|
332
|
+
Run `knl-view install anchordb` to install AnchorDB and write the `anchordb` block into your global configuration:
|
|
333
|
+
|
|
334
|
+
#### 1. Linux (Native Standalone Binary)
|
|
335
|
+
- Native binaries are published on [GitHub Releases](https://github.com/rachmanzz/anchordb/releases) for Linux architectures:
|
|
336
|
+
- `linux_amd64` (x86_64)
|
|
337
|
+
- `linux_arm64` (aarch64)
|
|
338
|
+
- On Linux, `knl-view install anchordb` automatically:
|
|
339
|
+
- Fetches the latest release asset and verifies it against the official `SHA256SUMS.txt`.
|
|
340
|
+
- Installs `anchordb-server` and `anchordb` into `~/.knlview/bin/` with secure file permissions (`0o700` / `0o755`).
|
|
341
|
+
- Starts `anchordb-server` detached as a background process daemon (logs in `~/.knlview/anchordb.log`, data in `~/.knlview/anchordb-data`).
|
|
342
|
+
- You can also explicitly opt for containers on Linux using `--method=container`.
|
|
343
|
+
|
|
344
|
+
#### 2. Windows & macOS (Container via Podman or Docker)
|
|
345
|
+
- AnchorDB relies on Linux kernel primitives (`mmap` memory mapping and POSIX file locking). Native binaries are not yet published for Windows or macOS.
|
|
346
|
+
- For Windows and macOS, AnchorDB is currently deployed via a lightweight container image (`ghcr.io/rachmanzz/anchordb`):
|
|
347
|
+
- **Podman (Recommended)**: Rootless, daemonless, lightweight, and requires no administrative privileges or background daemons.
|
|
348
|
+
- **Docker**: Supported via Docker Desktop or Docker Engine (`--runtime=docker`).
|
|
349
|
+
- `knl-view install anchordb` automatically detects installed container runtimes. If both are found, it prompts you to select **Podman (Recommended)** or **Docker**. If neither is installed, it halts with clear installation guidance.
|
|
350
|
+
|
|
351
|
+
#### Flags & Automation (CI / Scripts)
|
|
352
|
+
- Non-interactive mode: add `--yes` (accepts all defaults).
|
|
353
|
+
- Force install method: `--method=binary` or `--method=container`.
|
|
354
|
+
- Specify container engine: `--runtime=podman` (recommended) or `--runtime=docker`.
|
|
355
|
+
- Custom token: `--token=<text>` (default: cryptographic 32-byte hex token).
|
|
356
|
+
- Port conflict handling: automatically detects if port 17448 is occupied and suggests alternative free ports.
|
|
357
|
+
- Data safety: if a container named `anchordb-knlview` already exists, the installer stops rather than overwriting existing data.
|
|
358
|
+
|
|
359
|
+
## Configuration
|
|
360
|
+
|
|
361
|
+
Two optional config files. A missing file is never an error; a broken file is ignored with one warning on stderr. CLI flags always win over config values.
|
|
362
|
+
|
|
363
|
+
**Global (`~/.knlview/knl-config.json`)**: shared by every project on the machine. Holds the `anchordb` block. Without it, AnchorDB stays completely off and the viewer runs fully local:
|
|
364
|
+
|
|
365
|
+
```json
|
|
366
|
+
{
|
|
367
|
+
"anchordb": {
|
|
368
|
+
"url": "wire://127.0.0.1:17448",
|
|
369
|
+
"token": "your-token",
|
|
370
|
+
"sync": true,
|
|
371
|
+
"deamon": "podman",
|
|
372
|
+
"container_name": "anchordb-knlview",
|
|
373
|
+
"container_id": "56519e7acbaa...",
|
|
374
|
+
"container_created_on": "2026-10-31 14:08:48..."
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
**Per project: `knl-config.json` at the project root** (gitignored):
|
|
380
|
+
`path`, `port`, `host`, `models`, and optional `include` / `exclude` patterns:
|
|
381
|
+
|
|
382
|
+
```json
|
|
383
|
+
{
|
|
384
|
+
"port": 8091,
|
|
385
|
+
"models": {
|
|
386
|
+
"knowledges": "vez0vqrp",
|
|
387
|
+
"consensus": "n0qrnmsz"
|
|
388
|
+
},
|
|
389
|
+
"include": ["dist/bundle.js"],
|
|
390
|
+
"exclude": ["legacy/**", "*.tmp"]
|
|
391
|
+
}
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
- `exclude`: Hard exclude that strictly filters files and folders from graph analysis and knowledge tree. Always takes precedence over defaults and includes.
|
|
395
|
+
- `include`: Whitelists files and folders. Overrides default directory exclusions (e.g. including files from `dist/` or dot-folders).
|
|
396
|
+
|
|
397
|
+
Model names are owned by the `models` map: role → name, and the name can be anything (random names are fine; the map records what each name is *for*). Names stay stable even if the project folder is renamed. knl-view never invents names by itself: create them with `knl-view model new <role>` (writes the map and the global registry), and inspect ownership with `knl-view model check`.
|
|
398
|
+
|
|
399
|
+
The global registry `~/.knlview/models.json` records every name's owner (project, role, path) and warns when two projects claim the same name. A project whose map has no entry for a role runs fully local: AnchorDB is touched only once the role is mapped.
|
|
400
|
+
|
|
463
401
|
## Development
|
|
464
402
|
|
|
465
403
|
```sh
|
|
466
404
|
npm run dev
|
|
467
405
|
```
|
|
468
406
|
|
|
469
|
-
Starts the API on port 8085 (override with `PORT`) and the Vite dev server on
|
|
470
|
-
5173 (override with `WEB_PORT`). Pass a base folder as the first argument:
|
|
407
|
+
Starts the API on port 8085 (override with `PORT`) and the Vite dev server on 5173 (override with `WEB_PORT`). Pass a base folder as the first argument:
|
|
471
408
|
|
|
472
409
|
```sh
|
|
473
410
|
npm run dev -- ../some-project/.knowledges
|
|
474
411
|
```
|
|
475
412
|
|
|
476
|
-
`dist/` is committed to this repository so that installs straight from GitHub
|
|
477
|
-
keep working, because npm runs no build step for a git install without a
|
|
478
|
-
`prepare` script. After changing the frontend, run `npm run build` and commit
|
|
479
|
-
the result together with the source, or those installs stay on the previous
|
|
480
|
-
build.
|
|
413
|
+
`dist/` is committed to this repository so that installs straight from GitHub keep working, because npm runs no build step for a git install without a `prepare` script. After changing the frontend, run `npm run build` and commit the result together with the source, or those installs stay on the previous build.
|
|
481
414
|
|
|
482
415
|
## License
|
|
483
416
|
|