Contributing to KonsolScript

Resources for contributors to libkonsolscript, authors of KonsolScript plugins, and embedders integrating the library into a host application.

→ Script authors: see Scripting Guide

Source layout

libkonsolscript - the interpreter
Public SDK headers
Bundled plugins
Example applications
minks - the CLI

Adding a built-in module
Writing a plugin
Building the bundled plugins
Embedding libkonsolscript in a host application

Source layout

`libkonsolscript` - the interpreter (shared library)

All files compiled into libkonsolscript.dll / .so / .dylib:

Path	Contents
`core/kse.cpp`	Engine core: tokenizer, evaluator (`evalExpr` → … → `evalAtom` chain), `execute`, `loadScript`, `run`, `eval`, `reloadFile`
`core/kse.hpp`	Engine public API and private declarations; includes `reloadFile(path)`, `setEvalGuard(fn)`, `EvalGuard` type
`core/kse_types.hpp`	`Value`, `Token`, `CMD_*` constants, `KseException`, `ListVar`, `DictionaryVar`, `ArrayVar`, `ClassDef`, `CallFrame`
`core/kse_dynload.hpp`	Platform DL helpers (`lib_open/sym/close`), `DYNLIB_EXT`, `userPluginDir()`
`cls/kse_var.cpp`	`Var:` declarations (Number/String/Boolean/UDT/Class)
`cls/kse_array.cpp`	`Array:` module; `Engine::arrayGet` / `Engine::arraySet`; `ArrayException`
`cls/kse_math.cpp`	`Math:` module; `MathException`
`cls/kse_string.cpp`	`String:` module
`cls/kse_file.cpp`	`File:` module
`cls/kse_time.cpp`	`Time:` module
`cls/kse_konsol.cpp`	`Konsol:` module
`cls/kse_class.cpp`	`Class:Create` (class definitions); `Class:TypeName name` non-generic instantiation
`cls/kse_object.cpp`	Built-in `Object` and `Exception` class definitions
`cls/kse_list.cpp`	`List:` module
`cls/kse_dictionary.cpp`	`Dictionary:` module
`cls/kse_json.cpp`	`JSON:` module
`cls/kse_os.cpp`	`OS:` module
`cls/kse_path.cpp`	`Path:` module
`cls/kse_hash.cpp`	`Hash:` module
`cls/kse_date.cpp`	`Date:` module
`cls/kse_csv.cpp`	`CSV:` module
`cls/kse_regex.cpp`	`Regex:` module
`ctrl/kse_try.cpp`	`try` / `catch` / `finally` / `throw`
`ctrl/kse_if.cpp`	`if` / `else if` / `else`
`ctrl/kse_while.cpp`	`while` loop
`ctrl/kse_for.cpp`	`for` loop
`ctrl/kse_switch.cpp`	`switch` / `case` / `default`
`ctrl/kse_foreach.cpp`	`foreach` loop
`ctrl/kse_return.cpp`	`return` / `break` / `continue` statements

Public SDK headers

Header-only files in minks/ that embedders and plugin authors include directly. Not compiled into libkonsolscript.

Header	Contents
`minks_plugin.h`	Plugin SDK - `PluginClass` builder, `registerPluginException`, `throwPluginException`
`kse_watch.hpp`	File watcher for hot-reload - `FileWatcher` class; poll and background-thread modes; pairs with `Engine::reloadFile()`

Bundled plugins

Each plugin is a standalone shared library in its own subdirectory:

Path	Module(s)	Library
`curl_plugin/kse_curl.cpp`	`Curl:`	libcurl
`sqlite_plugin/kse_sqlite.cpp`	`SQLite:`	SQLite amalgamation
`mysql_plugin/kse_mysql.cpp`	`MySQL:` / `Maria:`	libmysqlclient / libmariadb
`pg_plugin/kse_pg.cpp`	`PG:`	libpq
`redis_plugin/kse_redis.cpp`	`Redis:`	hiredis
`zip_plugin/kse_zip.cpp`	`Zip:`	libzip
`crypto_plugin/kse_crypto.cpp`	`Crypto:`	OpenSSL
`ws_plugin/kse_ws.cpp`	`WS:`	libcurl ≥ 7.86
`net_plugin/kse_net.cpp`	`Net:`	ws2_32 (Windows) / sockets
`jwt_plugin/kse_jwt.cpp`	`JWT:`	OpenSSL (same as `crypto_plugin`)
`sample_plugin/kse_sample.cpp`	`Sample:`	none - reference plugin implementation

Example applications

Path	Contents
`demo_ai_bridge/`	Complete AI event bridge demo - C++ game host embeds libkonsolscript; a `.ks` script calls Claude and ships generated event scripts over LAN for live `engine.eval()`. See AI Bridge Demo
`demo_hotreload/`	Hot-reload demo - C++ host uses `FileWatcher` (poll mode) + `Engine::reloadFile()` to live-reload a `.ks` script; calls `tick()` each second so behavior changes take effect without restarting the host
`sample_app/`	Minimal C++ host embedding `libkonsolscript`; demonstrates the embedding API

`minks` - the CLI (single file)

Path	Contents
`main.cpp`	CLI entry point; argument parsing; `--plugin-path`, `--check`, `--debug`, `--sandbox`; REPL; `install`/`remove`/`list` package manager subcommands; uncaught `KseException` handler (exit code 2)

main.cpp links dynamically against libkonsolscript. Any other host application embedding the library must add its own catch (const KseException&) around engine.run().

Adding a built-in module

→ Adding a Module

Writing a plugin

Plugins are shared libraries that add new modules to KonsolScript without recompiling libkonsolscript. Use the PluginClass builder from minks_plugin.h.

Run make-plugin.ks to generate a C++ starter template, Makefile, and optionally a manifest in one interactive session:

minks make-plugin.ks

→ Plugin System

Building the bundled plugins

Each plugin's build instructions (dependency install + make command) live in its own doc:

curl_plugin - libcurl
zip_plugin - libzip
net_plugin - no extra dependency
sqlite_plugin - SQLite amalgamation (bundled)
mysql_plugin - libmysqlclient / libmariadb
pg_plugin - libpq
redis_plugin - hiredis
crypto_plugin - OpenSSL
ws_plugin - libcurl ≥ 7.86
jwt_plugin - OpenSSL (no curl needed)
sample_plugin - no extra dependency (reference implementation)

Selective build and clean targets:

Build	Clean	What
`make`	`make clean`	everything
`make konsolscript`	`make clean-konsolscript`	libkonsolscript only
`make static`	`make clean-static`	static archive `libkonsolscript.a`
`make minks`	`make clean-minks`	minks binary only
`make plugin`	`make clean-plugin`	all plugins + sample_plugin
`make demo`	`make clean-demo`	AI Bridge Demo + demo_hotreload + sample_app

Plugins and demo automatically depend on libkonsolscript - if its headers change, make plugin rebuilds the lib first then all plugins. If only the implementation changes (no header changes), run make clean-plugin && make plugin to force a relink.

Embedding libkonsolscript in a host application

Link libkonsolscript into any C++17 application to make it scriptable.

→ Embedding API