bunosh 0.3.2 → 0.4.1

package/README.md

@@ -5,11 +5,11 @@
 </p>
 
 <p align="center">
-  <strong>ONE TOOL TO SCRIPT THEM ALL</strong>
+  <strong>Your exceptional task runner</strong>
 </p>
 
 <p align="center">
-  Transform JavaScript functions into powerful CLI commands. Write once, run anywhere.
+  Transform JavaScript functions into CLI commands.
 </p>
 
 ---
@@ -23,39 +23,55 @@ Bunosh is a modern task runner that turns your JavaScript functions into CLI com
 ### ✨ Key Features
 
 - **🚀 Zero Configuration** - Write functions, get CLI commands automatically
-- **🎨 pure JavaScript** - write commands as JavaScript functions
+- **🎨 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
 
-## Why Choose Bunosh?
+## Hello World
+
+No nore words, just code:
 
-### Over Bash Scripts
+```js
+// this is a command in Bunoshfile.js
+// bunosh hello:world
 
-- **Readable** syntax if you already know JavaScript (no cryptic bash symbol)
-- **Cross-platform** without compatibility headaches
-- **Rich ecosystem** - use any npm package
+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}`)
 
-### Over npm scripts
+  const toCleanup = await ask('Do you want me to cleanup tmp for you?', true);
 
-- **Real programming** - loops, conditions, async/await
-- **Interactive** - outputs, prompts, confirmations, selections
-- **Composable** - one file for everything! Call functions from other functions
-- **Arguments & options** - full CLI parameter support
+  if (!toCleanup) {
+    say('Bye, then!');
+    return;
+  }
 
-### Over Traditional Task Runners
+  await shell`rm -rf ${require('os').tmpdir()}/*`;
+  say('🧹 Cleaned up! Have a great day!');
+}
+````
+
+## Why Choose Bunosh?
 
-- **No configuration files** - just export functions
-- **No DSL to learn** - it's just JavaScript
-- **Native speed** - runs on Bun or Node.js
-- **Modern DX** - auto-completion, beautiful output
+| 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 |
 
-## Table of Contents
+## TOC
 
 - [Installation](#installation)
 - [Quickstart](#quickstart)
 - [Commands](#commands)
+  - [Personal Commands (My Namespace)](#personal-commands-my-namespace)
 - [Tasks](#tasks)
 - [Input/Output](#inputoutput)
 - [Task Control](#task-control)
@@ -203,17 +219,107 @@ Functions are automatically converted to kebab-case commands:
 | `npmInstall` | `bunosh npm:install` |
 | `buildAndDeploy` | `bunosh build:and-deploy` |
 
+### Personal Commands (My Namespace)
+
+Bunosh automatically loads commands from your home directory (`~/Bunoshfile.js`) and makes them available in any project with the `my:` namespace prefix.
+
+**Create your personal toolkit:**
+
+```javascript
+// ~/Bunoshfile.js - Your global commands available everywhere
+
+/**
+ * Quick deployment to personal staging server
+ */
+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!');
+}
+
+/**
+ * Personal backup script
+ */
+export function backup(target = 'documents') {
+  say(`💾 Creating backup of ${target}...`);
+  await exec`rsync -av ~/${target}/ ~/Backups/${target}-$(date +%Y%m%d)/`;
+  say('📦 Backup completed!');
+}
+
+/**
+ * Quick project setup
+ */
+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!`);
+}
+```
+
+**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
+```
+
+**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
+
 ## Tasks
 
-All Bunosh utilities are available via `global.bunosh`:
+Bunosh provides built-in tasks which are available via `global.bunosh`:
 
 ```javascript
-const { exec, shell, fetch, writeToFile, copyFile, task, ai, say, ask, yell } = global.bunosh;
+const { exec, shell, fetch, writeToFile, copyFile, task } = global.bunosh;
 ```
 
 > We use global variables instead of imports to ensure you can use it with bunosh single-executable on any platform.
 
 
+* Async tasks: `exec`, `shell`, `fetch`
+* Sync tasks: `writeToFile`, `copyFile`
+* Task wrapper: `task`
+
+Each executed task returns `TaskResult` object which can be analyzed and used in next steps:
+
+```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'
+```
+
+Now let's look into other tasks:
+
+#### `task`
+
+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;
+});
+```
+
+If a another task is executed inside a task function, its description will be appended to all child tasks.
+
 #### `exec`
 
 Run single command using [child process `spawn`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options)
@@ -266,9 +372,9 @@ For more details see [bun shell](https://bun.sh/docs/runtime/shell) reference
 
 shell prints output from stdout and stderr. To disable output, [make tasks silent](#silent):
 
-### HTTP Requests
+###$ `fetch`
 
-Built-in fetch with progress indicators:
+`fetch` task wraps fetch:
 
 ```javascript
 /**
@@ -294,22 +400,23 @@ Template-based file writing and copying:
 /**
  * Generate configuration file
  */
-export function generateConfig(name, port = 3000) {
-  writeToFile('config.json', (line) => {
-    line`{`;
-    line`  "name": "${name}",`;
-    line`  "port": ${port},`;
-    line`  "environment": "development"`;
-    line`}`;
+export function generatePage(name, description = '') {
+  writeToFile('index.mdx', (line) => {
+    line`name": "${name}",`;
+    if (description) {
+      line`description: "${description}"`;
+    }
+    line`---`;
   });
 
-  say('📝 Config file created');
+  say('📝 Page created');
 }
 
 // Copy files
 copyFile('template.env', '.env');
 ```
 
+
 ## Input/Output
 
 ### `say` - Normal Output
@@ -466,7 +573,7 @@ export async function checkServices() {
     await useFallbackDatabase();
   }
 
-  const apiHealthy = await task.try(() => fetch('http://localhost:3000/health');
+  const apiHealthy = await task.try(() => fetch('http://localhost:3000/health'));
 
   if (!apiHealthy) {
     yell('API IS DOWN!');
@@ -535,336 +642,126 @@ export async function commit() {
 }
 ```
 
-See more ai usage examples below:
+See more ai usage examples in [docs/examples.md](docs/examples.md)
 
-## Examples
 
-### Development Examples
+## Execute JavaScript Code
 
-#### Feature Branch Workflow
+Bunosh supports executing JavaScript code directly using the `-e` flag, allowing for powerful one-liners and integration with shell scripts and CI/CD systems.
 
-```
-bunosh worktree:create
-bunosh worktree:delete
-```
+### Basic Usage
 
-```javascript
-/**
- * Create worktree for feature development
- */
-export async function worktreeCreate(name = '') {
-  const worktreeName = name || await ask('What is feature name?');
-  const newDir = `../app-${worktreeName}`;
-
-  await exec`git worktree add ${newDir}`;
-  say(`Created worktree for feature ${worktreeName} in ${newDir}`);
-}
-
-/**
- * Remove worktree when feature is merged
- */
-export async function worktreeDelete(worktree = '') {
-  const worktrees = await shell`git worktree list`;
-  const worktreePaths = worktrees.output
-    .split('\n')
-    .map(line => line.split(' ')[0])
-    .filter(path => path !== process.cwd());
-
-  if (worktreePaths.length === 0) {
-    say('No worktrees found');
-    return;
-  }
-
-  const worktreeName = worktree || await ask('Select worktree to delete', worktreePaths);
-  const rmDir = worktreePaths.find(path => path.includes(worktreeName));
-
-  if (!rmDir) {
-    say(`Worktree for feature ${worktreeName} not found`);
-    return;
-  }
+```bash
+# Execute inline JavaScript
+bunosh -e "say('Hello')"
 
-  await exec`git worktree remove ${rmDir} --force`;
-  say(`Deleted worktree for feature ${worktreeName} in ${rmDir}`);
-}
+# Execute JavaScript from stdin
+echo "say('Hello')" | bunosh -e
 ```
 
-#### Generate Release Notes with AI
-
-```javascript
-/**
- * Generate comprehensive release notes using AI
- */
-export async function generateReleaseNotes(fromTag = '', toTag = 'HEAD') {
-  const { ai, writeToFile, exec, say, ask } = global.bunosh;
-
-  // Get version
-  const version = await ask('Release version:', '1.0.0');
-
-  // Get commit history
-  const gitLog = fromTag
-    ? await exec`git log ${fromTag}..${toTag} --pretty=format:"%h %s" --no-merges`
-    : await exec`git log -n 50 --pretty=format:"%h %s" --no-merges`;
-
-  // Get diff statistics
-  const stats = fromTag
-    ? await exec`git diff --stat ${fromTag}..${toTag}`
-    : await exec`git diff --stat HEAD~50..HEAD`;
-
-  // Generate release notes with AI
-  const releaseNotes = await ai(
-    `Generate professional release notes for version ${version} based on these commits and changes:
+### Heredoc Syntax
 
-    Commits:
-    ${gitLog.output}
+For multi-line scripts, use heredoc syntax for clean, readable code:
 
-    Statistics:
-    ${stats.output}
-
-    Group changes logically and write user-friendly descriptions.`,
-    {
-      features: 'New features (bullet points with emoji)',
-      fixes: 'Bug fixes',
-      acknowledgments: 'Contributors and acknowledgments'
-    }
-  );
+```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
+```
 
-  // Write release notes
-  writeToFile(`CHANGELOG.md`, (line) => {
-    line`# Release v${version}`;
-    line`*${new Date().toLocaleDateString()}*`;
-    line``;
-    line`## ✨ New Features`;
-    line`${releaseNotes.features}`;
-    line``;
-    line`## 🐛 Bug Fixes`;
-    line`${releaseNotes.fixes}`;
-    line``;
-    line`## 🙏 Acknowledgments`;
-    line`${releaseNotes.acknowledgments}`;
-
-    // append previous contents
-    line.fromFile('CHANGELOG.md');
-  });
+### With Environment Variables and Control Flow
 
-  say(`📝 Release notes generated for v${version}`);
+```bash
+# 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`
 }
-```
 
-### Analyze Logs with AI
-
-```js
-const fileContents = await shell`tail -n 500 error.log`
-const analysis = await ai(`Analyze this error log ${fileContents.output}`, {
-  severity: "critical/high/medium/low",
-  rootCause: "specific issue identified",
-  solution: "step-by-step fix",
-  preventionTips: "how to avoid this"
-});
+yell('BUILD COMPLETE!')
+EOF
 ```
 
-#### Build and Publish Containers in Parallel
+### Error Handling
 
-```javascript
-/**
- * Build and publish multiple services in parallel
- */
-export async function publishContainers(registry = 'docker.io/myorg') {
-  const { exec, task, say, yell } = global.bunosh;
-
-  const services = ['api', 'web', 'worker', 'admin'];
-  const version = process.env.VERSION || 'latest';
-
-  say(`🐳 Building ${services.length} containers...`);
-
-  task.stopOnFailures();
-  // Build all containers in parallel
-  const buildResults = await Promise.all(
-    services.map(service =>
-      exec`docker build -t ${registry}/${service}:${version} -f ${service}/Dockerfile ${service}`
-    )
-  );
-
-  say('✅ All containers built successfully');
-
-  // Push all containers in parallel
-  say('📤 Publishing to registry...');
-
-  const pushResults = await Promise.all(
-    services.map(service =>
-      exec`docker push ${registry}/${service}:${version}`
-    )
-  );
-
-  yell('CONTAINERS PUBLISHED!');
-  say(`Published: ${pushResults.join(', ')}`);
-  say(`Registry: ${registry}`);
-  say(`Version: ${version}`);
+```bash
+# Script with error handling
+bunosh -e << 'EOF'
+task.stopOnFailures()
+
+try {
+  await shell`npm test`
+  await shell`npm run build`
+  say('✅ Success!')
+} catch (error) {
+  yell(`❌ Build failed: ${error.message}`)
+  process.exit(1)
 }
+EOF
 ```
 
-#### Kubernetes Deployment Control
-
-```javascript
-/**
- * Deploy to Kubernetes with health checks
- */
-export async function kubeDeploy(
-  environment = 'staging',
-  options = { wait: true, replicas: 3 }
-) {
-  const { exec, task, say, yell, ask } = global.bunosh;
-
-  // Confirm production deployments
-  if (environment === 'production') {
-    const confirmed = await ask(
-      `⚠️ Deploy to PRODUCTION?`,
-      false
-    );
-    if (!confirmed) {
-      say('Deployment cancelled');
-      return;
-    }
-  }
-
-  // Set kubectl context
-  await task('Setting context', () =>
-    exec`kubectl config use-context ${environment}`
-  );
-
-  // Apply configurations
-  await task('Applying configurations', () =>
-    exec`kubectl apply -f k8s/${environment}/`
-  );
-
-  // Scale if needed
-  if (options.replicas) {
-    await task(`Scaling to ${options.replicas} replicas`, () =>
-      exec`kubectl scale deployment/app --replicas=${options.replicas}`
-    );
-  }
-
-  // Wait for rollout
-  if (options.wait) {
-    await task('Waiting for rollout', () =>
-      exec`kubectl rollout status deployment/app --timeout=5m`
-    );
-  }
-
-  // Verify deployment
-  const pods = await exec`kubectl get pods -l app=myapp -o json`;
-  const podData = JSON.parse(pods.output);
-  const runningPods = podData.items.filter(
-    pod => pod.status.phase === 'Running'
-  ).length;
+### JavaScript Execution in GitHub Actions
 
-  if (runningPods === options.replicas) {
-    yell('DEPLOYMENT SUCCESSFUL!');
-    say(`✅ ${runningPods} pods running in ${environment}`);
-  } else {
-    yell('DEPLOYMENT ISSUES!');
-    say(`⚠️ Only ${runningPods}/${options.replicas} pods running`);
-  }
-}
+Use JavaScript execution to run Bunosh scripts inside CI/CD workflows without creating separate files:
 
-/**
- * Rollback Kubernetes deployment
- */
-export async function kubeRollback(environment = 'staging') {
-  const { exec, say, ask } = global.bunosh;
+```yaml
+- name: Build and Deploy
+  run: |
+    bunosh -e << 'EOF'
+    say('🚀 Starting deployment...')
 
-  const confirmed = await ask(
-    `Rollback ${environment} deployment?`,
-    false
-  );
+    if (!process.env.NODE_ENV === 'production') return;
 
-  if (!confirmed) {
-    say('Rollback cancelled');
-    return;
-  }
+    shell`./deploy.sh`
 
-  await exec`kubectl config use-context ${environment}`;
-  await exec`kubectl rollout undo deployment/app`;
-  await exec`kubectl rollout status deployment/app`;
+    const response = await fetch('${{ secrets.DEPLOY_WEBHOOK }}', {
+      method: 'POST',
+      headers: { 'Authorization': 'Bearer ${{ secrets.API_TOKEN }}' }
+    })
 
-  say(`✅ Rolled back ${environment} deployment`);
-}
+    if (response.ok) {
+      yell('🚀 DEPLOYMENT COMPLETE!')
+    } else {
+      yell('❌ DEPLOYMENT FAILED!')
+      process.exit(1)
+    }
+    EOF
+  env:
+    NODE_ENV: production
 ```
 
-#### AWS Infrastructure Management
+### Shell Integration
 
-```
-bunosh aws:spawn-server --count 3
+```bash
+bunosh -e << 'EOF'
+say('Running database migrations...')
+await shell`npm run migrate`
+say('Migrations completed')
+EOF
 ```
 
-```javascript
-/**
- * Spawn EC2 instances and configure
- *
- */
-export async function awsSpawnServer(
-  instanceType = 't3.micro',
-  options = { count: 1, region: 'us-east-1' }
-) {
-  const { exec, task, say, writeToFile } = global.bunosh;
-
-  const result = await exec`aws ec2 run-instances \
-      --image-id ami-0c55b159cbfafe1f0 \
-      --instance-type ${instanceType} \
-      --count ${options.count} \
-      --region ${options.region} \
-      --output json`;
-
-  const instanceIds = JSON.parse(result.output).Instances.map(i => i.InstanceId);
-  say(`🚀 Launched instances: ${instanceIds.join(', ')}`);
-
-  exec`aws ec2 wait instance-running --instance-ids ${instanceIds.join(' ')}`
-
-  const details = await exec`aws ec2 describe-instances \
-    --instance-ids ${instanceIds.join(' ')} \
-    --output json`;
-  const instances = JSON.parse(details.output).Reservations[0].Instances;
-
-  writeToFile('instances.json', (line) => {
-    line`${JSON.stringify(instances, null, 2)}`;
-  });
 
-  // Output connection info
-  instances.forEach(instance => {
-    say(`Instance ${instance.InstanceId}:`);
-    say(`  Public IP: ${instance.PublicIpAddress}`);
-    say(`  SSH: ssh -i key.pem ec2-user@${instance.PublicIpAddress}`);
-  });
-
-  return instances;
-}
+## Examples
 
-/**
- * Configure Cloudflare DNS for new servers
- */
-export async function cloudflareSetup(domain, ipAddress) {
-  const { exec, task, say } = global.bunosh;
-
-  const zoneId = process.env.CLOUDFLARE_ZONE_ID;
-  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
-
-  await task('Creating DNS record', async () => {
-    const result = await exec`curl -X POST \
-      "https://api.cloudflare.com/client/v4/zones/${zoneId}/dns_records" \
-      -H "Authorization: Bearer ${apiToken}" \
-      -H "Content-Type: application/json" \
-      --data '{
-        "type": "A",
-        "name": "${domain}",
-        "content": "${ipAddress}",
-        "ttl": 3600
-      }'`;
-
-    return JSON.parse(result.output);
-  });
+For comprehensive examples of Bunosh in action, see [docs/examples.md](docs/examples.md).
 
-  say(`✅ DNS configured: ${domain} → ${ipAddress}`);
-}
-```
+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