@qodalis/cli-server-node 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -1,5 +1,8 @@
 # Qodalis CLI Server (Node.js)
 
+[![npm @qodalis/cli-server-node](https://img.shields.io/npm/v/@qodalis/cli-server-node?label=%40qodalis%2Fcli-server-node)](https://www.npmjs.com/package/@qodalis/cli-server-node)
+[![npm @qodalis/cli-server-abstractions](https://img.shields.io/npm/v/@qodalis/cli-server-abstractions?label=%40qodalis%2Fcli-server-abstractions)](https://www.npmjs.com/package/@qodalis/cli-server-abstractions)
+
 A Node.js CLI server framework for the [Qodalis CLI](https://github.com/qodalis-solutions/web-cli) ecosystem. Build custom server-side commands that integrate with the Qodalis web terminal.
 
 ## Installation
@@ -297,36 +300,109 @@ Every processor receives a `CliProcessCommand` with the parsed command input:
 | `rawCommand` | `string` | Original unprocessed input |
 | `data` | `any` | Arbitrary data payload from the client |
 
-## API Versioning
+## API Endpoints
+
+The server exposes versioned endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/qcli/versions` | Version discovery (supported versions, preferred version) |
+| GET | `/api/v1/qcli/version` | V1 server version |
+| GET | `/api/v1/qcli/commands` | V1 commands (all processors) |
+| POST | `/api/v1/qcli/execute` | V1 execute |
+| POST | `/api/v1/qcli/execute/stream` | V1 SSE streaming execute |
+| WS | `/ws/qcli/events` | WebSocket events (also `/ws/v1/qcli/events`) |
+| WS | `/ws/v1/qcli/shell` | Interactive PTY shell session |
+
+`GET /capabilities` reports `shell: true|false` and, when the shell is enabled, `shellAuth: 'users' | 'token' | 'custom' | 'anonymous' | 'locked'`.
 
-Processors declare which API version they target. The default is version 1.
+## Remote Shell Security
+
+The PTY shell (`/ws/v1/qcli/shell`, `/ws/qcli/shell`) gives OS-level access to the server. It is **off** unless `enableShell: true`. When enabled, exactly one access mode applies:
+
+| Mode (`shellAuth`) | When | Client must |
+|---|---|---|
+| `users` | the users plugin is mounted | connect with a WS ticket (`?ticket=`) of a session holding `shell:execute` |
+| `token` | no users plugin, `shell.token` set | send `Authorization: Bearer <token>` (header, or the `_header_Authorization` query parameter) |
+| `custom` | no users plugin, `shell.authorize` set | pass the host's `authorize(request, { url, remoteAddress, mode })` check |
+| `anonymous` | no users plugin, `shell.allowAnonymous: true` | nothing (a startup WARNING is logged) |
+| `locked` | none of the above | — every connection is closed with 4401 and a startup ERROR explains the options |
+
+Precedence: users plugin mounted (even with `protectServer: false`) ⇒ `users`; otherwise `token`, then `custom`, then `anonymous`. Whatever the mode, **every configured check among `token` and `authorize` must pass** (so with both set, both are required and `shellAuth` reports `token`); `allowAnonymous` is ignored once either is set. Tokens are compared in constant time (SHA-256 of both, then `timingSafeEqual`) and never logged; an `authorize` that throws or rejects denies.
+
+### With the users plugin
 
 ```typescript
-class DashboardProcessor extends CliCommandProcessor {
-    command = 'dashboard';
-    description = 'Server dashboard (v2 only)';
-    apiVersion = 2;
+const { mountPlugin, eventSocketManager } = createCliServer({ enableShell: true });
+mountPlugin(new CliUsersBuilder().build((m) => eventSocketManager.broadcastMessage(m)));
+// Grant shell:execute to a group (root/admin has '*'):
+//   PUT /api/v1/qcli/groups/ops  { "permissions": ["commands:execute", "shell:execute"] }
+```
 
-    async handleAsync(command: CliProcessCommand): Promise<string> {
-        return 'Dashboard data...';
-    }
+An open shell is bound to the session that opened it: logout, idle/absolute session expiry, admin revoke (kick), user disabled or deleted, or losing `shell:execute` (checked once more right after the shell is registered and before it is spawned, so a logout racing the open is not missed; then immediately on session/user/group changes and every `sessionCheckIntervalMs`, default 30 s, max 60 s), or a password change becoming required closes it with **4401** `session ended` and kills its process tree. Users authenticated by an external auth adapter have no stored session: their shells are re-checked by calling the adapter again with the shell's original upgrade request (see the users plugin README). Re-checks never extend the session by themselves; stdin received since the previous check counts as session activity (at most one touch per 30 s), so an active shell user is not idle-logged-out. Opens and closes are audited as `shell_opened` / `shell_closed` (`userId`, `actorId`, `metadata: { mode: 'interactive' | 'command', sessionId, durationMs, reason, exitCode? }`), never with the command text or stdin. `reason` is one of `exited` (then `exitCode` is set), `closed`, `session ended`, `permission removed`, `shell timed out`, `server shutdown`, `error`.
+
+### Without the users plugin (token mode)
+
+```typescript
+createCliServer({
+    enableShell: true,
+    shell: { token: process.env.QCLI_SHELL_TOKEN },   // long random secret
+});
+```
+
+Browser clients cannot set WebSocket headers: configure the server in web-cli with `headers: { Authorization: 'Bearer <token>' }` and the client forwards it as `?_header_Authorization=Bearer%20<token>`. The standalone server (`src/server.ts`) enables token mode when `QCLI_SHELL_TOKEN` is set. Use HTTPS/WSS so the token is not sent in clear text.
+
+For your own scheme (reverse-proxy identity, IP allow-list, …) use `authorize`:
+
+```typescript
+createCliServer({
+    enableShell: true,
+    shell: { authorize: async (req, { remoteAddress }) => remoteAddress === '127.0.0.1' && req.headers['x-ops'] === 'yes' },
+});
+```
+
+Non-users modes log one info line per open/close (remote address, mode, reason) without the command text.
+
+### Options
+
+```typescript
+shell: {
+    token?: string;                    // token mode (or extra requirement with the users plugin)
+    authorize?: (req, ctx) => boolean | Promise<boolean>;  // custom mode (or extra requirement)
+    allowAnonymous?: boolean;          // open to anyone who can reach the server (not recommended)
+    maxSessionsPerUser?: number;       // per user (users mode) or per remote address (default 3; X-Forwarded-For only with trustProxy)
+    maxSessions?: number;              // total concurrent shells (default 20)
+    idleTimeoutMs?: number;            // close after no stdin (resize does not count; default 15 min, 0 = off)
+    maxDurationMs?: number;            // absolute limit (default none)
+    sessionCheckIntervalMs?: number;   // users-mode re-check (default 30 000, max 60 000)
+    cwd?: string;                      // working directory (default: home directory)
+    shell?: string;                    // shell binary (default: detected)
+    env?: { allow?: string[]; set?: Record<string, string> };
 }
 ```
 
-The server exposes versioned endpoints:
+The shell does **not** inherit the server environment: it gets only `PATH`, `HOME`, `USER`, `LANG`, `TERM`, `COLUMNS`, `LINES`, `SHELL` (plus the variables Windows needs to start PowerShell), the names in `env.allow`, and `env.set`. Secrets such as database passwords stay out of the shell.
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/cli/versions` | Version discovery (supported versions, preferred version) |
-| GET | `/api/v1/cli/version` | V1 server version |
-| GET | `/api/v1/cli/commands` | V1 commands (all processors) |
-| POST | `/api/v1/cli/execute` | V1 execute |
-| GET | `/api/v2/cli/version` | V2 server version |
-| GET | `/api/v2/cli/commands` | V2 commands (only `apiVersion >= 2`) |
-| POST | `/api/v2/cli/execute` | V2 execute |
-| WS | `/ws/cli/events` | WebSocket events (also `/ws/v1/cli/events`, `/ws/v2/cli/events`) |
+### Process cleanup
 
-The Qodalis CLI client auto-negotiates the highest mutually supported version via the `/api/cli/versions` discovery endpoint.
+Whenever a shell ends (exit, client close, session ended or permission removed, timeout, server shutdown), the server first collects everything the shell started — its process group, its descendants by parent PID (including background jobs that interactive shells move to their own process groups, and `setsid`/`nohup` children), on Linux every process of its session, and every process tagged with the shell's marker (below) — and then sends SIGHUP, SIGTERM and, after a 1 s grace period, SIGKILL to all of them (re-collecting before the SIGKILL). The server's own process and process group are never targeted. Linux reads `/proc` for everything (no `ps` needed); macOS and other Unixes run `ps`. On Windows only the shell process is killed.
+
+Every shell gets a unique marker in its environment, `QCLI_SHELL_ID=<random 128-bit hex>`, added after the `env.allow`/`env.set` filtering so configuration can neither override nor remove it. Children inherit it, so processes that were re-parented to init *and* left the shell's process group and session — e.g. `setsid sleep 100 &` from an interactive shell, double-forking daemons — are still found: on Linux by reading `/proc/<pid>/environ`, on macOS through `ps -A -E -ww` (which shows the environment of the server user's processes).
+
+Limitations: a process escapes only if it deliberately unsets or changes `QCLI_SHELL_ID` before detaching (`env -u QCLI_SHELL_ID setsid …`), or runs as a different user whose environment the server cannot read (e.g. via `sudo`). On macOS the environment of Apple platform binaries (`/bin/sleep`, `/usr/bin/perl`, …) is hidden from `ps -E`, so such a binary that left the shell's tree and session is not found there either. Run the server in a container or under a service manager (cgroup) if every process must be contained.
+
+### Close codes
+
+Refusals are sent as *accept, then close* so browsers can read them (a foreign `Origin` is still rejected with HTTP 403):
+
+| Code | Reason | When |
+|---|---|---|
+| 4401 | `login required` / `session ended` / `shell access is not configured` | missing ticket or (Bearer) token; session ended (logout, expiry, kick, user disabled/deleted, `shell:execute` removed, password change now required) — shell, events and logs sockets; shell locked |
+| 4403 | `forbidden` | wrong token, `authorize` false or threw, no `shell:execute`, password change required |
+| 4404 | `shell disabled` | `enableShell` is false |
+| 4408 | `shell timed out` | idle timeout or `maxDurationMs` |
+| 4429 | `too many shell sessions` | `maxSessionsPerUser` or `maxSessions` reached |
+| 1001 | `server shutdown` | the server is shutting down |
 
 ## Processor Base Class Reference
 
@@ -342,19 +418,31 @@ The Qodalis CLI client auto-negotiates the highest mutually supported version vi
 | `allowUnlistedCommands` | `boolean` | `undefined` | Accept sub-commands not in `processors` |
 | `valueRequired` | `boolean` | `undefined` | Require a positional value |
 | `version` | `string` | `'1.0.0'` | Processor version string |
-| `apiVersion` | `number` | `1` | Target API version |
 | `author` | `ICliCommandAuthor` | default author | Author metadata (name, email) |
 
 ## Server Options
 
 ```typescript
 interface CliServerOptions {
-    basePath?: string;                     // API base path (default: '/api/cli')
-    cors?: boolean | cors.CorsOptions;     // CORS config (default: false)
+    basePath?: string;                     // API base path (default: '/api/qcli')
+    cors?: boolean | cors.CorsOptions;     // CORS config (default: only allowedOrigins; off when none)
+    allowedOrigins?: string[];             // CORS + WebSocket Origin allow-list ('http://host:*' = any port)
+    enableShell?: boolean;                 // Interactive shell WebSocket (default: false)
+    shell?: CliShellOptions;               // Shell access mode, limits, timeouts, env (see Remote Shell Security)
+    trustProxy?: boolean | number;         // Trusted proxy hops for X-Forwarded-* (true = 1; default false = none)
+    auth?: ICliServerAuth;                 // Protect the whole server (e.g. usersPlugin.serverAuth)
     configure?: (builder: CliBuilder) => void;  // Processor registration
 }
 ```
 
+CORS is disabled unless `allowedOrigins` (or an explicit `cors` option) is given. The shell socket is off unless `enableShell: true`, and even then it is locked until an access mode applies (see [Remote Shell Security](#remote-shell-security)).
+
+Same-origin requests (e.g. the bundled admin dashboard at `/qcli/admin`) are always allowed by the Origin, CORS and CSRF checks, even when `allowedOrigins` does not list the server's own origin (`X-Forwarded-Proto`/`X-Forwarded-Host` are honoured only with `trustProxy`, and read like `X-Forwarded-For`: the entry at index `len - hops`, the leftmost when the list is shorter, an empty entry ignored).
+
+`trustProxy` is the number of trusted reverse-proxy hops in front of the server (`true` = 1, `false`/`0`/absent = none). With n hops the client IP (Express `req.ip`, the shell's per-address limits) is the `X-Forwarded-For` entry at index `len - n` of the comma-separated list, i.e. with one hop the rightmost entry, appended by your proxy; the leftmost entries are client-controlled and never used unless the list is shorter than n. Without the header (or when the selected entry is empty) the socket address is used. Set it to the exact number of proxies you run, otherwise clients can spoof their IP.
+
+When the users plugin is mounted (`mountPlugin(usersPlugin)`) or passed as `auth`, every `/api/...` route and every WebSocket requires a users session (see [Users Plugin](#users-plugin)); without it the server behaves as before.
+
 `createCliServer()` returns:
 
 ```typescript
@@ -362,7 +450,11 @@ interface CliServerOptions {
     app: Express;                          // Configured Express app
     registry: CliCommandRegistry;          // Processor registry
     builder: CliBuilder;                   // Registration builder
-    eventSocketManager: CliEventSocketManager;  // WebSocket manager
+    executor: CliCommandExecutorService;   // Command executor
+    eventSocketManager: CliEventSocketManager;  // WebSocket event manager
+    logSocketManager: CliLogSocketManager;      // WebSocket log manager
+    mountPlugin(plugin: MountablePlugin): void; // Mount a plugin with its routes (installs plugin.serverAuth)
+    setAuth(auth?: ICliServerAuth): void;       // Install/remove the server auth provider
 }
 ```
 
@@ -411,19 +503,19 @@ import {
 
 ## File Storage
 
-The server includes a pluggable file storage system exposed at `/api/cli/fs/*`. Enable it with `setFileStorageProvider()` and choose a storage backend.
+The server includes a pluggable file storage system exposed at `/api/qcli/fs/*`. Enable it with `setFileStorageProvider()` and choose a storage backend.
 
 ### Filesystem API Endpoints
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/cli/fs/ls?path=/` | List directory contents |
-| GET | `/api/cli/fs/cat?path=/file.txt` | Read file content |
-| GET | `/api/cli/fs/stat?path=/file.txt` | File/directory metadata |
-| GET | `/api/cli/fs/download?path=/file.txt` | Download file |
-| POST | `/api/cli/fs/upload` | Upload file (multipart) |
-| POST | `/api/cli/fs/mkdir` | Create directory |
-| DELETE | `/api/cli/fs/rm?path=/file.txt` | Delete file or directory |
+| GET | `/api/qcli/fs/ls?path=/` | List directory contents |
+| GET | `/api/qcli/fs/cat?path=/file.txt` | Read file content |
+| GET | `/api/qcli/fs/stat?path=/file.txt` | File/directory metadata |
+| GET | `/api/qcli/fs/download?path=/file.txt` | Download file |
+| POST | `/api/qcli/fs/upload` | Upload file (multipart) |
+| POST | `/api/qcli/fs/mkdir` | Create directory |
+| DELETE | `/api/qcli/fs/rm?path=/file.txt` | Delete file or directory |
 
 ### Storage Providers
 
@@ -492,6 +584,180 @@ class MyProvider implements IFileStorageProvider {
 builder.setFileStorageProvider(new MyProvider());
 ```
 
+## Data Explorer
+
+The Data Explorer plugin provides interactive, full-screen REPL access to data sources. It exposes a provider-based API where each data source type (SQL, MongoDB, etc.) is a separate plugin implementing `IDataExplorerProvider`.
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/qcli/data-explorer/sources` | List registered data sources with metadata |
+| POST | `/api/qcli/data-explorer/execute` | Execute a query against a named source |
+
+### SQL Provider
+
+```typescript
+import { SqlDataExplorerProvider } from '@qodalis/cli-server-plugin-data-explorer-sql';
+import { DataExplorerLanguage, DataExplorerOutputFormat } from '@qodalis/cli-server-abstractions';
+
+const { app } = createCliServer({
+    configure: (builder) => {
+        builder.addDataExplorerProvider(
+            new SqlDataExplorerProvider({ type: 'sqlite', filename: './data.db' }),
+            {
+                name: 'my-database',
+                description: 'Application database',
+                language: DataExplorerLanguage.Sql,
+                defaultOutputFormat: DataExplorerOutputFormat.Table,
+                timeout: 30000,
+                maxRows: 1000,
+                templates: [
+                    {
+                        name: 'list_tables',
+                        query: "SELECT name FROM sqlite_master WHERE type='table'",
+                        description: 'List all tables',
+                    },
+                ],
+            },
+        );
+    },
+});
+```
+
+### MongoDB Provider
+
+```typescript
+import { MongoDataExplorerProvider } from '@qodalis/cli-server-plugin-data-explorer-mongo';
+
+builder.addDataExplorerProvider(
+    new MongoDataExplorerProvider({
+        connectionString: 'mongodb://localhost:27017',
+        database: 'myapp',
+    }),
+    {
+        name: 'mongo-primary',
+        description: 'Primary MongoDB database',
+        language: DataExplorerLanguage.Json,
+        defaultOutputFormat: DataExplorerOutputFormat.Json,
+        templates: [
+            { name: 'show_collections', query: 'show collections', description: 'List all collections' },
+            { name: 'find_users', query: 'db.users.find({})', description: 'Find all users' },
+        ],
+    },
+);
+```
+
+**Supported MongoDB operations:** `db.collection.find({...})`, `findOne`, `aggregate([...])`, `insertOne`, `insertMany`, `updateOne`, `updateMany`, `deleteOne`, `deleteMany`, `countDocuments`, `distinct`. Convenience commands: `show collections`, `show dbs`.
+
+### Custom Provider
+
+Implement `IDataExplorerProvider` to add your own data source:
+
+```typescript
+import { IDataExplorerProvider, DataExplorerExecutionContext, DataExplorerResult } from '@qodalis/cli-server-abstractions';
+
+class MyProvider implements IDataExplorerProvider {
+    async executeAsync(context: DataExplorerExecutionContext): Promise<DataExplorerResult> {
+        // context.query — the user's query string
+        // context.parameters — key-value parameters
+        // context.options — provider options (name, language, etc.)
+        return {
+            success: true,
+            source: context.options.name,
+            language: context.options.language,
+            defaultOutputFormat: context.options.defaultOutputFormat,
+            executionTime: 0,
+            columns: ['id', 'name'],       // null for document-oriented results
+            rows: [[1, 'Alice'], [2, 'Bob']], // objects when columns is null
+            rowCount: 2,
+            truncated: false,
+            error: null,
+        };
+    }
+}
+
+builder.addDataExplorerProvider(new MyProvider(), { name: 'custom', ... });
+```
+
+The same provider class can be registered multiple times with different configurations (e.g., two databases with different names).
+
+## AWS Cloud Services
+
+The AWS plugin adds commands for managing AWS resources (S3, EC2, Lambda, CloudWatch, SNS, SQS, IAM, DynamoDB, ECS) directly from the CLI. It uses AWS SDK v3 and supports the full credential chain.
+
+```typescript
+import { AwsModule } from '@qodalis/cli-server-plugin-aws';
+
+const { app } = createCliServer({
+    configure: (builder) => {
+        builder.addModule(new AwsModule());
+    },
+});
+```
+
+### Authentication
+
+The plugin resolves credentials in this order:
+
+1. **CLI configure**: `aws configure set --key <KEY> --secret <SECRET> --region <REGION>`
+2. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+3. **AWS profiles**: `aws configure set --profile <name>`
+4. **IAM roles**: Automatic on EC2/ECS/Lambda
+
+Verify connectivity with `aws status`.
+
+### Available Commands
+
+| Service | Commands |
+|---------|----------|
+| **configure** | `aws configure set`, `aws configure get`, `aws configure profiles` |
+| **status** | `aws status` — STS GetCallerIdentity connectivity check |
+| **S3** | `aws s3 ls`, `aws s3 cp`, `aws s3 rm`, `aws s3 mb`, `aws s3 rb`, `aws s3 presign` |
+| **EC2** | `aws ec2 list`, `aws ec2 describe`, `aws ec2 start`, `aws ec2 stop`, `aws ec2 reboot`, `aws ec2 sg list` |
+| **Lambda** | `aws lambda list`, `aws lambda invoke`, `aws lambda logs` |
+| **CloudWatch** | `aws cloudwatch alarms`, `aws cloudwatch logs`, `aws cloudwatch metrics` |
+| **SNS** | `aws sns topics`, `aws sns publish`, `aws sns subscriptions` |
+| **SQS** | `aws sqs list`, `aws sqs send`, `aws sqs receive`, `aws sqs purge` |
+| **IAM** | `aws iam users`, `aws iam roles`, `aws iam policies` |
+| **DynamoDB** | `aws dynamodb tables`, `aws dynamodb describe`, `aws dynamodb scan`, `aws dynamodb query` |
+| **ECS** | `aws ecs clusters`, `aws ecs services`, `aws ecs tasks` |
+
+All commands support `--region` (`-r`) for region override and `--output` (`-o`) for format selection (`table`, `json`, `text`). Destructive commands support `--dry-run`.
+
+See [`plugins/aws/README.md`](plugins/aws/README.md) for the full command reference.
+
+### Users Plugin
+
+The users plugin (`@qodalis/cli-server-plugin-users`) adds REST endpoints under `/api/v1/qcli` for authentication, users, groups with permissions, sessions and an audit log, with swappable storage (in-memory by default). It is the server side of the `@qodalis/cli-users` browser plugin's *server mode*.
+
+```typescript
+import { CliUsersBuilder } from '@qodalis/cli-server-plugin-users';
+
+const usersPlugin = new CliUsersBuilder()
+    .build((msg) => eventSocketManager.broadcastMessage(msg));
+mountPlugin(usersPlugin); // protects the whole server (protectServer: true)
+```
+
+Once mounted, every server route and socket requires a users session (login, version discovery and capabilities stay public):
+
+| Surface | Permission |
+|---|---|
+| `GET /commands` | authenticated |
+| `POST /execute`, `/execute/stream` | `commands:execute` + the processor's `requiredPermissions` |
+| fs `ls`/`cat`/`stat`/`download` | `files:read` |
+| fs `upload`/`mkdir`/`rm` | `files:write` |
+| data explorer | `data:query` |
+| jobs read / manage | `jobs:read` / `jobs:manage` |
+| events / logs / shell WebSocket | authenticated / `logs:read` / `shell:execute` (see [Remote Shell Security](#remote-shell-security)) |
+| admin dashboard | `admin:access` |
+
+WebSockets authenticate with a single-use ticket: `POST /api/v1/qcli/sessions/ws-ticket` → `{ ticket, expiresIn: 30 }`, then connect with `?ticket=<ticket>`. Host routes can use `usersPlugin.requireAuth()` / `usersPlugin.requirePermission('perm')`. Processors declare `requiredPermissions: ['deploy:run']` to be enforced server-side.
+
+Events and logs sockets authenticated with a stored session are bound to it: when the session ends (logout, revoke/kick, user disabled or deleted, a password change becoming required, idle/absolute expiry) the socket is closed with **4401** `session ended`; for a revoke the events socket first receives `session-kicked`. Bound sockets are re-checked on every session/user/group change and after each expired-session sweep (`setCleanupInterval`, default 5 minutes). Sockets authenticated by an external auth adapter have no stored session and are not re-checked.
+
+See [`plugins/users/README.md`](plugins/users/README.md) for options, endpoints, custom storage and external auth adapters.
+
 ## Built-in Processors
 
 These processors ship with the library and are included in the standalone server:
@@ -504,7 +770,6 @@ These processors ship with the library and are included in the standalone server
 | `http` | HTTP request operations |
 | `hash` | Hash computation (MD5, SHA1, SHA256, SHA512) |
 | `base64` | Base64 encode/decode (sub-commands) |
-| `uuid` | UUID generation |
 
 ## Docker
 
@@ -540,10 +805,22 @@ packages/
       cli-command-parameter-descriptor.ts  # Parameter declaration
       cli-command-author.ts           # Author metadata
 plugins/
+  admin/                              # Admin dashboard plugin (auth, status, config, logs)
+  aws/                                # AWS cloud services (S3, EC2, Lambda, CloudWatch, etc.)
+  data-explorer/                      # Core data explorer abstraction
+  data-explorer-sql/                  # SQL data explorer provider (SQLite)
+  data-explorer-mongo/                # MongoDB data explorer provider
+  data-explorer-postgres/             # PostgreSQL data explorer provider
+  data-explorer-mysql/                # MySQL data explorer provider
+  data-explorer-mssql/                # MS SQL data explorer provider
+  data-explorer-redis/                # Redis data explorer provider
+  data-explorer-elasticsearch/        # Elasticsearch data explorer provider
   filesystem/                         # Core file storage abstraction (IFileStorageProvider, InMemory, OS)
   filesystem-json/                    # JSON file persistence provider
   filesystem-sqlite/                  # SQLite persistence provider (better-sqlite3)
   filesystem-s3/                      # Amazon S3 storage provider (@aws-sdk/client-s3)
+  jobs/                               # Job scheduling plugin
+  users/                              # Users plugin (auth, sessions, groups, audit)
   weather/                            # Weather module (example plugin)
 src/
   abstractions/                       # Re-exports from @qodalis/cli-server-abstractions
@@ -556,10 +833,11 @@ src/
     cli-command-executor-service.ts   # Command execution pipeline
     cli-response-builder.ts           # Structured output builder
     cli-event-socket-manager.ts       # WebSocket event broadcasting
+    cli-log-socket-manager.ts         # WebSocket log streaming
+    cli-shell-session-manager.ts      # PTY shell session management
   controllers/
-    cli-controller.ts                 # V1 REST API (/api/v1/cli)
-    cli-controller-v2.ts              # V2 REST API (/api/v2/cli)
-    cli-version-controller.ts         # Version discovery (/api/cli/versions)
+    cli-controller.ts                 # V1 REST API (/api/v1/qcli)
+    cli-version-controller.ts         # Version discovery (/api/qcli/versions)
   extensions/
     cli-builder.ts                    # Fluent registration API (addProcessor, addModule)
   processors/                         # Built-in processors

package/dist/src/abstractions/index.d.ts

@@ -1,2 +1,2 @@
-export { ICliCommandAuthor, CliCommandAuthor, DefaultLibraryAuthor, CliProcessCommand, ICliCommandParameterDescriptor, CliCommandParameterDescriptor, ICliCommandProcessor, CliCommandProcessor, ICliModule, CliModule, ICliJob, ICliJobExecutionContext, ICliJobLogger, CliJobOptions, JobOverlapPolicy, ICliJobStorageProvider, JobExecution, JobExecutionStatus, JobState, JobStatus, JobLogEntry, JobLogLevel, } from '@qodalis/cli-server-abstractions';
+export { ICliCommandAuthor, CliCommandAuthor, DefaultLibraryAuthor, CliProcessCommand, ICliCommandParameterDescriptor, CliCommandParameterDescriptor, ICliCommandProcessor, CliCommandProcessor, ICliModule, CliModule, ICliJob, ICliJobExecutionContext, ICliJobLogger, CliJobOptions, JobOverlapPolicy, ICliJobStorageProvider, JobExecution, JobExecutionStatus, JobState, JobStatus, JobLogEntry, JobLogLevel, CliStructuredOutput, CliStructuredResponse, IDataExplorerProvider, DataExplorerProviderOptions, DataExplorerLanguage, DataExplorerOutputFormat, DataExplorerTemplate, DataExplorerParameterDescriptor, DataExplorerExecutionContext, DataExplorerResult, DataExplorerExecuteRequest, DataExplorerSourceInfo, ICliProcessorFilter, ICliStreamCommandProcessor, isStreamCapable, } from '@qodalis/cli-server-abstractions';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/abstractions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/abstractions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,OAAO,EACP,uBAAuB,EACvB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,WAAW,GACd,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/abstractions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,OAAO,EACP,uBAAuB,EACvB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,+BAA+B,EAC/B,4BAA4B,EAC5B,kBAAkB,EAClB,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,EAC1B,eAAe,GAClB,MAAM,kCAAkC,CAAC"}

package/dist/src/abstractions/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliModule = exports.CliCommandProcessor = exports.CliCommandParameterDescriptor = exports.DefaultLibraryAuthor = exports.CliCommandAuthor = void 0;
+exports.isStreamCapable = exports.DataExplorerOutputFormat = exports.DataExplorerLanguage = exports.CliModule = exports.CliCommandProcessor = exports.CliCommandParameterDescriptor = exports.DefaultLibraryAuthor = exports.CliCommandAuthor = void 0;
 var cli_server_abstractions_1 = require("@qodalis/cli-server-abstractions");
 Object.defineProperty(exports, "CliCommandAuthor", { enumerable: true, get: function () { return cli_server_abstractions_1.CliCommandAuthor; } });
 Object.defineProperty(exports, "DefaultLibraryAuthor", { enumerable: true, get: function () { return cli_server_abstractions_1.DefaultLibraryAuthor; } });
 Object.defineProperty(exports, "CliCommandParameterDescriptor", { enumerable: true, get: function () { return cli_server_abstractions_1.CliCommandParameterDescriptor; } });
 Object.defineProperty(exports, "CliCommandProcessor", { enumerable: true, get: function () { return cli_server_abstractions_1.CliCommandProcessor; } });
 Object.defineProperty(exports, "CliModule", { enumerable: true, get: function () { return cli_server_abstractions_1.CliModule; } });
+Object.defineProperty(exports, "DataExplorerLanguage", { enumerable: true, get: function () { return cli_server_abstractions_1.DataExplorerLanguage; } });
+Object.defineProperty(exports, "DataExplorerOutputFormat", { enumerable: true, get: function () { return cli_server_abstractions_1.DataExplorerOutputFormat; } });
+Object.defineProperty(exports, "isStreamCapable", { enumerable: true, get: function () { return cli_server_abstractions_1.isStreamCapable; } });
 //# sourceMappingURL=index.js.map

package/dist/src/abstractions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/abstractions/index.ts"],"names":[],"mappings":";;;AAAA,4EAuB0C;AArBtC,2HAAA,gBAAgB,OAAA;AAChB,+HAAA,oBAAoB,OAAA;AAGpB,wIAAA,6BAA6B,OAAA;AAE7B,8HAAA,mBAAmB,OAAA;AAEnB,oHAAA,SAAS,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/abstractions/index.ts"],"names":[],"mappings":";;;AAAA,4EAsC0C;AApCtC,2HAAA,gBAAgB,OAAA;AAChB,+HAAA,oBAAoB,OAAA;AAGpB,wIAAA,6BAA6B,OAAA;AAE7B,8HAAA,mBAAmB,OAAA;AAEnB,oHAAA,SAAS,OAAA;AAiBT,+HAAA,oBAAoB,OAAA;AACpB,mIAAA,wBAAwB,OAAA;AASxB,0HAAA,eAAe,OAAA"}

package/dist/src/auth/cli-server-auth-gate.d.ts

@@ -0,0 +1,31 @@
+import { RequestHandler } from 'express';
+import { ICliCommandRegistry } from '../services/cli-command-registry';
+import { CliServerAuthContext, ICliServerAuth } from './cli-server-auth';
+declare global {
+    namespace Express {
+        interface Request {
+            /** Set by the server auth gate when the users plugin protects the server. */
+            qcliServerAuth?: CliServerAuthContext;
+        }
+    }
+}
+/** Normalizes a request path for classification: lower-case, single slashes, no trailing slash. */
+export declare function normalizePath(path: string): string;
+export interface ServerAuthGateOptions {
+    registry: ICliCommandRegistry;
+    /** Prefixes serving the CLI controller (`/api/v1/qcli`, custom basePath). */
+    cliPrefixes: string[];
+    /** Extra public routes as `"METHOD /path"` (e.g. a plugin's own login). */
+    publicRoutes: Set<string>;
+}
+/** Collects `requiredPermissions` along the resolved processor chain. */
+export declare function processorPermissions(registry: ICliCommandRegistry, command: unknown, chain: unknown): string[];
+/** Permissions required for a (protected) server route. */
+export declare function requiredServerPermissions(method: string, path: string, body: any, options: ServerAuthGateOptions): string[];
+/**
+ * Express middleware protecting every `/api/...` route of the CLI server when
+ * an auth provider with `protectServer` is installed. Without a provider it is
+ * a no-op, so servers without the users plugin behave as before.
+ */
+export declare function createServerAuthGate(getAuth: () => ICliServerAuth | undefined, options: ServerAuthGateOptions): RequestHandler;
+//# sourceMappingURL=cli-server-auth-gate.d.ts.map

package/dist/src/auth/cli-server-auth-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-server-auth-gate.d.ts","sourceRoot":"","sources":["../../../src/auth/cli-server-auth-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAA6B,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKpG,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,OAAO,CAAC;QACd,UAAU,OAAO;YACb,6EAA6E;YAC7E,cAAc,CAAC,EAAE,oBAAoB,CAAC;SACzC;KACJ;CACJ;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAgBD,MAAM,WAAW,qBAAqB;IAClC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,2EAA2E;IAC3E,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,GACf,MAAM,EAAE,CAkBV;AAED,2DAA2D;AAC3D,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAiB3H;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,MAAM,cAAc,GAAG,SAAS,EACzC,OAAO,EAAE,qBAAqB,GAC/B,cAAc,CAkDhB"}

package/dist/src/auth/cli-server-auth-gate.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+exports.processorPermissions = processorPermissions;
+exports.requiredServerPermissions = requiredServerPermissions;
+exports.createServerAuthGate = createServerAuthGate;
+const cli_server_auth_1 = require("./cli-server-auth");
+const logger_1 = require("../utils/logger");
+const logger = (0, logger_1.createLogger)('ServerAuth');
+/** Normalizes a request path for classification: lower-case, single slashes, no trailing slash. */
+function normalizePath(path) {
+    const p = path.toLowerCase().replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+    return p || '/';
+}
+const PUBLIC_GET = new Set([
+    '/api/qcli/versions',
+    '/api/qcli/version',
+    '/api/qcli/capabilities',
+    '/api/cli/versions',
+    '/api/v1/qcli/version',
+    '/api/v1/qcli/capabilities',
+    '/health',
+    '/healthz',
+    '/api/health',
+]);
+const FS_READ = new Set(['ls', 'cat', 'stat', 'download']);
+/** Collects `requiredPermissions` along the resolved processor chain. */
+function processorPermissions(registry, command, chain) {
+    if (typeof command !== 'string')
+        return [];
+    const root = registry.processors.find((p) => p.command.toLowerCase() === command.toLowerCase());
+    if (!root)
+        return [];
+    const out = [...(root.requiredPermissions ?? [])];
+    let current = root;
+    if (Array.isArray(chain)) {
+        for (const sub of chain) {
+            if (typeof sub !== 'string')
+                break;
+            const child = current.processors?.find((p) => p.command.toLowerCase() === sub.toLowerCase());
+            if (!child)
+                break;
+            out.push(...(child.requiredPermissions ?? []));
+            current = child;
+        }
+    }
+    return out;
+}
+/** Permissions required for a (protected) server route. */
+function requiredServerPermissions(method, path, body, options) {
+    for (const prefix of options.cliPrefixes) {
+        if (path === `${prefix}/execute` || path === `${prefix}/execute/stream`) {
+            return [cli_server_auth_1.CliServerPermissions.CommandsExecute, ...processorPermissions(options.registry, body?.command, body?.chainCommands)];
+        }
+    }
+    if (path === '/api/qcli/fs' || path.startsWith('/api/qcli/fs/')) {
+        const op = path.slice('/api/qcli/fs/'.length);
+        return [method === 'GET' && FS_READ.has(op) ? cli_server_auth_1.CliServerPermissions.FilesRead : cli_server_auth_1.CliServerPermissions.FilesWrite];
+    }
+    if (path === '/api/qcli/data-explorer' || path.startsWith('/api/qcli/data-explorer/')) {
+        return [cli_server_auth_1.CliServerPermissions.DataQuery];
+    }
+    if (path === '/api/v1/qcli/jobs' || path.startsWith('/api/v1/qcli/jobs/')) {
+        return [method === 'GET' ? cli_server_auth_1.CliServerPermissions.JobsRead : cli_server_auth_1.CliServerPermissions.JobsManage];
+    }
+    return [];
+}
+/**
+ * Express middleware protecting every `/api/...` route of the CLI server when
+ * an auth provider with `protectServer` is installed. Without a provider it is
+ * a no-op, so servers without the users plugin behave as before.
+ */
+function createServerAuthGate(getAuth, options) {
+    return (req, res, next) => {
+        const auth = getAuth();
+        if (!auth || !auth.protectServer) {
+            next();
+            return;
+        }
+        const method = req.method.toUpperCase();
+        if (method === 'OPTIONS') {
+            next();
+            return;
+        }
+        const path = normalizePath(req.path);
+        if (!path.startsWith('/api/') && path !== '/api') {
+            next();
+            return;
+        }
+        if ((method === 'GET' || method === 'HEAD') && PUBLIC_GET.has(path)) {
+            next();
+            return;
+        }
+        if (options.publicRoutes.has(`${method} ${path}`) || auth.handlesPath(path, method)) {
+            next();
+            return;
+        }
+        auth.authenticateRequest(req).then((ctx) => {
+            const missing = requiredServerPermissions(method, path, req.body, options).filter((p) => !auth.hasPermission(ctx, p));
+            if (missing.length > 0) {
+                res.status(403).json({ error: `forbidden: missing permission ${missing.join(', ')}` });
+                return;
+            }
+            req.qcliServerAuth = ctx;
+            next();
+        }, (err) => {
+            if (typeof err?.status !== 'number') {
+                // not an auth error (e.g. a store failure): never expose its message
+                logger.error('authentication failed unexpectedly:', err);
+                res.status(500).json({ error: 'internal server error' });
+                return;
+            }
+            const status = err.status;
+            res.status(status).json({ error: status === 401 ? err.message || 'unauthorized' : err.message || 'forbidden' });
+        });
+    };
+}
+//# sourceMappingURL=cli-server-auth-gate.js.map