@qodalis/cli-core 0.0.15 → 2.0.0-beta.1

package/README.md

@@ -1,34 +1,45 @@
-<h1 align="center">Qodalis Angular Web CLI</h1>
+<h1 align="center">Qodalis Web CLI</h1>
 
-<p align="center">A web-based terminal for Angular applications — extensible, themeable, and packed with built-in developer tools.</p>
+<p align="center">A web-based terminal for Angular, React, and Vue — extensible, themeable, and packed with built-in developer tools.</p>
 
 <div align="center">
 
-[![npm version](https://img.shields.io/npm/v/@qodalis/angular-cli.svg)](https://www.npmjs.com/package/@qodalis/angular-cli)
-[![Build Status](https://github.com/qodalis-solutions/angular-web-cli/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/qodalis-solutions/angular-web-cli/actions)
+[![npm version](https://img.shields.io/npm/v/@qodalis/cli.svg?label=cli)](https://www.npmjs.com/package/@qodalis/cli)
+[![npm version](https://img.shields.io/npm/v/@qodalis/angular-cli.svg?label=angular)](https://www.npmjs.com/package/@qodalis/angular-cli)
+[![npm version](https://img.shields.io/npm/v/@qodalis/react-cli.svg?label=react)](https://www.npmjs.com/package/@qodalis/react-cli)
+[![npm version](https://img.shields.io/npm/v/@qodalis/vue-cli.svg?label=vue)](https://www.npmjs.com/package/@qodalis/vue-cli)
+[![Build Status](https://github.com/qodalis-solutions/web-cli/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/qodalis-solutions/web-cli/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 </div>
 
 <p align="center">
-  <a href="https://cli-docs.qodalis.com/">Documentation</a> &middot;
-  <a href="https://stackblitz.com/~/github.com/n1colae-lupei/stackblitz-qodalis-cli-example">Live Demo</a> &middot;
-  <a href="https://www.npmjs.com/package/@qodalis/angular-cli">npm</a>
+  <a href="https://cli.qodalis.com/">Live Demo</a> &middot;
+  <a href="https://cli.qodalis.com/docs/">Documentation</a> &middot;
+  <a href="https://www.npmjs.com/package/@qodalis/cli">npm</a>
 </p>
 
 ---
 
 ![Help command](assets/help_command.gif)
 
-## Installation
+## Packages
 
-```bash
-npm install @qodalis/angular-cli
-```
+| Package | Description |
+|---------|-------------|
+| [`@qodalis/cli-core`](https://www.npmjs.com/package/@qodalis/cli-core) | Shared interfaces, models, and types |
+| [`@qodalis/cli`](https://www.npmjs.com/package/@qodalis/cli) | Framework-agnostic terminal engine (50+ built-in commands) |
+| [`@qodalis/angular-cli`](https://www.npmjs.com/package/@qodalis/angular-cli) | Angular wrapper |
+| [`@qodalis/react-cli`](https://www.npmjs.com/package/@qodalis/react-cli) | React wrapper |
+| [`@qodalis/vue-cli`](https://www.npmjs.com/package/@qodalis/vue-cli) | Vue 3 wrapper |
 
 ## Quick Start
 
-**1. Import the module:**
+### Angular
+
+```bash
+npm install @qodalis/angular-cli
+```
 
 ```typescript
 import { CliModule } from '@qodalis/angular-cli';
@@ -39,7 +50,7 @@ import { CliModule } from '@qodalis/angular-cli';
 export class AppModule {}
 ```
 
-**2. Add the styles to `angular.json`:**
+Add styles to `angular.json`:
 
 ```json
 {
@@ -49,20 +60,50 @@ export class AppModule {}
 }
 ```
 
-**3. Add the terminal to your template:**
-
 ```html
 <!-- Full terminal -->
 <cli [options]="cliOptions" />
 
-<!-- Collapsible panel at the bottom of the page -->
+<!-- Collapsible panel -->
 <cli-panel />
 ```
 
-**4. Configure (optional):**
+### React
+
+```bash
+npm install @qodalis/react-cli
+```
+
+```tsx
+import { Cli } from '@qodalis/react-cli';
+
+function App() {
+  return <Cli style={{ width: '100vw', height: '100vh' }} />;
+}
+```
+
+### Vue
+
+```bash
+npm install @qodalis/vue-cli
+```
+
+```vue
+<script setup lang="ts">
+import { Cli } from '@qodalis/vue-cli';
+</script>
+
+<template>
+  <Cli :style="{ width: '100vw', height: '100vh' }" />
+</template>
+```
+
+### Configuration (all frameworks)
+
+Pass options to customize the terminal:
 
 ```typescript
-cliOptions = {
+const options = {
   welcomeMessage: {
     message: '-- your custom welcome message --',
     show: 'daily', // 'never', 'once', 'daily', 'always'
@@ -83,7 +124,7 @@ cliOptions = {
 | `version` | `ver` | Display CLI version and documentation link |
 | `hotkeys` | `shortcuts`, `keys` | Show keyboard shortcuts |
 | `history` | `hist` | Browse and clear command history |
-| `theme` | `themes` | Apply, customize, and save terminal themes |
+| `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 |
 
@@ -145,6 +186,8 @@ pkg update                     # Update all packages
 pkg update guid@1.0.2          # Pin a specific version
 pkg check                      # Check for updates
 pkg versions guid              # Show all published versions
+pkg source set                 # Interactively select a package source (CDN)
+pkg source set unpkg           # Set package source directly
 ```
 
 ### Available Packages
@@ -170,9 +213,318 @@ pkg add lodash
 eval _.map([1, 2, 3], n => n * 2)
 ```
 
-## Extending with Custom Commands
+## Creating a CLI Plugin
+
+### Quick Start
+
+Scaffold a complete plugin project with a single command:
+
+```bash
+npx @qodalis/create-cli-plugin
+```
+
+The interactive prompts will ask for:
+
+| Prompt | Description | Example |
+|--------|-------------|---------|
+| **Plugin name** | Lowercase, no spaces, no `cli-` prefix (added automatically) | `weather` |
+| **Description** | Short description of the plugin | `Weather forecasts` |
+| **Processor class name** | PascalCase name for the command processor class | `Weather` |
+
+You can also skip the prompts by passing arguments directly:
+
+```bash
+npx @qodalis/create-cli-plugin --name weather --description "Weather forecasts" --processor-name Weather
+```
+
+Or install globally:
+
+```bash
+npm install -g @qodalis/create-cli-plugin
+create-cli-plugin
+```
+
+### Standalone vs Monorepo Mode
+
+The tool auto-detects whether you're inside the `web-cli` monorepo:
+
+| Mode | Detection | Output directory | Package manager |
+|------|-----------|-----------------|-----------------|
+| **Standalone** | Any directory outside web-cli | `./qodalis-cli-<name>/` | npm or pnpm (auto-detected) |
+| **Monorepo** | Inside web-cli workspace | `packages/plugins/<name>/` | pnpm (workspace) |
+
+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>`
+
+### Generated Project Structure
+
+```
+qodalis-cli-weather/                    # or packages/plugins/weather/ in monorepo
+  package.json                          # npm package with CJS/ESM/UMD exports
+  tsup.config.ts                        # Build config (library + IIFE bundles)
+  tsconfig.json                         # TypeScript config
+  README.md                             # Auto-generated README
+  src/
+    public-api.ts                       # Public exports + ICliModule declaration
+    cli-entrypoint.ts                   # IIFE entrypoint for browser runtime loading
+    lib/
+      version.ts                        # LIBRARY_VERSION + API_VERSION constants
+      index.ts                          # Barrel re-exports
+      processors/
+        cli-weather-command-processor.ts # Command processor (your main logic goes here)
+    tests/
+      index.spec.ts                     # Jasmine test scaffold
+```
 
-Create a class implementing `ICliCommandProcessor`:
+### Step-by-Step Workflow
+
+#### 1. Scaffold the plugin
+
+```bash
+npx @qodalis/create-cli-plugin --name weather
+```
+
+#### 2. Implement your command processor
+
+Edit `src/lib/processors/cli-weather-command-processor.ts`:
+
+```typescript
+import {
+    CliProcessCommand,
+    DefaultLibraryAuthor,
+    ICliCommandProcessor,
+    ICliExecutionContext,
+} from '@qodalis/cli-core';
+import { LIBRARY_VERSION } from '../version';
+
+export class CliWeatherCommandProcessor implements ICliCommandProcessor {
+    command = 'weather';
+    description = 'Weather forecasts';
+    author = DefaultLibraryAuthor;
+    version = LIBRARY_VERSION;
+
+    // Sub-commands
+    processors?: ICliCommandProcessor[] = [
+        {
+            command: 'forecast',
+            description: 'Get weather forecast for a city',
+            parameters: [
+                {
+                    name: 'city',
+                    aliases: ['c'],
+                    description: 'City name',
+                    required: true,
+                    type: 'string',
+                },
+                {
+                    name: 'days',
+                    aliases: ['d'],
+                    description: 'Number of days',
+                    required: false,
+                    type: 'number',
+                    defaultValue: '3',
+                },
+            ],
+            processCommand: async (command, context) => {
+                const city = command.args['city'];
+                const days = parseInt(command.args['days'] ?? '3');
+                context.writer.writeln(`Forecast for ${city} (${days} days):`);
+                context.writer.writeSuccess('Sunny, 25°C');
+            },
+        },
+        {
+            command: 'current',
+            description: 'Get current weather',
+            acceptsRawInput: true,    // command.value = text after 'current'
+            valueRequired: true,       // error if no value provided
+            processCommand: async (command, context) => {
+                context.writer.writeln(`Current weather in ${command.value}: Sunny, 25°C`);
+            },
+        },
+    ];
+
+    // Default handler (runs when user types just 'weather')
+    async processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void> {
+        context.executor.showHelp(command, context);
+    }
+}
+```
+
+#### 3. Build the plugin
+
+**Standalone:**
+
+```bash
+cd qodalis-cli-weather
+npm run build          # or: npx tsup
+```
+
+**Monorepo:**
+
+```bash
+pnpm nx build weather
+```
+
+Build output goes to `dist/weather/` with three bundles:
+- `public-api.js` (CJS) + `public-api.mjs` (ESM) + `public-api.d.ts` (types)
+- `umd/index.js` (IIFE — self-contained browser bundle for runtime `pkg add`)
+
+#### 4. Test the plugin
+
+**Standalone:** Add your preferred test runner.
+
+**Monorepo:**
+
+```bash
+pnpm nx test weather
+```
+
+#### 5. Publish to npm
+
+```bash
+cd dist/weather         # or: cd qodalis-cli-weather/dist
+npm publish --access public
+```
+
+Users can then install your plugin at runtime in any Qodalis CLI terminal:
+
+```bash
+pkg add @qodalis/cli-weather
+weather forecast --city "New York"
+```
+
+### The ICliModule Export
+
+Every plugin exports an `ICliModule` object in `public-api.ts`. This is how frameworks register your plugin:
+
+```typescript
+import { ICliModule } from '@qodalis/cli-core';
+import { CliWeatherCommandProcessor } from './lib/processors/cli-weather-command-processor';
+import { API_VERSION } from './lib/version';
+
+export const weatherModule: ICliModule = {
+    apiVersion: API_VERSION,         // must be >= 2
+    name: '@qodalis/cli-weather',
+    processors: [new CliWeatherCommandProcessor()],
+};
+```
+
+`ICliModule` also supports optional lifecycle hooks and configuration:
+
+```typescript
+export const weatherModule: ICliModule = {
+    apiVersion: 2,
+    name: '@qodalis/cli-weather',
+    processors: [new CliWeatherCommandProcessor()],
+    dependencies: ['@qodalis/cli-curl'],     // boot other modules first
+    priority: 0,                              // boot order (lower = first)
+    configure(config) { /* ... */ return this; },
+    onInit(context) { /* before processors initialize */ },
+    onAfterBoot(context) { /* after all modules boot */ },
+    onDestroy(context) { /* teardown */ },
+};
+```
+
+### The IIFE Entrypoint
+
+`src/cli-entrypoint.ts` enables runtime loading via `pkg add`. It calls `bootCliModule()` which registers the module with the global `window.__cliModuleRegistry`:
+
+```typescript
+import { bootCliModule, ICliModule } from '@qodalis/cli-core';
+import { CliWeatherCommandProcessor } from './lib/processors/cli-weather-command-processor';
+import { API_VERSION } from './lib/version';
+
+const module: ICliModule = {
+    apiVersion: API_VERSION,
+    name: '@qodalis/cli-weather',
+    processors: [new CliWeatherCommandProcessor()],
+};
+
+bootCliModule(module);
+```
+
+### Execution Context API
+
+The `ICliExecutionContext` passed to `processCommand` provides:
+
+| Property | Description |
+|----------|-------------|
+| `context.writer` | Terminal output — `writeln()`, `writeInfo()`, `writeSuccess()`, `writeError()`, `wrapInColor()` |
+| `context.reader` | User input — `readLine()`, `readPassword()`, `readConfirm()`, `readSelect()`, `readMultiSelect()`, `readNumber()` |
+| `context.executor` | Command execution — `showHelp(command, context)` |
+| `context.clipboard` | Clipboard — `write()`, `read()` |
+| `context.state` | Persistent key-value store |
+| `context.progressBar` | Progress bar widget |
+| `context.spinner` | Spinner widget |
+| `context.terminal` | Raw xterm.js `Terminal` instance |
+| `context.onAbort` | `Subject<void>` for Ctrl+C cancellation |
+| `context.enterFullScreenMode()` | Switch to full-screen TUI mode |
+| `context.createInterval()` / `context.createTimeout()` | Managed timers (auto-cleaned on abort) |
+
+### Registering Plugins in Your App
+
+#### Angular (via providers)
+
+```typescript
+import { CliModule, resolveCliModuleProvider } from '@qodalis/angular-cli';
+import { weatherModule } from '@qodalis/cli-weather';
+
+@NgModule({
+  imports: [CliModule],
+  providers: [resolveCliModuleProvider(weatherModule)],
+})
+export class AppModule {}
+```
+
+#### Angular (via template input)
+
+```typescript
+import { weatherModule } from '@qodalis/cli-weather';
+
+export class AppComponent {
+  modules = [weatherModule];
+}
+```
+
+```html
+<cli [modules]="modules" />
+```
+
+#### React
+
+```tsx
+import { CliConfigProvider, Cli } from '@qodalis/react-cli';
+import { weatherModule } from '@qodalis/cli-weather';
+
+function App() {
+  return (
+    <CliConfigProvider modules={[weatherModule]}>
+      <Cli />
+    </CliConfigProvider>
+  );
+}
+```
+
+#### Vue
+
+```vue
+<script setup lang="ts">
+import { CliConfigProvider, Cli } from '@qodalis/vue-cli';
+import { weatherModule } from '@qodalis/cli-weather';
+</script>
+
+<template>
+  <CliConfigProvider :modules="[weatherModule]">
+    <Cli />
+  </CliConfigProvider>
+</template>
+```
+
+## Extending with Inline Commands
+
+For quick one-off commands without creating a full plugin, implement `ICliCommandProcessor` directly in your app:
 
 ```typescript
 import {
@@ -184,7 +536,7 @@ import {
 export class GreetCommandProcessor implements ICliCommandProcessor {
   command = 'greet';
   description = 'Greet someone by name';
-  allowUnlistedCommands = true;
+  acceptsRawInput = true;
   valueRequired = true;
 
   async processCommand(
@@ -196,16 +548,14 @@ export class GreetCommandProcessor implements ICliCommandProcessor {
 }
 ```
 
-Register it in your module:
+Register it with your framework (Angular: `resolveCommandProcessorProvider(GreetCommandProcessor)`, React/Vue: pass via `processors` prop), or wrap it in an inline `ICliModule`:
 
 ```typescript
-import { CliModule, resolveCommandProcessorProvider } from '@qodalis/angular-cli';
-
-@NgModule({
-  imports: [CliModule],
-  providers: [resolveCommandProcessorProvider(GreetCommandProcessor)],
-})
-export class AppModule {}
+const myModule: ICliModule = {
+  apiVersion: 2,
+  name: 'my-app-commands',
+  processors: [new GreetCommandProcessor()],
+};
 ```
 
 ```bash
@@ -213,14 +563,32 @@ export class AppModule {}
 Hello, World!
 ```
 
+## Using the Engine Directly
+
+For advanced use cases or non-framework environments, use `CliEngine` directly:
+
+```typescript
+import { CliEngine } from '@qodalis/cli';
+
+const engine = new CliEngine(document.getElementById('terminal')!, {
+  welcomeMessage: { message: 'Welcome!', show: 'always' },
+});
+
+engine.registerProcessors([new GreetCommandProcessor()]);
+await engine.start();
+```
+
 ## Features
 
-- **Command chaining** with `&&` and `||` operators
+- **Multi-framework** — Angular, React, Vue, or vanilla JS
+- **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
 - **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
 - **Progress bars, spinners, and text animations**
 - **Runtime package installation** from npm
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@qodalis/cli-core",
-  "version": "0.0.15",
-  "description": "Core Angular CLI for @qodalis extensions.",
+  "version": "2.0.0-beta.1",
+  "description": "Core interfaces, types, and utilities for the @qodalis CLI ecosystem.",
   "author": "Nicolae Lupei, Qodalis Solutions",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/qodalis-solutions/angular-web-cli"
+    "url": "https://github.com/qodalis-solutions/web-cli"
   },
   "homepage": "https://qodalis.com",
   "keywords": [
@@ -14,29 +14,22 @@
     "cli",
     "qodalis",
     "terminal",
-    "angular",
+    "interfaces",
+    "types",
     "extensions"
   ],
-  "peerDependencies": {
-    "@angular/common": "^16.2.0",
-    "@angular/core": "^16.2.0"
+  "main": "./public-api.js",
+  "module": "./public-api.mjs",
+  "types": "./public-api.d.ts",
+  "exports": {
+    ".": {
+      "types": "./public-api.d.ts",
+      "import": "./public-api.mjs",
+      "require": "./public-api.js"
+    }
   },
   "dependencies": {
-    "tslib": "^2.3.0",
     "@xterm/xterm": "^5.5.0"
   },
-  "sideEffects": false,
-  "module": "fesm2022/qodalis-cli-core.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "esm2022": "./esm2022/qodalis-cli-core.mjs",
-      "esm": "./esm2022/qodalis-cli-core.mjs",
-      "default": "./fesm2022/qodalis-cli-core.mjs"
-    }
-  }
-}
+  "sideEffects": false
+}