@quatrain/cli 1.1.9 → 1.1.10

package/README.md

@@ -1,60 +1,103 @@
-# @quatrain/core-cli
+# @quatrain/cli
 
-The official Command Line Interface (CLI) for the Quatrain ecosystem.
-This CLI provides tools to scaffold projects, generate normalized bootloader configurations, and create migration files.
+The official Command Line Interface (CLI) and script utility library for the Quatrain ecosystem. 
 
-## Installation
+This package serves two distinct purposes:
+1. **Programmatic Utilities (Library API):** Exported classes and prompt helpers to build interactive scripts and run system subprocesses (e.g. within agent skills).
+2. **Core Command-Line Executable (`core`):** A global terminal command runner to scaffold projects, generate configurations, and manage deployments.
 
-You can install the CLI globally via NPM or Yarn, or run it on the fly using `npx` or `bunx`.
+---
 
-### Global Installation
+## 1. Programmatic Utilities (Library API)
 
-```bash
-npm install -g @quatrain/core-cli
-# or
-yarn global add @quatrain/core-cli
-# or via Bun
-bun add -g @quatrain/core-cli
-```
+Import these utilities directly in your TypeScript/JavaScript scripts to interact with the user or run external processes.
 
-### On-the-fly Execution
+### A. Fluent Command Executor (`Command`)
 
-```bash
-npx @quatrain/core-cli <command>
-# or
-bunx @quatrain/core-cli <command>
+The `Command` class provides a cross-platform, fluent builder-pattern interface to execute system subprocesses. It simplifies spawning commands, passing arguments, setting working directories, extending environment variables, and supports PowerShell routing.
+
+```typescript
+import { Command } from '@quatrain/cli';
+
+const result = await Command.create('kubectl')
+  .arg('apply')
+  .arg('-f')
+  .arg('deployment.yaml')
+  .cwd('/path/to/project')
+  .env({ KUBECONFIG: '/path/to/config' })
+  .execute();
+
+if (result.success) {
+  console.log(`Success: ${result.stdout}`);
+} else {
+  console.error(`Exit code: ${result.code}, Error: ${result.stderr}`);
+}
 ```
 
-## Commands
+**Fluent Methods:**
+- `Command.create(bin)` / `new Command(bin)`: Start building a command for the given binary.
+- `.arg(value)` / `.args([values])`: Append command-line arguments.
+- `.cwd(dir)`: Set the execution working directory.
+- `.env({ KEY: VALUE })`: Set or extend environment variables.
+- `.inherit()`: Direct stdout and stderr to the parent process terminal.
+- `.usePowerShell(use, type)`: Force process execution through PowerShell (`powershell.exe` or `pwsh`) with safe quote escaping.
+- `.execute()`: Run the process asynchronously and return `{ stdout, stderr, code, success }`.
 
-### `core generate scaffold <project-name>`
-Quickly initializes a new Quatrain project.
-- Creates a base directory.
-- Sets up the `apps/`, `data/`, `config/`, `packages/`, and `migrations/` folders.
-- Generates a monorepo-ready `package.json` utilizing Yarn workspaces.
-- Generates a `tsconfig.json` pre-configured with the required path mappings.
+### B. Interactive Prompt Helpers
 
-### `core generate config`
-Starts an interactive wizard to generate a `quatrain.json` configuration file.
-- Prompts for Backend, Auth, Queue, Storage, and Messaging adapters.
-- Generates a normalized JSON configuration.
-- The generated `env(...)` tokens will be resolved at runtime by the `AppBootloader`.
+Helpers wrapping `inquirer` to prompt user inputs cleanly:
 
-### `core generate migration <name>`
-Scaffolds a new migration file.
-- Creates a `migrations/` directory if it does not exist.
-- Generates a timestamped TypeScript file (e.g., `20260427184500_init.ts`).
-- Provides boilerplate `up()` and `down()` methods.
+```typescript
+import { askConfirm, askInput, askChoice } from '@quatrain/cli';
 
-## Language Guidelines
-> **Recommendation:** All text contents (such as console logs, commit messages, and comments) within the Quatrain ecosystem must be written in **International English**. This ensures accessibility and maintainability for developers worldwide.
+// Yes/No Confirmations
+const proceed = await askConfirm('Do you want to deploy now?');
+
+// String Inputs
+const name = await askInput('Enter your username:', 'default_user');
+
+// Multi-choice select lists
+const selected = await askChoice('Select action:', [
+  { name: 'Sync Google Calendar', value: 'sync' },
+  { name: 'Reset Database', value: 'reset' }
+]);
+```
+
+---
+
+## 2. Core Command-Line Executable
 
-## HOWTO / Usage Examples
+A global CLI tool invoked via the `core` command (or `quatrain` depending on symlinks).
+
+### Installation
+
+Install globally or run on-the-fly:
 
 ```bash
-# Example of scaffolding a new project
-yarn global add @quatrain/core-cli
-quatrain generate scaffold my-app
-cd my-app
-yarn install
+# Global
+bun add -g @quatrain/cli
+
+# Run on the fly
+bunx @quatrain/cli <command>
 ```
+
+### Commands Reference
+
+#### `core deploy`
+Manage Kubernetes deployments (create, list, modify, promote, delete namespaces and manifests).
+
+#### `core generate scaffold <project-name>`
+Initialize a new Quatrain project structure:
+- Sets up directories: `apps/`, `data/`, `config/`, `packages/`, `migrations/`.
+- Generates a monorepo-ready workspace `package.json` and a pre-configured `tsconfig.json`.
+
+#### `core generate config`
+Start an interactive wizard to generate the `quatrain.json` bootloader configuration file.
+
+#### `core generate migration <name>`
+Scaffold a timestamped TypeScript migration file (e.g., `migrations/20260427_name.ts`) with template `up()` and `down()` blocks.
+
+---
+
+## Language Guidelines
+> **Recommendation:** All text contents (logs, console prints, commit messages, comments) within the Quatrain ecosystem must be written in **International English** to ensure global team maintainability.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/cli",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "license": "AGPL-3.0-only",
   "description": "Quatrain Core CLI for generating configurations and migrations",
   "main": "dist/index.js",