From 3900e664f8871a1b67c8cd78888979814abeec6a Mon Sep 17 00:00:00 2001 From: GaspardKirira Date: Sun, 21 Dec 2025 09:12:35 +0300 Subject: [PATCH 1/4] docs(readme): fix incorrect code example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6b7229d..1c0b77d 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ using namespace Vix; int main() { App app; - app.get("/", [](Request, Request res) { + app.get("/", [](Request req, Response res) { res.json({ "message", "Hello world" }); }); From 0b501e35907a4924937131809476520131895f57 Mon Sep 17 00:00:00 2001 From: Gaspard Kirira Date: Sun, 21 Dec 2025 11:12:42 +0300 Subject: [PATCH 2/4] chore(core): update core submodule (sync inflight timeout + permanent failure handling) --- modules/core | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/core b/modules/core index 85dd2de..9529028 160000 --- a/modules/core +++ b/modules/core @@ -1 +1 @@ -Subproject commit 85dd2de3de4844947172afc467ca81ebd923f42d +Subproject commit 95290285a369d29d4003f2f628c22f56136c8149 From ba2264c06be060f23b4ad432b062a3a4985e251b Mon Sep 17 00:00:00 2001 From: Gaspard Kirira Date: Sun, 21 Dec 2025 23:21:23 +0300 Subject: [PATCH 3/4] chore(submodules): bump cli to v1.13.1 --- modules/cli | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/cli b/modules/cli index 16858b1..0d8a31d 160000 --- a/modules/cli +++ b/modules/cli @@ -1 +1 @@ -Subproject commit 16858b12c29b8a05456aed492df3f94c09d8cd04 +Subproject commit 0d8a31d276d711d95a60705c88a70e3509c800d7 From b9b573adaf6ab60fce5a454714caa6fe582549c4 Mon Sep 17 00:00:00 2001 From: Gaspard Kirira Date: Mon, 22 Dec 2025 00:30:01 +0300 Subject: [PATCH 4/4] =?UTF-8?q?release(cli):=20v1.16.0=20=E2=80=94=20defau?= =?UTF-8?q?lt=20REPL,=20improved=20UX=20and=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 68 +++++++++- CMakeLists.txt | 2 +- README.md | 74 ++++++++++ docs/README_REPL.md | 258 +++++++++++++++++++++++++++++++++++ docs/modules/cli.md | 322 +++++++++++++++++++++++++++++--------------- modules/cli | 2 +- 6 files changed, 612 insertions(+), 114 deletions(-) create mode 100644 docs/README_REPL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 18d3a47..0a52623 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,17 +8,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- ## [Unreleased] + +## 1.16.0 โ€” 2025-01-XX + +### ๐Ÿš€ Highlights + +- **REPL is now the default mode** + Running `vix` starts the interactive shell automatically + (no more `vix repl`). + +- **Modern runtime experience** + Behavior aligned with Python, Node.js, and Deno. + +--- + +### โœจ Added + +- Default interactive REPL when running `vix` +- Dedicated `README_REPL.md` with: + - Math expressions + - Variables + - JSON usage + - `print` / `println` + - Built-in `Vix` API examples +- Improved CLI documentation (`docs/modules/cli.md`) + +--- + +### ๐Ÿง  Improved + +- REPL argument evaluation: + - Correct handling of string literals + - Math expressions with variables + - Mixed arguments (`println("x =", x+1)`) +- REPL execution flow stability +- Error messages clarity in interactive mode +- Overall CLI UX consistency + +--- + +### ๐Ÿงน Changed + +- Removed `vix repl` as a required entry point +- REPL is now the primary interaction mode +- CLI documentation updated to reflect new behavior + +--- + +### ๐Ÿ”ง Internal + +- REPL flow refactoring and cleanup +- Better separation between CLI dispatcher and REPL runtime +- Documentation structure improvements + +--- + +### โš ๏ธ Notes + +- JSON literals must be **strictly valid JSON** + (`{"key":"value"}`, not `{key, value}`) + ## [1.15.0] - 2025-12-20 ### Added -- + +- ### Changed -- + +- ### Removed -- +- ## v1.15.0 โ€” 2025-12-20 diff --git a/CMakeLists.txt b/CMakeLists.txt index ec552e6..1d9c1ff 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -13,7 +13,7 @@ cmake_minimum_required(VERSION 3.20) # cmake --build build -j # ==================================================================== -project(vix VERSION 1.15.0 LANGUAGES CXX) +project(vix VERSION 1.16.0 LANGUAGES CXX) # Make find_package honor *_ROOT hints (e.g. MYSQLCPPCONN_ROOT) if (POLICY CMP0144) diff --git a/README.md b/README.md index 1c0b77d..27b5005 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,80 @@ app.get("/users/{id}", [](Request req, Response res) { }); ``` +# ๐Ÿง  Vix REPL โ€” Interactive Runtime Shell + +## โ–ถ๏ธ Starting the REPL + +```bash +vix +``` + +Example startup: + +``` +Vix.cpp v1.x (CLI) โ€” Modern C++ backend runtime +[GCC 13.3.0] on linux +Exit: Ctrl+C / Ctrl+D | Clear: Ctrl+L | Type help for help +vix> +``` + +--- + +## ๐Ÿงฎ Math Expressions + +You can type expressions directly: + +```text +1 + 2 +10 * (3 + 4) +``` + +## ๐Ÿงฉ JSON Support + +The REPL supports **strict JSON** using `nlohmann::json`. + +### Objects + +```text +user = {"name":"Gaspard","age":10} +user +``` + +### Arrays + +```text +nums = [1,2,3,4] +nums +``` + +## ๐Ÿ–จ๏ธ print / println + +### Basic output + +```text +print("Hello") +println("Hello world") +``` + +### Mix strings and expressions + +```text +x = 3 +println("x =", x) +println("x+1 =", x+1) +``` + +## โš™๏ธ Built-in Vix API + +The REPL exposes a built-in `Vix` object. + +### Working directory + +```text +cwd() +Vix.cwd() +``` + ### Minimal HTTP + WebSocket Server This example shows the **smallest fully working HTTP + WS hybrid server**. diff --git a/docs/README_REPL.md b/docs/README_REPL.md new file mode 100644 index 0000000..a686dc1 --- /dev/null +++ b/docs/README_REPL.md @@ -0,0 +1,258 @@ +# ๐Ÿง  Vix REPL โ€” Interactive Runtime Shell + +The **Vix REPL** is an interactive shell built directly into the `vix` binary. +Just like **python**, **node**, or **deno**, you start it simply by typing: + +```bash +vix +``` + +No subcommand. No flags. +This is the **default interactive mode** of Vix. + +--- + +## โœจ What is the Vix REPL? + +The Vix REPL is a **developer-friendly interactive environment** designed to: + +- Experiment with C++-like expressions +- Test runtime logic quickly +- Evaluate math expressions +- Manipulate variables and JSON data +- Call built-in Vix runtime APIs +- Prototype logic before moving to real code + +It feels familiar if youโ€™ve used: + +- Python REPL +- Node.js REPL +- Deno REPL + +โ€ฆbut adapted to the **Vix.cpp philosophy**. + +--- + +## โ–ถ๏ธ Starting the REPL + +```bash +vix +``` + +Example startup: + +``` +Vix.cpp v1.x (CLI) โ€” Modern C++ backend runtime +[GCC 13.3.0] on linux +Exit: Ctrl+C / Ctrl+D | Clear: Ctrl+L | Type help for help +vix> +``` + +--- + +## ๐Ÿงฎ Math Expressions + +You can type expressions directly: + +```text +1 + 2 +10 * (3 + 4) +``` + +With variables: + +```text +x = 3 +x + 1 +x * 10 +``` + +--- + +## ๐Ÿ“ฆ Variables + +### Assign values + +```text +x = 42 +name = "Gaspard" +``` + +### Print variables + +```text +x +name +``` + +--- + +## ๐Ÿงฉ JSON Support + +The REPL supports **strict JSON** using `nlohmann::json`. + +### Objects + +```text +user = {"name":"Gaspard","age":10} +user +``` + +### Arrays + +```text +nums = [1,2,3,4] +nums +``` + +### Nested data + +```text +profile = { + "name":"Gaspard", + "meta":{"country":"UG","verified":true}, + "tags":["cpp","vix","repl"] +} +profile +``` + +> โš ๏ธ JSON must be **valid** +> โŒ `{ "name", "Gaspard" }` +> โœ… `{ "name": "Gaspard" }` + +--- + +## ๐Ÿ–จ๏ธ print / println + +### Basic output + +```text +print("Hello") +println("Hello world") +``` + +### Mix strings and expressions + +```text +x = 3 +println("x =", x) +println("x+1 =", x+1) +``` + +--- + +## โš™๏ธ Built-in Vix API + +The REPL exposes a built-in `Vix` object. + +### Working directory + +```text +cwd() +Vix.cwd() +``` + +### Change directory + +```text +Vix.cd("..") +``` + +### Process info + +```text +pid() +Vix.pid() +``` + +### Environment variables + +```text +Vix.env("HOME") +Vix.env("PATH") +``` + +### Arguments + +```text +Vix.args() +``` + +--- + +## ๐Ÿ› ๏ธ Filesystem helpers + +```text +Vix.mkdir("tmp") +Vix.mkdir("tmp/logs", true) +``` + +--- + +## โ–ถ๏ธ Running CLI commands + +You can run CLI commands **from inside the REPL**: + +```text +Vix.run("version") +Vix.run("help") +Vix.run("check", "--help") +``` + +--- + +## ๐Ÿงน Session control + +### Clear screen + +```text +clear +``` + +or: + +```text +Ctrl + L +``` + +### Exit REPL + +```text +exit +``` + +or: + +```text +Ctrl + D +Ctrl + C +``` + +--- + +## ๐Ÿง  Tips & Best Practices + +- Use the REPL to **prototype logic** +- Validate math & JSON before writing C++ +- Use `println()` for debugging expressions +- Treat the REPL as your **scratchpad** + +--- + +## ๐Ÿงญ Roadmap (REPL) + +Planned features: + +- Property access: `user.name` +- Function definitions +- History persistence +- Autocomplete for variables +- Structured error hints +- Module imports + +--- + +## ๐Ÿงพ License + +MIT License ยฉ Gaspard Kirira +Part of the **Vix.cpp** ecosystem diff --git a/docs/modules/cli.md b/docs/modules/cli.md index bafedd7..8448469 100644 --- a/docs/modules/cli.md +++ b/docs/modules/cli.md @@ -1,200 +1,304 @@ # ๐Ÿงฉ Vix.cpp โ€” CLI Module -![C++20](https://img.shields.io/badge/C%2B%2B-20-blue.svg) -![MIT](https://img.shields.io/badge/License-MIT-green) -![Status](https://img.shields.io/badge/Module-Stable-success) -![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey) +### Modern C++ Runtime Tooling โ€ข Zero-Friction Development โ€ข Fast Web Apps -> The **Vix CLI** (`vix`) is the official command-line interface for -> **Vix.cpp โ€” the offline-first, ultra-fast C++ runtime**. +![C++](https://img.shields.io/badge/C%2B%2B-20-blue.svg) +![License](https://img.shields.io/badge/License-MIT-green) +![Status](https://img.shields.io/badge/Status-Stable-success) +![Platform](https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Windows-lightgrey) +![Runtime](https://img.shields.io/badge/Runtime-Vix.cpp%201.x-orange) + +> **Vix CLI** is the official command-line interface for +> **Vix.cpp** โ€” the modern C++ backend runtime. > -> It provides a clean developer experience similar to _Cargo_, _Deno_, or _Vue CLI_, -> but natively powered by **C++20** and **fast incremental CMake builds**. +> It provides a **professional, modern, runtime-like developer experience** +> for C++, comparable to **Python**, **Node.js**, **Deno**, or **Bun**. --- # ๐Ÿš€ Overview -The CLI is designed to offer a **zero-friction workflow**: +The Vix CLI (`vix`) brings modern runtime ergonomics to C++: -- create a new project in one command -- build it instantly -- run it with auto-compile and execution -- support direct `.cpp` execution (script mode) +- Instant project creation +- Smart CMake-based builds +- Friendly compiler diagnostics +- Sanitizer-first validation +- Script-like execution of `.cpp` files +- Packaging & artifact verification +- Built-in interactive REPL (**default**) -Whether you're building a microservice, a full backend, or experimenting locally, -the Vix CLI is the fastest way to work with Vix.cpp. +Running `vix` with no arguments launches the **interactive REPL**. --- # โš™๏ธ Features -### ๐Ÿ— Project Generation +## ๐Ÿง  Built-in REPL (default) -`vix new ` scaffolds a new Vix application with: +```bash +vix +``` -- CMakeLists.txt -- src/main.cpp -- README.md -- .gitignore +- Variables & expressions +- JSON literals +- Math evaluation +- Runtime APIs (`Vix.cwd()`, `Vix.env()`, etc.) +- Script-like exploration -### โšก Smart Build System +Explicit mode: -`vix build` automatically: +```bash +vix repl +``` -- detects CMake presets -- performs incremental builds -- handles compile_commands.json -- avoids unnecessary rebuilds +--- -### ๐Ÿš€ Automatic Run +## ๐Ÿ—๏ธ Project scaffolding -`vix run`: +```bash +vix new blog +``` -- builds if needed -- selects the correct executable -- passes your runtime arguments -- handles script mode (.cpp execution) +Creates: -### ๐Ÿ”ง Unified Logging +- CMake-based project +- Modern C++20 structure +- Ready-to-run Vix app -Supports: +--- -``` ---log-level trace|debug|info|warn|error|critical ---quiet ---verbose +## โšก Smart build system + +```bash +vix build ``` +- Uses CMake presets automatically +- Parallel builds +- Colored logs & spinners +- Clean Ctrl+C handling + --- -# ๐Ÿงฐ Commands +## ๐Ÿš€ Run applications +```bash +vix run ``` -vix [GLOBAL OPTIONS] [ARGS...] + +- Auto-build if required +- Real-time logs +- Runtime log-level injection + +Script mode: + +```bash +vix run demo.cpp ``` -## Project Commands +--- + +## ๐Ÿงช Check & Tests (Sanitizers ready) + +Compile-only validation: -| Command | Description | -| ------------ | -------------------------- | -| `new ` | Scaffold a new Vix project | +```bash +vix check +vix check demo.cpp +``` -## Development Commands +With sanitizers: -| Command | Description | -| --------------------- | ------------------------------------------ | -| `build [name]` | Configure and build a project | -| `run [name] [--args]` | Build if needed, then run | -| `run file.cpp` | Script mode: compile & run a single `.cpp` | +```bash +vix check demo.cpp --san +vix check demo.cpp --asan +vix check demo.cpp --ubsan +vix check demo.cpp --tsan +``` -## Info Commands +Run tests: -| Command | Description | -| --------- | ----------------- | -| `help` | Show help | -| `version` | Show version info | +```bash +vix tests +vix tests --san +``` --- -# ๐ŸŒ Global Options +## ๐Ÿ“ฆ Packaging & Verification + +Create a distribution artifact: + +```bash +vix pack --name blog --version 1.0.0 +``` -| Option | Description | -| --------------------- | -------------------- | -| `--log-level ` | Set log level | -| `--verbose` | Debug-level logs | -| `--quiet` | Only warnings/errors | -| `-h`, `--help` | Show CLI help | -| `-v`, `--version` | Show CLI version | +Verify artifacts: + +```bash +vix verify dist/blog@1.0.0 +vix verify dist/blog@1.0.0 --require-signature +``` --- -# ๐ŸŒฑ Environment Variables +## ๐Ÿง  ErrorHandler โ€” your C++ teacher -| Variable | Description | -| --------------- | ----------------- | -| `VIX_LOG_LEVEL` | Default log level | +- Explains template & overload errors +- Detects missing includes +- Highlights the _first real error_ +- Provides actionable hints --- -# ๐Ÿงช Examples +# ๐Ÿงฐ Commands + +```bash +vix [options] +``` + +| Command | Description | +| ------------------------- | ---------------------------- | +| `vix` | Start REPL (default) | +| `vix repl` | Start REPL explicitly | +| `vix new ` | Create a new project | +| `vix build [name]` | Configure + build | +| `vix run [name] [--args]` | Build and run | +| `vix dev [name]` | Dev mode (watch & reload) | +| `vix check [path]` | Compile-only validation | +| `vix tests [path]` | Run tests | +| `vix pack [options]` | Create distribution artifact | +| `vix verify [options]` | Verify artifact | +| `vix orm ` | ORM tooling | +| `vix help [command]` | Show help | +| `vix version` | Show version | -### Create +--- + +# ๐Ÿงช Usage Examples ```bash +vix vix new api +cd api +vix dev +vix check --san +vix tests +vix pack --name api --version 1.0.0 +vix verify dist/api@1.0.0 ``` -### Build +--- -```bash -vix build +# ๐Ÿงฉ Architecture + +The CLI is built around a command dispatcher: + +```cpp +std::unordered_map commands; ``` -### Run +### Main components + +| Path | Responsibility | +| -------------------------------- | -------------------- | +| `include/vix/cli/CLI.hpp` | CLI entry & parsing | +| `src/CLI.cpp` | Command routing | +| `src/ErrorHandler.cpp` | Compiler diagnostics | +| `src/commands/ReplCommand.cpp` | Interactive REPL | +| `src/commands/CheckCommand.cpp` | Validation | +| `src/commands/PackCommand.cpp` | Packaging | +| `src/commands/VerifyCommand.cpp` | Verification | + +--- + +# ๐Ÿ”ง Build & Installation + +### Standalone CLI build ```bash -vix run -- --port 8080 +git clone https://github.com/vixcpp/vix.git +cd vix/modules/cli +cmake -B build -S . +cmake --build build -j$(nproc) ``` -### Script mode +Binary: ```bash -vix run server.cpp +./build/vix ``` --- -# ๐Ÿงฉ Architecture +### Full Vix build + +```bash +cd vix +cmake -B build -S . +cmake --build build +``` -### Internal Components +--- -- **CLI** โ€” dispatches commands -- **RunFlow** โ€” orchestrates build โ†’ run -- **RunScript** โ€” compiles .cpp files in temporary environments +# โš™๏ธ Configuration -### Directory Structure +### Environment variables -```csharp -modules/cli/ - include/vix/cli/CLI.hpp - src/CLI.cpp - src/commands/ - src/commands/run/ - CMakeLists.txt -``` +| Variable | Description | +| --------------------- | ------------------------- | +| `VIX_LOG_LEVEL` | Runtime log level | +| `VIX_STDOUT_MODE` | `line` for real-time logs | +| `VIX_MINISIGN_SECKEY` | Secret key for `pack` | +| `VIX_MINISIGN_PUBKEY` | Public key for `verify` | --- -# ๐Ÿงพ Actual Help Output +# ๐Ÿ“ฆ CLI Help Output -```csharp +```sql Vix.cpp โ€” Modern C++ backend runtime -Version: v1.5.1 +Version: v1.x.x Usage: vix [GLOBAL OPTIONS] [ARGS...] + vix help + +Quick start: + vix new api + cd api && vix dev + vix pack --name api --version 1.0.0 && vix verify Commands: Project: - new Scaffold a new Vix project in ./ - - Development: - build [name] Configure and build a project (root or app) - run [name] [--args] Build (if needed) and run a project or app + new Create a new Vix project + build [name] Configure + build + run [name] Build and run + dev [name] Dev mode + check [path] Compile-only validation + tests [path] Run tests + + Packaging & security: + pack Create distribution artifact + verify Verify artifact or package + + REPL: + repl Start interactive REPL + (default) Run `vix` to start the REPL + +Global options: + --verbose + -q, --quiet + --log-level + -h, --help + -v, --version - Info: - help [command] Show this help or help for a specific command - version Show CLI version information - -Examples: - vix new api - vix build - vix run api -- --port 8080 ``` --- -# ๐Ÿชช License +# ๐Ÿงพ License -MIT License โ€” Vix.cpp Authors +**MIT License** ยฉ [Gaspard Kirira](https://github.com/gkirira) +See [`LICENSE`](../../LICENSE) for details. diff --git a/modules/cli b/modules/cli index 0d8a31d..1ba4b76 160000 --- a/modules/cli +++ b/modules/cli @@ -1 +1 @@ -Subproject commit 0d8a31d276d711d95a60705c88a70e3509c800d7 +Subproject commit 1ba4b7624a9ab9b3c78224aa9eb562538960301b