@rahmantech/knl-view 0.1.0 → 0.3.0

package/README.md

@@ -27,6 +27,8 @@ knl-view --port 8086 --path=.knowledges
   that narrows the index by file title or path.
 - Interface in English or Indonesian, switchable in the top bar. English is the
   default.
+- Whole-project dependency and symbol call graph extraction via WebAssembly
+  Tree-Sitter for JavaScript, TypeScript, Go, Python, and Rust.
 
 ## Requirements
 
@@ -73,9 +75,39 @@ GitHub commit without cloning, run
 `--install-links`, npm 11 links against a temporary clone it deletes
 afterwards, which leaves a broken install.
 
+## How to Set Up
+
+Setting up a project takes a single command:
+
+```sh
+knl-view setup
+```
+
+Or run directly without installing:
+
+```sh
+npx @rahmantech/knl-view setup
+```
+
+### What `knl-view setup` Does Automatically
+1. **Scaffolds `.knowledges/`**: Creates the documentation directory with a starter `README.md` index and template folders (or custom folders via `--folders`).
+2. **Installs Agent Skills**: Automatically places the `knl-view` skill into `.agents/skills/knl-view/` so coding agents (Antigravity, Claude, Codex, OpenCode) can read and manage your knowledge base.
+3. **Integrates Decision History**: Audits and offers to install the `decision-history` skill ([decisionskills](https://github.com/rachmanzz/decisionskills)) for append-only architecture decision tracking.
+4. **Protects Configuration**: Ensures `.gitignore` includes `knl-config.json` and temporary artifacts.
+5. **Auto-maps AnchorDB Models**: Configures `knowledges` and `sources` model identifiers in `knl-config.json` and records them in the machine-wide registry.
+6. **Provisions AnchorDB**: Prompts to start or provision an AnchorDB instance (native binary on Linux, Podman/Docker container on Windows & macOS).
+7. **Seeds Agent Rules**: Configures standardized KNL-View instructions in `AGENTS.md`, `GEMINI.md`, and `CLAUDE.md`.
+
+After setup, start the viewer immediately:
+
+```sh
+knl-view
+```
+
 ## Usage
 
 ```sh
+knl-view setup                             # bootstrap project (scaffold base, skill, gitignore, models)
 knl-view                                   # serve ./.knowledges on 127.0.0.1:8085
 knl-view --path=../other-project/.knowledges
 knl-view --port 8086 --host 0.0.0.0        # expose on the network
@@ -93,6 +125,8 @@ knl-view --seed-skill=knl-view --dir=global --yes
 | `--anchordb` | none | AnchorWire URL (`wire://host:port?token=...`) for this session; overrides the global config block |
 | `--target` | none | Target node ID for CLI subgraph trace (`knl-view graph trace`) |
 | `--hops` | `2` | Traversal depth radius for subgraph extraction |
+| `--method` | auto | Install method for `install anchordb`: `binary` or `container` |
+| `--runtime` | auto | Container runtime for `install anchordb`: `docker` or `podman` |
 | `--init` | off | Scaffold a new base interactively; does not start the server |
 | `--structure` | `standard` | Layout for a non-interactive `--init`: `standard`, `empty`, or `custom` |
 | `--folders` | none | Comma-separated folder names for `--structure=custom` |
@@ -118,15 +152,19 @@ off and the viewer runs fully local:
 ```json
 {
   "anchordb": {
-    "url": "wire://127.0.0.1:7448",
+    "url": "wire://127.0.0.1:17448",
     "token": "your-token",
-    "sync": true
+    "sync": true,
+    "deamon": "podman",
+    "container_name": "anchordb-knlview",
+    "container_id": "56519e7acbaa...",
+    "container_created_on": "2026-10-31 14:08:48..."
   }
 }
 ```
 
-**Per project: `knl-config.json` at the project root** (gitignored): only
-`path`, `port`, `host`, and a `models` map, never the anchordb connection:
+**Per project: `knl-config.json` at the project root** (gitignored):
+`path`, `port`, `host`, `models`, and optional `include` / `exclude` patterns:
 
 ```json
 {
@@ -134,10 +172,15 @@ off and the viewer runs fully local:
   "models": {
     "knowledges": "vez0vqrp",
     "consensus": "n0qrnmsz"
-  }
+  },
+  "include": ["dist/bundle.js"],
+  "exclude": ["legacy/**", "*.tmp"]
 }
 ```
 
+- `exclude`: Hard exclude that strictly filters files and folders from graph analysis and knowledge tree. Always takes precedence over defaults and includes.
+- `include`: Whitelists files and folders. Overrides default directory exclusions (e.g. including files from `dist/` or dot-folders).
+
 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
@@ -150,29 +193,48 @@ The global registry `~/.knlview/models.json` records every name's owner
 project whose map has no entry for a role runs fully local: AnchorDB is
 touched only once the role is mapped.
 
-## Installing AnchorDB (optional)
+## Operating System Support & Installing AnchorDB
+
+### Operating System Support
 
-AnchorDB is an optional layer. Without it the viewer runs fully local:
-everything (browsing, search, the graph engine, and `knl-view graph trace`)
-works with zero setup. Installing AnchorDB only adds persistent causal
-tracing across sessions and shared sync between machines.
+| OS | Core Viewer (`knl-view`) | Global Config Location | AnchorDB Backend |
+| --- | --- | --- | --- |
+| **Linux** | Native (Node.js >= 20.19) | `~/.knlview/knl-config.json` | **Native Binary** (`amd64`, `arm64`) or Container |
+| **macOS** | Native (Node.js >= 20.19) | `~/.knlview/knl-config.json` | **Container**: **Podman (Recommended)** or Docker |
+| **Windows** | Native (Node.js >= 20.19) | `%APPDATA%\knlview\knl-config.json` | **Container**: **Podman (Recommended)** or Docker |
 
-`knl-view install anchordb` installs AnchorDB and writes the `anchordb`
-block into the global config:
+---
 
-- **Linux and macOS**: downloads the native binary from
-  [GitHub Releases](https://github.com/rachmanzz/anchordb/releases),
-  verifies it against the release's `SHA256SUMS.txt`, installs to
-  `~/.knlview/bin/`, and starts `anchordb-server` detached (logs in
-  `~/.knlview/anchordb.log`, data in `~/.knlview/anchordb-data`).
-- **Other platforms**: a Linux container from
-  `ghcr.io/rachmanzz/anchordb` via docker or podman; the command refuses
-  to continue if neither is installed.
+### Installing AnchorDB (Optional)
 
-Non-interactive (CI/scripts): add `--yes`. Explicit method: `--method=binary`
-or `--method=container`. Fixed token instead of a random one: `--token=...`.
-If a container named `anchordb-knlview` already exists, the installer stops
-instead of removing it: data must not disappear by accident.
+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.
+
+Run `knl-view install anchordb` to install AnchorDB and write the `anchordb` block into your global configuration:
+
+#### 1. Linux (Native Standalone Binary)
+- Native binaries are published on [GitHub Releases](https://github.com/rachmanzz/anchordb/releases) for Linux architectures:
+  - `linux_amd64` (x86_64)
+  - `linux_arm64` (aarch64)
+- On Linux, `knl-view install anchordb` automatically:
+  - Fetches the latest release asset and verifies it against the official `SHA256SUMS.txt`.
+  - Installs `anchordb-server` and `anchordb` into `~/.knlview/bin/` with secure file permissions (`0o700` / `0o755`).
+  - Starts `anchordb-server` detached as a background process daemon (logs in `~/.knlview/anchordb.log`, data in `~/.knlview/anchordb-data`).
+- You can also explicitly opt for containers on Linux using `--method=container`.
+
+#### 2. Windows & macOS (Container via Podman or Docker)
+- AnchorDB relies on Linux kernel primitives (`mmap` memory mapping and POSIX file locking). Native binaries are not yet published for Windows or macOS.
+- For Windows and macOS, AnchorDB is currently deployed via a lightweight container image (`ghcr.io/rachmanzz/anchordb`):
+  - **Podman (Recommended)**: Rootless, daemonless, lightweight, and requires no administrative privileges or background daemons.
+  - **Docker**: Supported via Docker Desktop or Docker Engine (`--runtime=docker`).
+- `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.
+
+#### Flags & Automation (CI / Scripts)
+- Non-interactive mode: add `--yes` (accepts all defaults).
+- Force install method: `--method=binary` or `--method=container`.
+- Specify container engine: `--runtime=podman` (recommended) or `--runtime=docker`.
+- Custom token: `--token=<text>` (default: cryptographic 32-byte hex token).
+- Port conflict handling: automatically detects if port 17448 is occupied and suggests alternative free ports.
+- Data safety: if a container named `anchordb-knlview` already exists, the installer stops rather than overwriting existing data.
 
 ## How a base is read
 
@@ -207,10 +269,10 @@ Every entry is decoration. Nothing in it can invent a file that is not on disk.
     "coding-rules.md": { "title": "Coding rules", "order": 1 }
   },
   "files": {
-    "rahasia.md": { "ignore": true }
+    "secret.md": { "ignore": true }
   },
   "dirs": {
-    "draft-lama": { "ignore": true }
+    "old-drafts": { "ignore": true }
   }
 }
 ```
@@ -310,18 +372,19 @@ 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 (the
-JS family and Go today, one grammar package per language) 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.
+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.
 
 Each file also defines **symbol nodes**, extracted from the same parse:
 
 - 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.
-- Kinds: `function`, `class`, `method`, `type` (Go type declarations).
+- Kinds: `function`, `class`, `method`, `type`, `interface`, `enum`, `struct`, `trait`.
 - Edges: `defines`/`defined_in` (file → symbol) and `calls`/`called_by`
   (symbol → symbol), each stored in both directions because causalChain
   walks forward only.
@@ -335,6 +398,28 @@ Each file also defines **symbol nodes**, extracted from the same parse:
   per source file that has symbols; override the location with `labelDir`
   in the project config. Labels are regenerated and pruned on every sync.
 
+#### Supported Languages (v0.3.0)
+
+Tree-sitter WASM grammars run in-memory within Node.js without requiring host compilers:
+
+| Language | Extensions | Extracted Symbols | Import Resolution |
+| :--- | :--- | :--- | :--- |
+| **JavaScript** | `.js`, `.mjs`, `.cjs`, `.jsx` | `function`, `class`, `method` | ESM (`import`/`export`), dynamic `import()`, CJS `require()` |
+| **TypeScript** | `.ts`, `.mts`, `.cts`, `.tsx` | `function`, `class`, `method`, `interface`, `type`, `enum` | ESM/CJS, automatic resolution of `.js` specifiers to `.ts`/`.tsx` on disk |
+| **Go** | `.go` | `function`, `method` (receiver-qualified), `type` | `go.mod` module-internal packages |
+| **Python** | `.py` | `function`, `class`, `method` | Relative imports (`.local`, `..pkg`) and dot-separated package paths |
+| **Rust** | `.rs` | `function`, `method` (`impl`), `struct`, `enum`, `trait`, `type` | `mod <name>;`, `use crate::`, `use super::`, `use self::` |
+
+#### Upcoming Languages (Planned for Next Versions)
+
+Support for additional languages via WebAssembly Tree-Sitter grammars will be added in upcoming releases:
+
+- **Java** (`.java`): Class, interface, record, method extraction, package imports
+- **C / C++** (`.c`, `.h`, `.cpp`, `.hpp`): Functions, structs, classes, `#include` resolution
+- **C#** (`.cs`): Classes, structs, interfaces, methods, namespaces/using
+- **Ruby** (`.rb`): Modules, classes, methods, `require_relative`
+- **PHP** (`.php`): Classes, interfaces, traits, functions, namespaces/use
+
 ```sh
 knl-view model new sources
 knl-view sources sync
@@ -358,6 +443,22 @@ record with a normal save and relinks its edges. Sync reports
 never silent. The read-only HTTP endpoint answers the same queries:
 `GET /api/sources/trace?target=<id>&direction=in|out|both&hops=N`.
 
+### External Modules Graph (On-Demand Module Boundary)
+
+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:
+
+```sh
+# Build & sync external module graph on-demand
+knl-view modules build-graph npm::express
+knl-view modules build-graph go::github.com/gin-gonic/gin
+
+# Trace definitions and call hierarchy within the module
+knl-view modules trace npm::express Router --hops=1
+
+# List locally indexed modules in ~/.knlview/modules
+knl-view modules list
+```
+
 ### CLI Query
 
 ```sh