bunosh 0.3.1 → 0.4.0

package/README.md

@@ -1,27 +1,88 @@
 # 🍲 Bunosh
 
-> *Named after **banosh**, a traditional Ukrainian dish from cornmeal cooked with various ingredients such as mushrooms, cheese, sour cream*
-
 <p align="center">
   <img src="assets/logo.png" alt="Logo" width="150">
 </p>
 
+<p align="center">
+  <strong>Your exceptional task runner</strong>
+</p>
+
+<p align="center">
+  Transform JavaScript functions into CLI commands.
+</p>
+
+---
+
 ## What is Bunosh?
 
-Bunosh is a modern task runner that transforms JavaScript functions into CLI commands. Write your build, deploy, and automation tasks in JavaScript and run them directly from the command line.
+Bunosh is a modern task runner that turns your JavaScript functions into CLI commands instantly. No configuration, no boilerplate - just write functions and run them from the terminal.
+
+> *Named after **banosh**, a traditional Ukrainian dish from cornmeal cooked with various ingredients*
 
-**Why Bunosh?**
-- ✨ **Zero Configuration**: Write functions, get CLI commands
-- 🚀 **Fast Execution**: Built for speed with beautiful terminal output
-- 🎨 **Rich Output**: Colored formatting with progress indicators
-- 📦 **Built-in Tasks**: Shell execution, HTTP requests, file operations
-- 🔧 **Cross-Platform**: Works on macOS, Linux, and Windows
+### ✨ Key Features
+
+- **🚀 Zero Configuration** - Write functions, get CLI commands automatically
+- **🎨 Pure JavaScript** - write commands as JavaScript functions
+- **🏠 Personal Commands** - Global commands from `~/Bunoshfile.js` available everywhere with `my:` namespace
+- **📦 Built-in Tasks** - Shell execution, HTTP requests, file operations
+- **🤖 AI-Powered** - integrate LLM calls into your daily tasks
+- **🔧 Cross-Platform** - Works seamlessly on macOS, Linux, and Windows. Via bun, npm, or as single executable.
+- **🎯 Smart CLI** - Auto-completion, help generation, and intuitive argument handling
+
+## Hello World
+
+No nore words, just code:
+
+```js
+// this is a command in Bunoshfile.js
+// bunosh hello:world
+
+export async function helloWorld(name = 'person') {
+  name = await ask("What's your name?", name);
+  say(`👋 Hello, ${name}!`);
+  const city = await ask('Which city do you live in?')
+  const result = await fetch(`https://wttr.in/${city}?format=3`)
+  say(`Weather in your city ${result.output}`)
+
+  const toCleanup = await ask('Do you want me to cleanup tmp for you?', true);
+
+  if (!toCleanup) {
+    say('Bye, then!');
+    return;
+  }
+
+  await shell`rm -rf ${require('os').tmpdir()}/*`;
+  say('🧹 Cleaned up! Have a great day!');
+}
+````
+
+## Why Choose Bunosh?
+
+| Comparison | 🐚 Bash Scripts | 📦 npm scripts | 🛠️ Task Runners | 🍲 **Bunosh** |
+|------------|-----------------|----------------|------------------------------|----------------|
+| **Syntax** | bash/zsh  | Simple commands | Custom DSL | ✅ JavaScript |
+| **Cross-platform** | No | Yes | Yes | ✅ Yes |
+| **Ecosystem** | CLI tools | npm packages | Plugin dependent | ✅ Bash + npm |
+| **Composability** | Commands | Separate scripts | Task dependencies | ✅ Import any JS code |
+
+## TOC
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Commands](#commands)
+  - [Personal Commands (My Namespace)](#personal-commands-my-namespace)
+- [Tasks](#tasks)
+- [Input/Output](#inputoutput)
+- [Task Control](#task-control)
+- [AI Integration](#ai-integration)
+- [Examples](#examples)
 
 ## Installation
 
 ### Option 1: Single Executable (Recommended)
 
-Download and install the standalone executable - no Node.js or Bun required. Includes built-in upgrade functionality:
+Download the standalone executable - no Node.js or Bun required:
 
 **macOS:**
 ```bash
@@ -40,553 +101,361 @@ sudo mv bunosh-linux-x64 /usr/local/bin/bunosh
 Invoke-WebRequest -Uri "https://github.com/davertmik/bunosh/releases/latest/download/bunosh-windows-x64.exe.zip" -OutFile "bunosh.zip"
 Expand-Archive -Path "bunosh.zip" -DestinationPath .
 Move-Item "bunosh-windows-x64.exe" "bunosh.exe"
-# Add bunosh.exe to your PATH
 ```
 
-### Option 2: Bun Package Manager
+### Option 2: Package Managers
 
 ```bash
+# Using Bun
 bun add -g bunosh
-```
-
-### Option 3: NPM Package
 
-```bash
+# Using npm
 npm install -g bunosh
 ```
 
+## Quickstart
 
+1. **Initialize your Bunoshfile:**
 ```bash
-# Initialize a new Bunoshfile
 bunosh init
-
-# This creates Bunoshfile.js with sample tasks
 ```
 
-### Example: Web Development Tasks
-
-Create a `Bunoshfile.js`:
-
+2. **Write your first command:**
 ```javascript
-// Import Bunosh functions from global object
-const { exec, fetch, writeToFile, say, ask, yell } = global.bunosh;
+// Bunoshfile.js
+const { exec, say } = global.bunosh;
 
 /**
- * Installs project dependencies
+ * Builds the project for production
  */
-export async function install() {
-  await exec`npm install`;
-  say('📦 Dependencies installed!');
+export async function build(env = 'production') {
+  say(`🔨 Building for ${env}...`);
+  await exec`npm run build`.env({ NODE_ENV: env });
+  say('✅ Build complete!');
 }
+```
 
-/**
- * Starts development server
- */
-export async function dev() {
-  say('🚀 Starting development server...');
-  await exec`npm run dev`;
-}
+That's it! Your function is now a CLI command.
 
-/**
- * Builds project for production
- */
-export async function build(target = 'production') {
-  say(`🔨 Building for ${target}...`);
-  await exec`npm run build`;
+3. **Run it:**
+```bash
+# build for production
+bunosh build
 
-  if (target === 'production') {
-    await exec`npm run optimize`;
-    yell('BUILD COMPLETE!');
-  }
-}
+# build for staging
+bunosh build staging
 
-/**
- * Deploys to specified environment
- */
-export async function deploy(env = 'staging', options = { skipTests: false }) {
-  if (!options.skipTests) {
-    say('🧪 Running tests...');
-    await exec`npm test`;
-  }
+# build for development
+bunosh build development
+```
 
-  say(`🚀 Deploying to ${env}...`);
-  await build('production');
-  await exec`docker build -t myapp:${env} .`;
-  await exec`docker push myapp:${env}`;
+## Commands
 
-  yell(`DEPLOYED TO ${env.toUpperCase()}!`);
-}
+### Creating Commands
 
-/**
- * Cleans up temporary files
- */
-export async function clean() {
-  await exec`rm -rf dist node_modules/.cache tmp`;
-  say('✨ All clean!');
-}
+Every exported function in `Bunoshfile.js` becomes a CLI command:
 
-/**
- * Setup new project environment
- */
-export async function setup() {
-  const projectName = await ask('What is your project name?');
-  const useTypescript = await ask('Use TypeScript? (y/n)') === 'y';
-
-  say('🏗️ Setting up project...');
-
-  // Create package.json
-  writeToFile('package.json', (line) => {
-    line`{`;
-    line`  "name": "${projectName}",`;
-    line`  "version": "1.0.0",`;
-    line`  "type": "module"`;
-    if (useTypescript) {
-      line`,  "devDependencies": {`;
-      line`    "typescript": "^5.0.0"`;
-      line`  }`;
-    }
-    line`}`;
-  });
+```javascript
+// Simple command
+export function hello() {
+  console.log('Hello, World!');
+}
 
-  if (useTypescript) {
-    await exec`npm install typescript --save-dev`;
-  }
+// Command with parameters
+export function greet(name = 'friend') {
+  console.log(`Hello, ${name}!`);
+}
 
-  yell('PROJECT READY!');
+// Command with options
+export function deploy(env = 'staging', options = { force: false, verbose: false }) {
+  if (options.verbose) console.log('Verbose mode enabled');
+  console.log(`Deploying to ${env}${options.force ? ' (forced)' : ''}`);
 }
 ```
 
-### Run Your Tasks
-
+**CLI Usage:**
 ```bash
-# List all available commands
-bunosh
-
-# Run individual tasks
-bunosh install
-bunosh dev
-bunosh build
-bunosh build staging
-bunosh deploy production --skip-tests
-bunosh clean
-bunosh setup
+bunosh hello
+bunosh greet John
+bunosh deploy production --force --verbose
 ```
 
-**Bunosh will display your tasks like this:**
+### Arguments and Options
 
-```
-🍲 Your exceptional task runner
+Bunosh automatically maps function parameters to CLI arguments:
 
-Usage: bunosh <command> <args> [options]
+```javascript
+/**
+ * Create a new feature branch
+ * @param {string} name - Feature name (required)
+ * @param {string} base - Base branch (optional, defaults to 'main')
+ * @param {object} options - CLI options
+ * @param {boolean} options.push - Push to remote after creation
+ */
+export async function feature(name, base = 'main', options = { push: false }) {
+  await exec`git checkout -b feature/${name} ${base}`;
 
-  Commands are loaded from exported functions in Bunoshfile.js
+  if (options.push) {
+    await exec`git push -u origin feature/${name}`;
+  }
+}
+```
 
-Commands:
-  build                 Builds project for production
-                          bunosh build [target]
-  clean                 Cleans up temporary files
-  deploy                Deploys to specified environment
-                          bunosh deploy [env] --skip-tests
-  dev                   Starts development server
-  install               Installs project dependencies
-  setup                 Setup new project environment
+**Generated CLI:**
+```bash
+bunosh feature my-feature           # Creates from main
+bunosh feature my-feature develop   # Creates from develop
+bunosh feature my-feature --push    # Creates and pushes
 ```
 
-## Example: DevOps Tasks
+### Command Naming
 
-```javascript
-const { exec, fetch, writeToFile, say, task } = global.bunosh;
+Functions are automatically converted to kebab-case commands:
 
-/**
- * Checks service health across environments
- */
-export async function healthCheck(env = 'production') {
-  const services = ['api', 'web', 'database'];
-
-  for (const service of services) {
-    const url = `https://${service}.${env}.example.com/health`;
-    await task(`Checking ${service}`, async () => {
-      const response = await fetch(url);
-      if (!response.ok) throw new Error(`${service} is down!`);
-    });
-  }
+| Function Name | CLI Command |
+|--------------|-------------|
+| `build` | `bunosh build` |
+| `gitPush` | `bunosh git:push` |
+| `npmInstall` | `bunosh npm:install` |
+| `buildAndDeploy` | `bunosh build:and-deploy` |
 
-  say('✅ All services healthy!');
-}
+### Personal Commands (My Namespace)
 
-/**
- * Backup database with compression
- */
-export async function backup(database = 'main') {
-  const timestamp = new Date().toISOString().split('T')[0];
-  const filename = `backup-${database}-${timestamp}.sql.gz`;
+Bunosh automatically loads commands from your home directory (`~/Bunoshfile.js`) and makes them available in any project with the `my:` namespace prefix.
 
-  await exec`pg_dump ${database} | gzip > ${filename}`;
-  await exec`aws s3 cp ${filename} s3://backups/${filename}`;
-  await exec`rm ${filename}`;
+**Create your personal toolkit:**
 
-  say(`📦 Backup saved: ${filename}`);
-}
+```javascript
+// ~/Bunoshfile.js - Your global commands available everywhere
 
 /**
- * Updates SSL certificates
+ * Quick deployment to personal staging server
  */
-export async function updateCerts() {
-  await exec`certbot renew`;
-  await exec`nginx -s reload`;
-  say('🔒 Certificates updated!');
+export function deploy(app, env = 'staging') {
+  say(`🚀 Deploying ${app} to personal ${env} environment...`);
+  await exec`ssh deploy@myserver.com "deploy.sh ${app} ${env}"`;
+  say('✅ Deployment complete!');
 }
 
 /**
- * Deploys application with health checks
+ * Personal backup script
  */
-export async function deployWithChecks(env = 'staging') {
-  await exec`kubectl apply -f k8s/${env}/`;
-  await exec`kubectl rollout status deployment/myapp`;
-  await healthCheck(env);
-  say(`🚀 Successfully deployed to ${env}!`);
+export function backup(target = 'documents') {
+  say(`💾 Creating backup of ${target}...`);
+  await exec`rsync -av ~/${target}/ ~/Backups/${target}-$(date +%Y%m%d)/`;
+  say('📦 Backup completed!');
 }
 
 /**
- * Scales application instances
+ * Quick project setup
  */
-export async function scale(replicas = 3, service = 'myapp') {
-  await exec`kubectl scale deployment/${service} --replicas=${replicas}`;
-  say(`⚖️ Scaled ${service} to ${replicas} replicas`);
+export function newProject(name, template = 'basic') {
+  say(`🏗️ Creating new project: ${name}`);
+  await exec`git clone https://github.com/my-templates/${template}.git ${name}`;
+  await exec`cd ${name} && npm install`;
+  say(`✅ Project ${name} ready!`);
 }
 ```
 
-**Bunosh displays these as:**
+**Available in any project:**
 
+```bash
+# From any directory, these commands work:
+bunosh my:deploy my-app production
+bunosh my:backup projects
+bunosh my:new-project awesome-app react
+
+# List all your personal commands
+bunosh --help  # Shows "My Commands" section
 ```
-Usage: bunosh <command> <args> [options]
 
-  Commands are loaded from exported functions in Bunoshfile.js
+**Key Features:**
+- 🏠 **Global availability** - Access your personal commands from any project directory
+- 🏷️ **Namespaced** - `my:` prefix prevents conflicts with project commands
+- 📝 **Same syntax** - Uses identical JavaScript function syntax as project commands
+- 🔧 **Parameters & options** - Full support for arguments and CLI options
+- 📚 **Help integration** - Shows in help output with descriptions
+- 🚫 **Graceful fallback** - Works seamlessly when no home Bunoshfile exists
 
-Commands:
-  backup                Backup database with compression
-                          bunosh backup [database]
-  deploy:with-checks    Deploys application with health checks
-                          bunosh deploy:with-checks [env]
-  health:check          Checks service health across environments
-                          bunosh health:check [env]
-  scale                 Scales application instances
-                          bunosh scale [replicas] [service]
-  update:certs          Updates SSL certificates
+## Tasks
 
-```
-
-## Example: Content Management
+Bunosh provides built-in tasks which are available via `global.bunosh`:
 
 ```javascript
-const { exec, writeToFile, ask, say } = global.bunosh;
+const { exec, shell, fetch, writeToFile, copyFile, task } = global.bunosh;
+```
 
-/**
- * Creates new blog post template
- */
-export async function newPost() {
-  const title = await ask('Post title:');
-  const slug = title.toLowerCase().replace(/\s+/g, '-');
-  const date = new Date().toISOString().split('T')[0];
+> We use global variables instead of imports to ensure you can use it with bunosh single-executable on any platform.
 
-  writeToFile(`posts/${date}-${slug}.md`, (line) => {
-    line`---`;
-    line`title: "${title}"`;
-    line`date: ${date}`;
-    line`draft: true`;
-    line`---`;
-    line``;
-    line`# ${title}`;
-    line``;
-    line`Your content here...`;
-  });
 
-  say(`📝 Created: posts/${date}-${slug}.md`);
-}
+* Async tasks: `exec`, `shell`, `fetch`
+* Sync tasks: `writeToFile`, `copyFile`
+* Task wrapper: `task`
 
-/**
- * Optimizes and compresses images
- */
-export async function optimizeImages() {
-  await exec`find ./images -name "*.jpg" -exec jpegoptim --max=80 {} \\;`;
-  await exec`find ./images -name "*.png" -exec optipng -o2 {} \\;`;
-  say('🖼️ Images optimized!');
-}
+Each executed task returns `TaskResult` object which can be analyzed and used in next steps:
 
-/**
- * Creates new page template
- */
-export async function newPage(name) {
-  const slug = name.toLowerCase().replace(/\s+/g, '-');
+```js
+const result = await shell`echo "Hello"`;
+console.log(result.status);    // 'success', 'fail', or 'warning'
+console.log(result.output);    // Command output or result data
+console.log(result.hasFailed); // true if status is 'fail'
+console.log(result.hasSucceeded); // true if status is 'success'
+console.log(result.hasWarning); // true if status is 'warning'
+```
 
-  writeToFile(`content/pages/${slug}.md`, (line) => {
-    line`---`;
-    line`title: "${name}"`;
-    line`type: "page"`;
-    line`---`;
-    line``;
-    line`# ${name}`;
-    line``;
-    line`Page content here...`;
-  });
+Now let's look into other tasks:
 
-  say(`📄 Created: content/pages/${slug}.md`);
-}
+#### `task`
 
-/**
- * Generates site and deploys
- */
-export async function publish() {
-  await exec`hugo --minify`;
-  await exec`rsync -avz public/ user@server:/var/www/site/`;
-  say('🌐 Site published!');
-}
-
-/**
- * Builds and serves development site
- */
-export async function serve(port = 1313) {
-  await exec`hugo server --port ${port} --buildDrafts`;
-}
-```
-
-**Bunosh displays these as:**
+General method that transforms a function into a task. Adds it to tasks registry and prints task information:
 
+```js
+// register operation as a task
+const result = task('Fetch Readme file', () => {
+  const content = fs.readFileSync('README.md', 'utf8');
+  console.log(content);
+  return content;
+});
 ```
-Usage: bunosh <command> <args> [options]
 
-  Commands are loaded from exported functions in Bunoshfile.js
+If a another task is executed inside a task function, its description will be appended to all child tasks.
 
-Commands:
-  new:page              Creates new page template
-                          bunosh new:page <name>
-  new:post              Creates new blog post template
-  optimize:images       Optimizes and compresses images
-  publish               Generates site and deploys
-  serve                 Builds and serves development site
-                          bunosh serve [port]
+#### `exec`
 
-```
+Run single command using [child process `spawn`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options)
 
-## Built-in Functions
+```javascript
+// Complex commands with pipes and streaming output
+await exec`npm install --verbose`;
+await exec`docker build . | tee build.log`;
+await exec`find . -name "*.js" | grep -v node_modules | wc -l`;
 
-All Bunosh functions are available via `global.bunosh`:
+// With environment variables
+await exec`echo $NODE_ENV`.env({ NODE_ENV: 'production' });
 
-```javascript
-const { exec, shell, fetch, writeToFile, copyFile, say, ask, yell, task } = global.bunosh;
+// In specific directory
+await exec`npm install`.cwd('/tmp/project');
 ```
 
-### Shell Execution
+By default task prints live line-by-line output from stdout and stderr. To disable output, use `silent` method:
 
-Bunosh provides two ways to execute shell commands:
-
-#### `exec` - Universal Shell Execution
+```javascript
 
-Best for complex commands, cross-platform compatibility, and when you need real-time streaming output.
+// disable printing output
+await task.silent(() => exec`npm install`);
 
-```javascript
-// Complex shell commands with pipes and redirections
-await exec`find . -name "*.js" | grep -v node_modules | wc -l`;
-await exec`npm install --verbose`;  // Shows progress in real-time
-await exec`docker build . | tee build.log`;
+// disable output for all commands
+await task.silence();
 ```
 
-#### `shell` - Native Bun Shell (with Node.js fallback)
+See more [#silent](#silent)
 
-Best for simple commands when running under Bun for maximum performance.
+#### `shell` - Fast Native Execution
+
+Optimized for simple, fast commands when running under Bun:
 
 ```javascript
 // Simple, fast commands
 await shell`pwd`;
-await shell`echo "Hello World"`;
 await shell`ls -la`;
 await shell`cat package.json`;
 ```
 
-#### When to Use Which?
+For more details see [bun shell](https://bun.sh/docs/runtime/shell) reference
 
-**Use `shell` when:**
-- ✅ Running under Bun for optimal performance  
-- ✅ Executing simple commands (`pwd`, `ls`, `echo`, `cat`)
-- ✅ Want fastest possible execution
-- ✅ Working with basic file operations
+`shell` vs `exec`
 
-**Use `exec` when:**
-- ✅ Need cross-platform compatibility (Node.js + Bun)
-- ✅ Using complex shell features (pipes, redirections, command chaining)
-- ✅ Want real-time streaming output for long-running commands
-- ✅ Running package managers (`npm install`, `docker build`)
+| Command | Best For | Use Cases | Implementation | Compatibility |
+|---------|----------|-----------|----------------|---------------|
+| `exec` | Single command execution | single command | spawn process | NodeJS + Bun but platform dependent |
+| `shell` | Multiple cross-platform shell commands | exec + `pwd`, `ls`, `echo`, `cat`, basic file ops | bun shell | Bun only but Cross-platform |
 
-Both support the same API and return the same `TaskResult` object:
+shell prints output from stdout and stderr. To disable output, [make tasks silent](#silent):
 
-```javascript
-// Both tasks support environment variables  
-await shell`echo $NODE_ENV`.env({ NODE_ENV: 'production' });
-await exec`echo $NODE_ENV`.env({ NODE_ENV: 'production' });
+###$ `fetch`
 
-// Both support working directory changes
-await shell`pwd`.cwd('/tmp');
-await exec`ls -la`.cwd('/tmp');
+`fetch` task wraps fetch:
 
-// Choose based on complexity and performance needs
-await shell`cat package.json`;              // Simple, fast
-await exec`npm install --verbose`;          // Complex, streaming
+```javascript
+/**
+ * Check service health
+ */
+export async function healthCheck(url) {
+  const response = await fetch(url);
+
+  if (response.ok) {
+    const data = await response.json();
+    say(`✅ Service healthy: ${data.status}`);
+  } else {
+    yell(`❌ Service down: ${response.status}`);
+  }
+}
 ```
 
-#### TaskResult Object
+### File Operations
 
-Both `exec` and `shell` return a `TaskResult` object with the following properties and methods:
+Template-based file writing and copying:
 
 ```javascript
-const result = await exec`ls -la`;
-// or 
-const result = await shell`ls -la`;
-
-// Properties
-result.status   // 'success' or 'fail' 
-result.output   // Combined stdout/stderr as string
-
-// Getters (boolean)
-result.hasFailed     // true if command failed (non-zero exit code)
-result.hasSucceeded  // true if command succeeded (exit code 0)
-```
-
-#### Error Handling Examples
+/**
+ * Generate configuration file
+ */
+export function generatePage(name, description = '') {
+  writeToFile('index.mdx', (line) => {
+    line`name": "${name}",`;
+    if (description) {
+      line`description: "${description}"`;
+    }
+    line`---`;
+  });
 
-```javascript
-// Check command success
-const result = await exec`npm test`;
-if (result.hasSucceeded) {
-  say('✅ Tests passed!');
-} else {
-  yell('❌ Tests failed!');
-  console.log(result.output); // Show error details
+  say('📝 Page created');
 }
 
-// Get command output
-const result = await exec`git rev-parse HEAD`;
-if (result.hasSucceeded) {
-  const commitHash = result.output.trim();
-  say(`Current commit: ${commitHash}`);
-}
+// Copy files
+copyFile('template.env', '.env');
+```
 
-// Handle failures gracefully
-const result = await exec`optional-command-that-might-fail`;
-if (result.hasFailed) {
-  say('Command failed, but continuing...');
-  console.log('Error output:', result.output);
-}
 
-// Old vs New style comparison
-// ❌ Old: Commands throw on failure
-try {
-  await someOtherTaskRunner('failing-command');
-} catch (error) {
-  // Handle error
-}
+## Input/Output
 
-// ✅ New: Explicit success/failure handling
-const result = await exec`failing-command`;
-if (result.hasFailed) {
-  // Handle failure explicitly
-}
-```
+### `say` - Normal Output
 
-### HTTP Requests (`fetch`)
-```javascript
-// GET request with progress indicator
-const response = await fetch('https://api.github.com/repos/user/repo');
-const data = await response.json();
-```
+Standard output with visual indicator:
 
-### File Operations
 ```javascript
-// Write file with template builder
-writeToFile('config.json', (line) => {
-  line`{`;
-  line`  "name": "myapp",`;
-  line`  "version": "1.0.0"`;
-  line`}`;
-});
-
-// Copy files
-copyFile('template.js', 'output.js');
+say('Building project...');
+say('📦 Dependencies installed');
+say(`Found ${count} files to process`);
 ```
 
-### User Interaction
+### `ask` - User Input
 
-#### `ask()` - Interactive User Input
-
-The `ask()` function provides flexible ways to get user input with smart parameter detection and multiple modes:
+Flexible user input with smart parameter detection:
 
 ```javascript
-// === SIMPLE SYNTAX WITH SMART DETECTION ===
-
-// Basic text input
-const name = await ask('What is your name?');
-
-// Text input with default value
-const projectName = await ask('Project name:', 'my-awesome-app');
-
-// Boolean confirmation (auto-detects confirm type)
-const shouldContinue = await ask('Continue with deployment?', true);
-const forceUpdate = await ask('Force update?', false);
-
-// Number input with default
-const port = await ask('Enter port number:', 3000);
+// Text input with default
+const name = await ask('Project name:', 'my-app');
 
-// Single choice selection (auto-detects from array)
-const framework = await ask('Choose your framework:', [
-  'React', 'Vue', 'Angular', 'Svelte'
-]);
-
-// Multiple choice selection (array + options)
-const features = await ask('Select features to include:', [
-  'TypeScript', 'ESLint', 'Prettier', 'Tests', 'CI/CD'
-], { multiple: true });
+// Boolean confirmation (auto-detects)
+const proceed = await ask('Continue?', true);
 
-// === ADVANCED OPTIONS SYNTAX ===
+// Single selection (auto-detects from array)
+const env = await ask('Select environment:', ['dev', 'staging', 'prod']);
 
-// Multiline text input (opens system editor)
-const description = await ask('Enter project description:', {
-  multiline: true  // Same as editor: true
-});
-
-// Editor input with default content
-const config = await ask('Edit configuration:', {
-  editor: true,
-  default: 'Initial content here...'
-});
+// Multiple selection
+const features = await ask('Select features:',
+  ['TypeScript', 'ESLint', 'Tests'],
+  { multiple: true }
+);
 
-// Password input (hidden)
-const password = await ask('Enter password:', {
-  type: 'password'
-});
+// Password input
+const password = await ask('Enter password:', { type: 'password' });
 
-// Mixed: default value + additional options
-const email = await ask('Email address:', 'user@example.com', {
-  validate: (input) => input.includes('@') || 'Please enter valid email'
-});
+// Multiline editor input
+const description = await ask('Enter description:', { editor: true });
 ```
 
-#### Ask Function Signatures
-
-```javascript
-// Smart detection syntax
-ask(question, defaultValue, options?)
-ask(question, choices[], options?)  
-ask(question, options)
-
-// Examples:
-ask('Name?', 'John')                    // String default
-ask('Continue?', true)                  // Boolean -> confirm type
-ask('Port?', 3000)                      // Number default  
-ask('Color?', ['red', 'blue'])          // Array -> choices
-ask('Colors?', ['red', 'blue'], { multiple: true })  // Array + options
-```
-
-#### Ask Options Reference
-
 | Parameter/Option | Type | Description | Example |
 |------------------|------|-------------|---------|
 | **Smart Detection** | | |
@@ -601,493 +470,298 @@ ask('Colors?', ['red', 'blue'], { multiple: true })  // Array + options
 | `type` | String | Input type: `'input'`, `'confirm'`, `'password'`, `'number'` | `'password'` |
 | `validate` | Function | Custom validation function | `(input) => input.length > 0` |
 
-#### Advanced Ask Examples
 
-```javascript
-/**
- * Interactive project setup with smart syntax
- */
-export async function setupProject() {
-  // Simple syntax with smart detection
-  const projectName = await ask('Project name:', 'my-awesome-project');
-  
-  const projectType = await ask('Project type:', [
-    'Web App', 'API', 'CLI Tool', 'Library'
-  ]);
-  
-  const dependencies = await ask('Select dependencies:', [
-    'express', 'lodash', 'axios', 'moment', 'uuid'
-  ], { multiple: true });
-  
-  const useTypescript = await ask('Use TypeScript?', false);
-  
-  // Editor input for complex configuration
-  const packageJson = await ask('Customize package.json:', {
-    editor: true,
-    default: JSON.stringify({
-      name: projectName,
-      version: '1.0.0',
-      description: '',
-      dependencies: {}
-    }, null, 2)
-  });
-  
-  say(`Creating ${projectType}: ${projectName}`);
-  say(`Dependencies: ${dependencies.join(', ')}`);
-  say(`TypeScript: ${useTypescript ? 'Yes' : 'No'}`);
-  
-  writeToFile('package.json', packageJson);
-}
+### `yell`
 
-/**
- * Git commit with editor input
- */
-export async function interactiveCommit() {
-  const message = await ask('Enter commit message:', {
-    editor: true,
-    default: 'feat: \n\n# Write your commit message above\n# First line: brief summary (50 chars max)\n# Blank line, then detailed explanation'
-  });
-  
-  await exec`git commit -m "${message}"`;
-  say('✅ Committed successfully!');
-}
+Emphasized Output
 
-/**
- * Database migration with smart syntax
- */
-export async function migrate() {
-  // Smart array detection for choices
-  const action = await ask('Migration action:', [
-    'Run pending migrations', 
-    'Rollback last migration', 
-    'Reset database', 
-    'Create new migration'
-  ]);
-  
-  if (action === 'Reset database') {
-    // Smart boolean detection for confirmation
-    const confirmed = await ask('⚠️  This will DELETE ALL DATA. Are you sure?', false);
-    
-    if (!confirmed) {
-      say('Migration cancelled');
-      return;
-    }
-  }
-  
-  // Execute migration based on selection...
-}
-
-/**
- * Server configuration with mixed smart syntax
- */
-export async function configureServer() {
-  // Simple defaults
-  const serverName = await ask('Server name:', 'my-server');
-  const port = await ask('Port number:', 8080);
-  const enableHTTPS = await ask('Enable HTTPS?', true);
-  
-  // Array with additional options
-  const databases = await ask('Select databases to connect:', [
-    'PostgreSQL', 'MongoDB', 'Redis', 'MySQL'
-  ], { multiple: true });
-  
-  // Mix of default + validation
-  const adminEmail = await ask('Admin email:', 'admin@example.com', {
-    validate: (email) => email.includes('@') || 'Please enter a valid email'
-  });
-  
-  say(`Configuring ${serverName} on port ${port}`);
-  say(`HTTPS: ${enableHTTPS ? 'Enabled' : 'Disabled'}`);
-  say(`Databases: ${databases.join(', ')}`);
-  say(`Admin: ${adminEmail}`);
-}
-```
-
-#### Output Functions
+ASCII art output for important messages:
 
 ```javascript
-// Output messages
-say('Building project...');          // Normal output with !
-yell('BUILD COMPLETE!');             // Emphasized ASCII art output
-
-// Wrap long operations with progress
-await task('Installing dependencies', async () => {
-  await exec`npm install`;
-});
+yell('BUILD COMPLETE!');
+yell('DEPLOYMENT SUCCESSFUL!');
 ```
 
-## 🤖 AI-Powered Tasks
+### `silent`
 
-Bunosh now supports AI integration with structured outputs! Connect to popular AI providers and generate content, analyze data, or automate text processing with simple function calls.
+Stop printing realtime output
 
-### Quick Setup
+```javascript
+// Silence all task output
+task.silence();
+await shell`npm build`;
 
-Set your AI provider credentials:
-```bash
-# Required: Choose your model
-export AI_MODEL=gpt-4o                         # or claude-3-5-sonnet-20241022, llama-3.3-70b-versatile, etc.
+// restore printing output
+task.prints();
 
-# Required: Set API key for your chosen provider
-export OPENAI_API_KEY=your_key_here           # for OpenAI models
-# export ANTHROPIC_API_KEY=your_key_here       # for Claude models
-# export GROQ_API_KEY=your_key_here            # for Groq models
+// Silent specific task
+const labels = await task.silent(() => shell(`gh api repos/:org/:repo/labels`));
 ```
 
-### Built-in AI Providers
-
-- **OpenAI** - GPT-4o, GPT-4o-mini, GPT-3.5-turbo (via `OPENAI_API_KEY`)
-- **Anthropic** - Claude 3.5 Sonnet, Claude 3 Haiku (via `ANTHROPIC_API_KEY`)
-- **Groq** - Llama 3.3, Mixtral, Gemma models (via `GROQ_API_KEY` or `GROQ_KEY`)
+## Task Control
 
-### Custom AI Providers
+### Parallel Executions
 
-For enterprise and custom setups, you can import and register any AI provider manually:
+No magic here. Use `Promise.all()` to run tasks in parallel:
 
 ```javascript
-const { ai } = global.bunosh;
-
-// Method 1: Direct model configuration (most flexible)
-import { bedrock } from '@ai-sdk/amazon-bedrock';
-const bedrockModel = bedrock('anthropic.claude-3-sonnet-20240229-v1:0', {
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'your-access-key',
-    secretAccessKey: 'your-secret-key'
-  }
-});
-
-ai.configure({ model: bedrockModel });
+// Parallel tasks
+const results = await Promise.all([
+  exec`npm run build:frontend`,
+  exec`npm run build:backend`,
+  exec`npm run build:docs`
+]);
+```
 
-// Method 2: Register custom provider with environment variable
-import { xai } from '@ai-sdk/xai';
-ai.configure({
-  registerProvider: {
-    envVar: 'XAI_API_KEY',
-    provider: {
-      createInstance: (modelName) => xai(modelName)
-    }
-  }
-});
+### Custom Tasks
 
-// Method 3: Register any custom provider (Azure OpenAI, OpenRouter, etc.)
-import { openrouter } from '@openrouter/ai-sdk-provider';
-ai.configure({
-  registerProvider: {
-    envVar: 'OPENROUTER_API_KEY', 
-    provider: {
-      createInstance: (modelName) => openrouter(modelName)
-    }
-  }
-});
+Name and group your tasks operations:
 
-// Method 4: Register completely custom provider
-ai.configure({
-  registerProvider: {
-    envVar: 'CUSTOM_AI_API_KEY',
-    provider: {
-      createInstance: (modelName) => {
-        // Your custom provider logic
-        return customAIProvider(modelName, {
-          apiKey: process.env.CUSTOM_AI_API_KEY,
-          endpoint: 'https://custom-ai.company.com/v1'
-        });
-      }
-    }
-  }
+```js
+await task('Build', () => {
+  await exec`npm run build:frontend`);
+  await exec`npm run build:docs`);
 });
+````
 
-// Reset to environment variable configuration
-ai.reset();
+### Stop on Failure
 
-// Check current configuration
-const config = ai.getConfig();
-console.log('Current AI config:', config);
-```
+By default bunosh executes all tasks event if they fail. To stop execution immediately on failure, use the `task.stopOnFailures()` method.
 
-### AI Task Examples
 
 ```javascript
-const { ai, writeToFile, say } = global.bunosh;
-
 /**
- * Generate project documentation with AI
+ * Strict deployment - stop on any failure
  */
-export async function generateDocs() {
-  const codebase = fs.readFileSync('src/index.js', 'utf8');
-  
-  const result = await ai(
-    `Generate documentation for this code: ${codebase}`,
-    {
-      overview: 'Brief project overview',
-      apiReference: 'API documentation',
-      examples: 'Usage examples',
-      installation: 'Installation instructions'
-    }
-  );
-  
-  writeToFile('README.md', (line) => {
-    line`# ${result.overview}`;
-    line``;
-    line`## Installation`;
-    line`${result.installation}`;
-    line``;
-    line`## API Reference`;
-    line`${result.apiReference}`;
-    line``;
-    line`## Examples`;
-    line`${result.examples}`;
-  });
-  
-  say('📚 Documentation generated!');
+export async function deployStrict() {
+  task.stopOnFailures();  // Exit immediately on any task failure
+
+  await exec`npm test`;
+  await exec`npm run build`;
+  await exec`deploy-script`;
+  // If any task fails, script exits immediately
 }
 
 /**
- * Analyze and optimize code with AI suggestions
+ * Cleanup - continue despite failures
  */
-export async function codeReview(filename) {
-  const code = fs.readFileSync(filename, 'utf8');
-  
-  const analysis = await ai(
-    `Review this code for improvements: ${code}`,
-    {
-      issues: 'List of potential issues',
-      suggestions: 'Specific improvement suggestions',  
-      security: 'Security considerations',
-      performance: 'Performance optimization tips',
-      rating: 'Overall code quality rating (1-10)'
-    }
-  );
-  
-  say(`🔍 Code Review for ${filename}:`);
-  console.log(`Rating: ${analysis.rating}/10`);
-  console.log(`Issues: ${analysis.issues}`);
-  console.log(`Suggestions: ${analysis.suggestions}`);
-  console.log(`Security: ${analysis.security}`);
-  console.log(`Performance: ${analysis.performance}`);
+export async function cleanup() {
+  task.ignoreFailures();  // Continue even if tasks fail
+
+  await task('Remove temp files', () => shell`rm -rf tmp/*`);
+  await task('Clear logs', () => shell`rm -f logs/*.log`);
+  await task('Reset cache', () => shell`rm -rf .cache`);
+  // All tasks run regardless of failures
 }
+```
+
+### Try Operations
 
+Gracefully handle operations that might fail:
+
+```javascript
 /**
- * Generate test cases from code
+ * Check service availability
  */
-export async function generateTests(sourceFile) {
-  const code = fs.readFileSync(sourceFile, 'utf8');
-  
-  const tests = await ai(
-    `Generate comprehensive unit tests for this code: ${code}`,
-    {
-      testSuite: 'Complete test suite code',
-      edgeCases: 'List of edge cases covered',
-      mockSetup: 'Required mocks and setup code'
-    }
-  );
-  
-  const testFile = sourceFile.replace('.js', '.test.js');
-  writeToFile(testFile, (line) => {
-    line`${tests.mockSetup}`;
-    line``;
-    line`${tests.testSuite}`;
-  });
-  
-  say(`🧪 Tests generated: ${testFile}`);
-  say(`Edge cases: ${tests.edgeCases}`);
+export async function checkServices() {
+  const dbConnected = await task.try(shell`nc -z localhost 5432`);
+
+  if (dbConnected) {
+    say('✅ Database connected');
+  } else {
+    say('⚠️ Database unavailable, using fallback');
+    await useFallbackDatabase();
+  }
+
+  const apiHealthy = await task.try(() => fetch('http://localhost:3000/health'));
+
+  if (!apiHealthy) {
+    yell('API IS DOWN!');
+  }
 }
+```
+
+## 💫 AI Integration
+
+Built-in AI support for code generation, documentation, and automation.
+Automatically responds to structured JSON output.
+
+AI provider automatically detected, but you need to provide API key and model name.
+Use `.env` file with `AI_MODEL` and `OPENAI_API_KEY` variables.
+In case you use provider other than OpenAI, Anthropic, Groq, you may need to configure it manually in top of Bunoshfile
+
+```bash
+# Choose your AI model
+export AI_MODEL=gpt-5  # or claude-4-sonnet, llama-3.3-70b, etc.
+
+# Set API key for your provider
+export OPENAI_API_KEY=your_key_here      # For OpenAI
+# export ANTHROPIC_API_KEY=your_key_here  # For Claude
+# export GROQ_API_KEY=your_key_here       # For Groq
+```
+
+
+Use the `ai` function to interact with the AI.
+
+```js
+const resp = await ai(message, { field1: 'what should be there', field2: 'what should be there' })
+```
+
+### Usage
+
+```javascript
+const { ai, writeToFile } = global.bunosh;
 
 /**
- * Create commit messages from git diff
+ * Generate commit message from staged changes
  */
-export async function smartCommit() {
+export async function commit() {
   const diff = await exec`git diff --staged`;
-  
-  if (diff.hasFailed || !diff.output.trim()) {
-    say('No staged changes found');
+
+  if (!diff.output.trim()) {
+    say('No staged changes');
     return;
   }
-  
+
   const commit = await ai(
-    `Generate a commit message for these changes: ${diff.output}`,
+    `Generate a conventional commit message for: ${diff.output}`,
     {
-      title: 'Concise commit title (50 chars max)',
-      body: 'Detailed commit body explaining what and why',
-      type: 'Commit type (feat/fix/docs/refactor/test/chore)'
+      type: 'Commit type (feat/fix/docs/chore)',
+      scope: 'Commit scope (optional)',
+      subject: 'Brief subject line (50 chars max)',
+      body: 'Detailed explanation'
     }
   );
-  
-  const message = `${commit.type}: ${commit.title}\n\n${commit.body}`;
-  await exec`git commit -m "${message}"`;
-  
-  say(`✅ Committed with AI-generated message:`);
-  console.log(message);
-}
 
-/**
- * Enterprise AI setup with custom provider
- */
-export async function setupEnterpriseAI() {
-  // Import your enterprise AI provider
-  import { bedrock } from '@ai-sdk/amazon-bedrock';
-  
-  // Configure for enterprise use
-  const enterpriseModel = bedrock('anthropic.claude-3-sonnet-20240229-v1:0', {
-    region: 'us-east-1'
-    // Uses AWS credentials from environment/profile
-  });
-  
-  ai.configure({ model: enterpriseModel });
-  
-  const analysis = await ai(
-    'Analyze our company performance from this quarterly report: [data]',
-    {
-      summary: 'Executive summary of performance',
-      risks: 'Identified business risks',
-      opportunities: 'Growth opportunities',
-      recommendations: 'Strategic recommendations'
-    }
-  );
-  
-  say('📊 Enterprise AI analysis complete');
-  console.log(analysis);
+  const message = commit.scope
+    ? `${commit.type}(${commit.scope}): ${commit.subject}\n\n${commit.body}`
+    : `${commit.type}: ${commit.subject}\n\n${commit.body}`;
+
+  await exec`git commit -m "${message}"`;
+  say('✅ AI-generated commit created');
 }
 ```
 
-### Simple Text Generation
+See more ai usage examples in [docs/examples.md](docs/examples.md)
 
-For quick text generation without structured output:
 
-```javascript
-/**
- * Generate marketing copy
- */
-export async function generateCopy(product) {
-  const copy = await ai(`Write compelling marketing copy for: ${product}`);
-  say('📝 Generated copy:');
-  console.log(copy);
-}
+## Execute JavaScript Code
 
-/**
- * Translate content
- */
-export async function translate(text, language = 'Spanish') {
-  const translation = await ai(`Translate to ${language}: ${text}`);
-  say(`🌐 Translation to ${language}:`);
-  console.log(translation);
-}
-```
+Bunosh supports executing JavaScript code directly using the `-e` flag, allowing for powerful one-liners and integration with shell scripts and CI/CD systems.
 
-### Progressive Enhancement
+### Basic Usage
 
-The AI task features:
-- **🎭 Animated Progress**: Braille spinner animation during generation
-- **📊 Token Tracking**: Shows token usage for cost monitoring  
-- **⚡ Fast Inference**: Optimized for speed with Groq and other providers
-- **🔧 Structured Output**: Get JSON responses with defined schemas
-- **🎯 Provider Auto-Detection**: Automatically detects available API keys
-- **💪 Error Handling**: Graceful handling of API errors and rate limits
+```bash
+# Execute inline JavaScript
+bunosh -e "say('Hello')"
 
-Transform your development workflow with AI-powered automation! Generate documentation, analyze code, create tests, write commit messages, and much more.
+# Execute JavaScript from stdin
+echo "say('Hello')" | bunosh -e
+```
 
-## Command Features
+### Heredoc Syntax
 
-### Automatic CLI Generation
-- `functionName` → `bunosh function:name`
-- Function parameters become command arguments
-- Last object parameter becomes CLI options
-- JSDoc comments become help descriptions
+For multi-line scripts, use heredoc syntax for clean, readable code:
 
-### Smart Argument Handling
-```javascript
-// Function definition
-export function deploy(env = 'staging', options = { force: false, verbose: false }) {
-  // ...
-}
-
-// CLI usage
-bunosh deploy production --force --verbose
+```bash
+bunosh -e << 'EOF'
+say('🚀 Starting build process...')
+await task('Install Dependencies', () => shell`npm ci`)
+await task('Build', () => shell`npm run build`)
+await task('Test', () => shell`npm test`)
+say('✅ All tasks completed successfully!')
+EOF
 ```
 
-### Help and Documentation
+### With Environment Variables and Control Flow
+
 ```bash
-# List all commands
-bunosh
+# Complex script with conditions
+bunosh -e << 'EOF'
+const env = process.env.NODE_ENV || 'development'
+say(`Building for ${env}...`)
+
+if (env === 'production') {
+  await shell`npm run build:prod`
+  await task('Deploy', () => shell`./deploy.sh`)
+} else {
+  await shell`npm run build:dev`
+}
 
-# Get help for specific command
-bunosh deploy --help
+yell('BUILD COMPLETE!')
+EOF
 ```
 
-### Shell Auto-Completion
-Enable tab completion for faster command typing:
+### Error Handling
 
 ```bash
-# 🚀 Auto-setup (recommended) - detects your shell and installs completion
-bunosh setup-completion
-
-# Manual setup if needed
-bunosh completion bash > ~/.bunosh-completion.bash
-echo "source ~/.bunosh-completion.bash" >> ~/.bashrc
-source ~/.bashrc
+# Script with error handling
+bunosh -e << 'EOF'
+task.stopOnFailures()
 
-# Now use tab completion
-bunosh dep<TAB>    # Completes to 'deploy'
-bunosh <TAB><TAB>  # Shows all available commands
+try {
+  await shell`npm test`
+  await shell`npm run build`
+  say('✅ Success!')
+} catch (error) {
+  yell(`❌ Build failed: ${error.message}`)
+  process.exit(1)
+}
+EOF
 ```
 
-**Supported shells:** bash, zsh, fish. The `setup-completion` command automatically detects your shell and handles installation. See [COMPLETION.md](COMPLETION.md) for detailed setup.
+### JavaScript Execution in GitHub Actions
 
-### Staying Up to Date
-
-**Single Executable:**
-```bash
-# Check for updates
-bunosh upgrade --check
+Use JavaScript execution to run Bunosh scripts inside CI/CD workflows without creating separate files:
 
-# Upgrade to latest version
-bunosh upgrade
+```yaml
+- name: Build and Deploy
+  run: |
+    bunosh -e << 'EOF'
+    say('🚀 Starting deployment...')
 
-# Force reinstall current version
-bunosh upgrade --force
-```
+    if (!process.env.NODE_ENV === 'production') return;
 
-**NPM Installation:**
-```bash
-npm update -g bunosh
-```
+    shell`./deploy.sh`
 
-## Advanced Usage
+    const response = await fetch('${{ secrets.DEPLOY_WEBHOOK }}', {
+      method: 'POST',
+      headers: { 'Authorization': 'Bearer ${{ secrets.API_TOKEN }}' }
+    })
 
-### Parallel Task Execution
-```javascript
-const results = await Promise.all([
-  task('Task 1', () => exec`sleep 2 && echo "Done 1"`),
-  task('Task 2', () => exec`sleep 2 && echo "Done 2"`),
-  task('Task 3', () => exec`sleep 2 && echo "Done 3"`)
-]);
+    if (response.ok) {
+      yell('🚀 DEPLOYMENT COMPLETE!')
+    } else {
+      yell('❌ DEPLOYMENT FAILED!')
+      process.exit(1)
+    }
+    EOF
+  env:
+    NODE_ENV: production
 ```
 
-### Error Handling
-```javascript
-export async function deployWithRollback(env) {
-  try {
-    await deploy(env);
-  } catch (error) {
-    say('❌ Deployment failed, rolling back...');
-    await exec`kubectl rollout undo deployment/myapp`;
-    throw error;
-  }
-}
-```
+### Shell Integration
 
-### NPM Scripts Integration
-Bunosh automatically includes your package.json scripts:
 ```bash
-bunosh npm:test    # runs npm run test
-bunosh npm:build   # runs npm run build
+bunosh -e << 'EOF'
+say('Running database migrations...')
+await shell`npm run migrate`
+say('Migrations completed')
+EOF
 ```
 
-## Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Write tests for new functionality
-4. Submit a pull request
+## Examples
+
+For comprehensive examples of Bunosh in action, see [docs/examples.md](docs/examples.md).
+
+This includes:
+- Feature branch workflow with git worktrees
+- AI-powered release note generation
+- Container building and publishing
+- Kubernetes deployment and rollback
+- AWS infrastructure management
+- And more practical examples
 
 ## License
 
@@ -1095,4 +769,4 @@ MIT License - see LICENSE file for details.
 
 ---
 
-Built with ❤️ for modern JavaScript development
+Cooked with ❤️ from Ukraine 🇺🇦