bunosh 0.4.0 → 0.4.6

package/README.md

@@ -20,15 +20,6 @@ Bunosh is a modern task runner that turns your JavaScript functions into CLI com
 
 > *Named after **banosh**, a traditional Ukrainian dish from cornmeal cooked with various ingredients*
 
-### ✨ 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
 
@@ -66,16 +57,24 @@ export async function helloWorld(name = 'person') {
 | **Ecosystem** | CLI tools | npm packages | Plugin dependent | ✅ Bash + npm |
 | **Composability** | Commands | Separate scripts | Task dependencies | ✅ Import any JS code |
 
+** Migrate to Bunosh**
+
+- [Migrating from Bash Scripts](docs/bash-migration-guide.md)
+- [Migrating from Node.js Scripts](docs/nodejs-migration-guide.md)
+
+Hint: Provide this link to a coding agent and make it convert scripts into Bunosh! 
+
 ## TOC
 
 - [Installation](#installation)
+- [MCP Integration](#mcp-integration)
 - [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)
+- [MCP](#mcp)
 - [Examples](#examples)
 
 ## Installation
@@ -135,21 +134,33 @@ export async function build(env = 'production') {
 }
 ```
 
-That's it! Your function is now a CLI command.
+## Commands
+
+By default, Bunosh loads commands from `Bunoshfile.js` in the current directory.
+
+```
+# reads Bunoshfile form cwd and runs hello()
+bunosh hello
+```
+
+You can specify custom configuration file using CLI option:
 
-3. **Run it:**
 ```bash
-# build for production
-bunosh build
+# Load commands from a different file
+bunosh --bunoshfile Bunoshfile.dev.js hello
+```
+
+or via environment variable:
 
-# build for staging
-bunosh build staging
+```bash
+# Set default bunoshfile for session
+export BUNOSHFILE=Bunoshfile.dev.js
+bunosh hello  # Uses Bunoshfile.dev.js
 
-# build for development
-bunosh build development
+# One-time usage
+BUNOSHFILE=Bunoshfile.prod.js bunosh deploy
 ```
 
-## Commands
 
 ### Creating Commands
 
@@ -219,63 +230,208 @@ 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:**
 
+### Project Namespaces
+
+Organize your project tasks by creating multiple Bunoshfiles with namespaces. This helps keep large projects organized and separates concerns.
+
+**Create namespace files:**
+```bash
+# Main tasks (no namespace)
+Bunoshfile.js
+
+# Development tasks
+Bunoshfile.dev.js
+
+# API tasks
+Bunoshfile.api.js
+
+# Database tasks
+Bunoshfile.db.js
+```
+
+**Example structure:**
 ```javascript
-// ~/Bunoshfile.js - Your global commands available everywhere
+// Bunoshfile.js - Core project tasks
+export function build() {
+  console.log('Building project...');
+}
 
-/**
- * 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!');
+export function test() {
+  console.log('Running tests...');
 }
 
-/**
- * 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!');
+// Bunoshfile.dev.js - Development tasks
+export function start() {
+  console.log('Starting dev server...');
 }
 
-/**
- * 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!`);
+export function debug() {
+  console.log('Debugging...');
+}
+
+// Bunoshfile.api.js - API specific tasks
+export function deploy() {
+  console.log('Deploying API...');
+}
+
+export function test() {
+  console.log('Running API tests...');
 }
 ```
 
-**Available in any project:**
+**Usage:**
+```bash
+# Core tasks (no namespace)
+bunosh build
+bunosh test
+
+# Namespaced tasks
+bunosh dev:start
+bunosh dev:debug
+bunosh api:deploy
+bunosh api:test
+```
+
+## MCP
 
+Bunosh supports the **Model Context Protocol (MCP)**, allowing you to expose your Bunoshfile commands as tools for AI assistants like Claude Desktop, Cursor, and other MCP-compatible applications.
+
+### Quick Start
+
+1. **Start MCP server** in your project directory:
 ```bash
-# From any directory, these commands work:
-bunosh my:deploy my-app production
-bunosh my:backup projects
-bunosh my:new-project awesome-app react
+# Uses Bunoshfile.js from current directory
+bunosh -mcp
+
+# Or with custom Bunoshfile
+bunosh --bunoshfile Bunoshfile.dev.js -mcp
+```
+
+2. **Configure your AI assistant** to use Bunosh as an MCP server (see instructions below).
 
-# List all your personal commands
-bunosh --help  # Shows "My Commands" section
+<details>
+<summary>Claude Desktop Setup</summary>
+
+1. **Edit Claude Desktop configuration** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "bunosh": {
+      "command": "bunosh",
+      "args": ["-mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+2. **Restart Claude Desktop** - your Bunosh commands will now be available as tools.
+
+3. **Use your commands** in Claude:
+   - "Build my project with bunosh"
+   - "Run tests using bunosh"
+   - "Deploy to staging with bunosh"
+
+**Multiple Projects:**
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "bunosh",
+      "args": ["-mcp"],
+      "cwd": "/path/to/my-app"
+    },
+    "my-api": {
+      "command": "bunosh",
+      "args": ["-mcp"],
+      "cwd": "/path/to/my-api"
+    }
+  }
+}
 ```
 
-**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
+</details>
+
+<details>
+<summary>Cursor Setup</summary>
+
+1. **Open Cursor settings** (`Cmd/Ctrl + ,`)
+
+2. **Navigate to** `Extensions` → `MCP Servers`
+
+3. **Add new MCP server:**
+   - **Name**: `bunosh`
+   - **Command**: `bunosh`
+   - **Arguments**: `-mcp`
+   - **Working Directory**: `/path/to/your/project`
+
+4. **Save and restart** Cursor
+
+5. **Your Bunosh commands** will now appear in the AI chat sidebar as available tools.
+
+</details>
+
+<details>
+<summary>Cline Setup (VS Code Extension)</summary>
+
+1. **Install Cline** extension from VS Code marketplace
+
+2. **Open Cline settings** (click the gear icon in Cline panel)
+
+3. **Add MCP server** under "MCP Servers" section:
+   ```json
+   {
+     "name": "bunosh",
+     "command": "bunosh",
+     "args": ["-mcp"],
+     "cwd": "/path/to/your/project"
+   }
+   ```
+
+4. **Save and reload** the VS Code window
+
+5. **Your commands** will be available in Cline's tool selection
+
+</details>
+
+<details>
+
+#### Best Practices for MCP
+
+### Command Design for AI
+
+Design your commands to work well with AI assistants:
+
+* Add comments to all commands
+* Describe use cases for each Command
+* Describe each param using JSDoc style comments
+* Include types when describing parameters
+
+```javascript
+/**
+ * Builds the project for specified environment
+ * @param {string} environment - Target environment: 'development', 'staging', or 'production'
+ * @param {Object} options - Build options
+ * @param {boolean} options.verbose - Enable verbose logging
+ * @param {boolean} options.analyze - Run bundle analysis after build
+ */
+export async function build(environment = 'development', options = {}) {
+  const config = getBuildConfig(environment);
+  if (options.verbose) say(`🔨 Building for ${environment}...`);
+
+  await exec`npm run build:${environment}`;
+
+  if (options.analyze) {
+    await exec`npm run analyze`;
+  }
+
+  say('✅ Build complete!');
+}
+```
 
 ## Tasks
 
@@ -301,6 +457,9 @@ 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'
+
+// Get structured JSON data from any task (async method)
+const json = await result.json();
 ```
 
 Now let's look into other tasks:
@@ -335,6 +494,11 @@ await exec`echo $NODE_ENV`.env({ NODE_ENV: 'production' });
 
 // In specific directory
 await exec`npm install`.cwd('/tmp/project');
+
+// Get structured output with stdout, stderr, exit code and lines
+const result = await exec`git status --porcelain`;
+const data = await result.json();
+// Returns: { stdout: "...", stderr: "...", exitCode: 0, lines: [...] }
 ```
 
 By default task prints live line-by-line output from stdout and stderr. To disable output, use `silent` method:
@@ -359,6 +523,11 @@ Optimized for simple, fast commands when running under Bun:
 await shell`pwd`;
 await shell`ls -la`;
 await shell`cat package.json`;
+
+// Get structured output with stdout, stderr, exit code and lines
+const result = await shell`ls -la`;
+const data = await result.json();
+// Returns: { stdout: "...", stderr: "...", exitCode: 0, lines: [...] }
 ```
 
 For more details see [bun shell](https://bun.sh/docs/runtime/shell) reference
@@ -390,6 +559,11 @@ export async function healthCheck(url) {
     yell(`❌ Service down: ${response.status}`);
   }
 }
+
+// Get JSON response data directly
+const apiResponse = await fetch('https://api.example.com/data');
+const jsonData = await apiResponse.json();
+// Calls response.json() method internally
 ```
 
 ### File Operations
@@ -623,7 +797,7 @@ export async function commit() {
     return;
   }
 
-  const commit = await ai(
+  const response = await ai(
     `Generate a conventional commit message for: ${diff.output}`,
     {
       type: 'Commit type (feat/fix/docs/chore)',
@@ -633,6 +807,8 @@ export async function commit() {
     }
   );
 
+  const commit = await response.json();
+
   const message = commit.scope
     ? `${commit.type}(${commit.scope}): ${commit.subject}\n\n${commit.body}`
     : `${commit.type}: ${commit.subject}\n\n${commit.body}`;