@qodalis/cli-core 2.0.0-beta.2 → 2.0.0-beta.21

package/README.md

@@ -21,6 +21,17 @@
 
 ---
 
+## Try It Online
+
+| Framework | StackBlitz | CodeSandbox | Gitpod |
+|-----------|------------|-------------|--------|
+| **Angular** | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/qodalis-solutions/qodalis-cli-angular-example) | [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/github/qodalis-solutions/qodalis-cli-angular-example) | [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/qodalis-solutions/qodalis-cli-angular-example) |
+| **React** | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/qodalis-solutions/qodalis-cli-react-example) | [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/github/qodalis-solutions/qodalis-cli-react-example) | [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/qodalis-solutions/qodalis-cli-react-example) |
+| **Vue** | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/qodalis-solutions/qodalis-cli-vue-example) | [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/github/qodalis-solutions/qodalis-cli-vue-example) | [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/qodalis-solutions/qodalis-cli-vue-example) |
+| **Vanilla** | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/qodalis-solutions/qodalis-cli-vanilla-example) | [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/github/qodalis-solutions/qodalis-cli-vanilla-example) | [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/qodalis-solutions/qodalis-cli-vanilla-example) |
+
+---
+
 ![Help command](assets/help_command.gif)
 
 ## Packages
@@ -55,7 +66,7 @@ Add styles to `angular.json`:
 ```json
 {
   "styles": [
-    "node_modules/@qodalis/angular-cli/src/assets/styles.sass"
+    "node_modules/@qodalis/angular-cli/src/assets/styles.css"
   ]
 }
 ```
@@ -75,6 +86,7 @@ npm install @qodalis/react-cli
 ```
 
 ```tsx
+import '@qodalis/react-cli/styles.css';
 import { Cli } from '@qodalis/react-cli';
 
 function App() {
@@ -90,6 +102,7 @@ npm install @qodalis/vue-cli
 
 ```vue
 <script setup lang="ts">
+import '@qodalis/vue-cli/styles.css';
 import { Cli } from '@qodalis/vue-cli';
 </script>
 
@@ -123,7 +136,7 @@ const options = {
 | `help` | `man` | Show all commands or help for a specific command |
 | `version` | `ver` | Display CLI version and documentation link |
 | `hotkeys` | `shortcuts`, `keys` | Show keyboard shortcuts |
-| `history` | `hist` | Browse and clear command history |
+| `history` | `hist` | Browse and clear your command history (per user with the users plugin) |
 | `theme` | `themes` | Apply, customize, and save terminal themes (interactive selection with live preview) |
 | `feedback` | `support` | Report bugs or request features on GitHub |
 | `pkg` | `packages` | Install, update, remove, and browse packages |
@@ -192,19 +205,60 @@ pkg source set unpkg           # Set package source directly
 
 ### Available Packages
 
+#### Utility Plugins
+
 | Package | Command | Description |
 |---------|---------|-------------|
+| [@qodalis/cli-data-explorer](https://www.npmjs.com/package/@qodalis/cli-data-explorer) | `data-explorer` | Interactive query console for SQL, MongoDB, Redis, Elasticsearch |
 | [@qodalis/cli-guid](https://www.npmjs.com/package/@qodalis/cli-guid) | `guid` | Generate and validate UUIDs |
-| [@qodalis/cli-string](https://www.npmjs.com/package/@qodalis/cli-string) | `string` | String manipulation (case, trim, reverse, slug, wc, etc.) |
-| [@qodalis/cli-curl](https://www.npmjs.com/package/@qodalis/cli-curl) | `curl` | HTTP requests (GET, POST, PUT, DELETE) |
-| [@qodalis/cli-todo](https://www.npmjs.com/package/@qodalis/cli-todo) | `todo` | Task management |
 | [@qodalis/cli-regex](https://www.npmjs.com/package/@qodalis/cli-regex) | `regex` | Regular expression testing |
 | [@qodalis/cli-qr](https://www.npmjs.com/package/@qodalis/cli-qr) | `qr` | QR code generation |
 | [@qodalis/cli-speed-test](https://www.npmjs.com/package/@qodalis/cli-speed-test) | `speed-test` | Internet speed test |
-| [@qodalis/cli-server-logs](https://www.npmjs.com/package/@qodalis/cli-server-logs) | `server-logs` | Live server log streaming |
+| [@qodalis/cli-curl](https://www.npmjs.com/package/@qodalis/cli-curl) | `curl` | HTTP requests (GET, POST, PUT, DELETE) |
+| [@qodalis/cli-password-generator](https://www.npmjs.com/package/@qodalis/cli-password-generator) | `generate-password` | Password generation |
+| [@qodalis/cli-string](https://www.npmjs.com/package/@qodalis/cli-string) | `string` | String manipulation (case, trim, reverse, slug, wc, etc.) |
+| [@qodalis/cli-todo](https://www.npmjs.com/package/@qodalis/cli-todo) | `todo` | Task management |
 | [@qodalis/cli-browser-storage](https://www.npmjs.com/package/@qodalis/cli-browser-storage) | `local-storage`, `cookies` | Browser storage operations |
 | [@qodalis/cli-text-to-image](https://www.npmjs.com/package/@qodalis/cli-text-to-image) | `text-to-image` | Generate images from text |
-| [@qodalis/cli-password-generator](https://www.npmjs.com/package/@qodalis/cli-password-generator) | `generate-password` | Password generation |
+| [@qodalis/cli-files](https://www.npmjs.com/package/@qodalis/cli-files) | `ls`, `cat`, `nano`, `mkdir`, `touch`, `rm` | Virtual filesystem |
+| [@qodalis/cli-yesno](https://www.npmjs.com/package/@qodalis/cli-yesno) | `yesno` | Interactive yes/no confirmation prompts |
+| [@qodalis/cli-server-logs](https://www.npmjs.com/package/@qodalis/cli-server-logs) | `server logs` | Live server log streaming with level filtering |
+| [@qodalis/cli-server-jobs](https://www.npmjs.com/package/@qodalis/cli-server-jobs) | `server jobs` | Manage server-side background jobs |
+| [@qodalis/cli-users](https://www.npmjs.com/package/@qodalis/cli-users) | `whoami`, `adduser`, `login` | User management and authentication |
+| [@qodalis/cli-chart](https://www.npmjs.com/package/@qodalis/cli-chart) | `chart` | Render bar, line, and sparkline charts |
+| [@qodalis/cli-cron](https://www.npmjs.com/package/@qodalis/cli-cron) | `cron` | Schedule and manage recurring commands |
+| [@qodalis/cli-csv](https://www.npmjs.com/package/@qodalis/cli-csv) | `csv` | Parse, filter, sort, and convert CSV data |
+| [@qodalis/cli-markdown](https://www.npmjs.com/package/@qodalis/cli-markdown) | `md` | Render Markdown content in the terminal |
+| [@qodalis/cli-encode](https://www.npmjs.com/package/@qodalis/cli-encode) | `base64`, `url`, `hex`, `html` | Encode/decode Base64, URL, hex, HTML entities |
+| [@qodalis/cli-scp](https://www.npmjs.com/package/@qodalis/cli-scp) | `scp` | Secure copy — transfer files between local and remote |
+| [@qodalis/cli-wget](https://www.npmjs.com/package/@qodalis/cli-wget) | `wget` | Download files from URLs |
+| [@qodalis/cli-stopwatch](https://www.npmjs.com/package/@qodalis/cli-stopwatch) | `stopwatch` | Interactive stopwatch and countdown timer |
+
+#### Game Plugins
+
+| Package | Command | Description |
+|---------|---------|-------------|
+| [@qodalis/cli-snake](https://www.npmjs.com/package/@qodalis/cli-snake) | `snake` | Classic Snake game |
+| [@qodalis/cli-tetris](https://www.npmjs.com/package/@qodalis/cli-tetris) | `tetris` | Tetris |
+| [@qodalis/cli-2048](https://www.npmjs.com/package/@qodalis/cli-2048) | `2048` | 2048 sliding puzzle |
+| [@qodalis/cli-minesweeper](https://www.npmjs.com/package/@qodalis/cli-minesweeper) | `minesweeper` | Minesweeper |
+| [@qodalis/cli-wordle](https://www.npmjs.com/package/@qodalis/cli-wordle) | `wordle` | Wordle word game |
+| [@qodalis/cli-sudoku](https://www.npmjs.com/package/@qodalis/cli-sudoku) | `sudoku` | Sudoku puzzle |
+
+#### Language Packs
+
+| Package | Language |
+|---------|----------|
+| [@qodalis/cli-lang-es](https://www.npmjs.com/package/@qodalis/cli-lang-es) | Spanish |
+| [@qodalis/cli-lang-fr](https://www.npmjs.com/package/@qodalis/cli-lang-fr) | French |
+| [@qodalis/cli-lang-de](https://www.npmjs.com/package/@qodalis/cli-lang-de) | German |
+| [@qodalis/cli-lang-it](https://www.npmjs.com/package/@qodalis/cli-lang-it) | Italian |
+| [@qodalis/cli-lang-pt](https://www.npmjs.com/package/@qodalis/cli-lang-pt) | Portuguese |
+| [@qodalis/cli-lang-ro](https://www.npmjs.com/package/@qodalis/cli-lang-ro) | Romanian |
+| [@qodalis/cli-lang-ru](https://www.npmjs.com/package/@qodalis/cli-lang-ru) | Russian |
+| [@qodalis/cli-lang-zh](https://www.npmjs.com/package/@qodalis/cli-lang-zh) | Chinese |
+| [@qodalis/cli-lang-ja](https://www.npmjs.com/package/@qodalis/cli-lang-ja) | Japanese |
+| [@qodalis/cli-lang-ko](https://www.npmjs.com/package/@qodalis/cli-lang-ko) | Korean |
 
 Any npm package with UMD support can also be loaded:
 
@@ -213,6 +267,90 @@ pkg add lodash
 eval _.map([1, 2, 3], n => n * 2)
 ```
 
+## Server Integration
+
+Connect the frontend terminal to a backend server for server-side command execution, interactive shell sessions, filesystem access, and event streaming. Three official backend implementations are available:
+
+| Server | Package | Port | Tech Stack |
+|--------|---------|------|------------|
+| **.NET** | [Qodalis.Cli](https://www.nuget.org/packages/Qodalis.Cli) | 8046 | ASP.NET Core, .NET 8 |
+| **Node.js** | [@qodalis/cli-server](https://www.npmjs.com/package/@qodalis/cli-server) | 8047 | Express, TypeScript, node-pty |
+| **Python** | [qodalis-cli-server](https://pypi.org/project/qodalis-cli-server/) | 8048 | FastAPI, uvicorn |
+
+All three implement the same API surface:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/cli/versions` | GET | Version discovery |
+| `/api/v1/cli/commands` | GET | List registered command processors |
+| `/api/v1/cli/execute` | POST | Execute a CLI command |
+| `/api/v1/cli/execute/stream` | POST | Execute with SSE streaming output |
+| `/ws/v1/cli/events` | WS | Server-push event streaming |
+| `/ws/v1/cli/shell` | WS | Interactive PTY shell session |
+| `/api/cli/fs/*` | Various | Filesystem operations (ls, cat, upload, download, mkdir, rm) |
+| `/api/qcli/mcp` | POST | MCP endpoint for AI clients (opt-in) |
+
+### Connecting to a Server
+
+```typescript
+import { CliOptions } from '@qodalis/cli-core';
+
+const options: CliOptions = {
+  servers: [
+    { name: 'node', url: 'http://localhost:8047' },
+    { name: 'dotnet', url: 'http://localhost:8046' },
+    { name: 'python', url: 'http://localhost:8048' },
+  ],
+};
+
+// Angular: <cli [options]="options" />
+// React:   <Cli options={options} />
+// Vue:     <Cli :options="options" />
+```
+
+### SSE Streaming Execution
+
+The frontend automatically uses SSE streaming when the server supports it, with transparent fallback to the legacy POST endpoint. Streaming processors emit output chunks as they execute rather than buffering the full response.
+
+### Resilience
+
+The frontend includes built-in resilience features:
+
+- **WebSocket auto-reconnect** with exponential backoff (up to 5 attempts, max 30s delay)
+- **Periodic health checks** for disconnected servers (30s interval)
+- **HTTP retry** on transient fetch failures (1 retry with 1s delay)
+- **Configurable request timeout** per server (default 30s)
+
+### MCP
+
+Each server can expose the whole system to AI clients such as Claude Code over the [Model Context Protocol](https://modelcontextprotocol.io) at `POST /api/qcli/mcp` (opt-in): CLI commands, the filesystem API, the data explorer, jobs and plugin-contributed tools, each with the caller's permissions. It works with or without the users plugin, whose `token create` command issues the API tokens MCP clients sign in with:
+
+```bash
+# direct HTTP
+claude mcp add --transport http qcli http://localhost:8047/api/qcli/mcp --header "Authorization: Bearer <token>"
+# or the local stdio proxy @qodalis/mcp-cli (token or user/password, read-only mode, tool filters)
+claude mcp add qcli -e QCLI_URL=http://localhost:8047 -e QCLI_TOKEN=<token> -- npx -y @qodalis/mcp-cli
+```
+
+See [MCP endpoint](https://cli.qodalis.com/docs/server-integration#mcp-endpoint) for enabling it, the tools and permissions, and client setup.
+
+### Server Plugins
+
+| Plugin | Servers | Description |
+|--------|---------|-------------|
+| **Background Jobs** | .NET, Node.js, Python | Scheduled and recurring job execution with cron/interval support |
+| **Admin Dashboard** | .NET, Node.js | React-based web UI for server management — commands, jobs, plugins, logs, filesystem, events, and an embedded terminal |
+| **AWS Cloud** | .NET, Python | S3, EC2, Lambda, DynamoDB, IAM, ECS, SQS, SNS, CloudWatch with multi-profile credential management |
+| **Data Explorer** | .NET, Node.js, Python | SQL, MongoDB, Redis, Elasticsearch, and custom data source providers |
+
+### Docker
+
+Run all three servers with Docker Compose from the [workspace root](https://github.com/qodalis-solutions/cli-workspace):
+
+```bash
+docker compose up --build
+```
+
 ## Creating a CLI Plugin
 
 ### Quick Start
@@ -256,7 +394,7 @@ The tool auto-detects whether you're inside the `web-cli` monorepo:
 In monorepo mode, the tool also:
 - Creates `project.json` (Nx build + test targets)
 - Creates `tsconfig.spec.json` (Karma/Jasmine test config)
-- Updates `tsconfig.base.json` with the path alias `@qodalis/cli-<name>` → `dist/<name>`
+- Updates `tsconfig.base.json` with the path alias `@qodalis/cli-<name>` -> `dist/<name>`
 
 ### Generated Project Structure
 
@@ -522,6 +660,81 @@ import { weatherModule } from '@qodalis/cli-weather';
 </template>
 ```
 
+## Data Explorer
+
+The `@qodalis/cli-data-explorer` plugin adds an interactive, full-screen REPL for querying data sources (SQL, MongoDB, Redis, Elasticsearch, and custom providers) directly from the terminal.
+
+### Setup
+
+Install and register the plugin, then configure backend servers:
+
+```typescript
+import { dataExplorerModule } from '@qodalis/cli-data-explorer';
+
+// Add to your modules array
+const modules = [dataExplorerModule, /* ... other modules */];
+
+// Configure at least one server with data explorer providers
+const options: CliOptions = {
+  servers: [
+    { name: 'node', url: 'http://localhost:8047' },
+    { name: 'dotnet', url: 'http://localhost:8046' },
+    { name: 'python', url: 'http://localhost:8048' },
+  ],
+};
+```
+
+Or install at runtime without a rebuild:
+
+```bash
+pkg add data-explorer
+```
+
+### Usage
+
+```bash
+data-explorer
+```
+
+Select a server and data source, then enter the full-screen REPL:
+
+```
+data-explorer> SELECT * FROM users WHERE active = true;
+
+3 rows (12ms)
+┌────┬───────┬──────────────┐
+│ id │ name  │ email        │
+├────┼───────┼──────────────┤
+│  1 │ Alice │ alice@ex.com │
+│  2 │ Bob   │ bob@ex.com   │
+│  3 │ Carol │ carol@ex.com │
+└────┴───────┴──────────────┘
+
+data-explorer> \format json
+Output format set to: json
+
+data-explorer> db.users.find({"age": {"$gt": 25}})
+[
+  { "_id": "abc", "name": "Alice", "age": 30 },
+  { "_id": "def", "name": "Bob", "age": 28 }
+]
+```
+
+### REPL Commands
+
+| Command | Description |
+|---------|-------------|
+| `\format <table\|json\|csv\|raw>` | Switch output format |
+| `\schema` | Show database schema (tables, columns, types) |
+| `\templates` | List available query templates |
+| `\use <name>` | Load a template query |
+| `\history` | Show query history |
+| `\clear` | Clear screen |
+| `\help` | Show all commands |
+| `\quit` / `\q` | Exit |
+
+Use **Up/Down arrows** for history navigation, **Escape** or **Ctrl+C** to exit.
+
 ## Extending with Inline Commands
 
 For quick one-off commands without creating a full plugin, implement `ICliCommandProcessor` directly in your app:
@@ -581,16 +794,21 @@ await engine.start();
 ## Features
 
 - **Multi-framework** — Angular, React, Vue, or vanilla JS
+- **38 official plugins** — 24 utility, 6 games, 10 language packs
 - **Command chaining** with `&&`, `||`, `|`, and `>>` operators
-- **Command history** with arrow key navigation
-- **Tab-like completions** and keyboard shortcuts (`Ctrl+C`, `Ctrl+L`, `Escape`)
-- **Theming** with built-in themes and custom color support
+- **Command history** with arrow key navigation, per user when the users plugin is used (like `~/.bash_history`)
+- **Tab-like completions** and readline keyboard shortcuts (`Ctrl+C`, `Ctrl+L`, `Escape`, `Ctrl+A/E`, `Ctrl+U/K/W/Y`, Home/End; `hotkeys` lists them)
+- **29 built-in themes** with custom color support
+- **Tabs & split panes** — multiple terminals in tabs with horizontal splitting
 - **User sessions** with multi-user support
 - **State persistence** across sessions
 - **Interactive prompts** with live preview (select menus with real-time feedback)
-- **Full-screen mode API** for rich TUI commands
+- **Full-screen mode API** for rich TUI commands (games, editors, pagers)
 - **Progress bars, spinners, and text animations**
 - **Runtime package installation** from npm
+- **Server integration** with SSE streaming, auto-reconnect, and health checks
+- **Admin dashboard** for server management (React SPA)
+- **Data explorer** for SQL, MongoDB, Redis, and Elasticsearch
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodalis/cli-core",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.21",
   "description": "Core interfaces, types, and utilities for the @qodalis CLI ecosystem.",
   "author": "Nicolae Lupei, Qodalis Solutions",
   "license": "MIT",