bunosh 0.2.3 → 0.3.1

package/README.md

@@ -373,23 +373,123 @@ Commands:
 All Bunosh functions are available via `global.bunosh`:
 
 ```javascript
-const { exec, fetch, writeToFile, copyFile, say, ask, yell, task } = global.bunosh;
+const { exec, shell, fetch, writeToFile, copyFile, say, ask, yell, task } = global.bunosh;
 ```
 
-### Shell Execution (`exec`)
+### Shell Execution
+
+Bunosh provides two ways to execute shell commands:
+
+#### `exec` - Universal Shell Execution
+
+Best for complex commands, cross-platform compatibility, and when you need real-time streaming output.
+
 ```javascript
-// Simple commands
-await exec`echo "Hello World"`;
-await exec`npm install`;
+// 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`;
+```
+
+#### `shell` - Native Bun Shell (with Node.js fallback)
+
+Best for simple commands when running under Bun for maximum performance.
+
+```javascript
+// Simple, fast commands
+await shell`pwd`;
+await shell`echo "Hello World"`;
+await shell`ls -la`;
+await shell`cat package.json`;
+```
 
-// With environment variables
+#### When to Use Which?
+
+**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
+
+**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`)
+
+Both support the same API and return the same `TaskResult` object:
+
+```javascript
+// Both tasks support environment variables  
+await shell`echo $NODE_ENV`.env({ NODE_ENV: 'production' });
 await exec`echo $NODE_ENV`.env({ NODE_ENV: 'production' });
 
-// With working directory
+// Both support working directory changes
+await shell`pwd`.cwd('/tmp');
 await exec`ls -la`.cwd('/tmp');
 
-// Complex shell commands
-await exec`find . -name "*.js" | grep -v node_modules | wc -l`;
+// Choose based on complexity and performance needs
+await shell`cat package.json`;              // Simple, fast
+await exec`npm install --verbose`;          // Complex, streaming
+```
+
+#### TaskResult Object
+
+Both `exec` and `shell` return a `TaskResult` object with the following properties and methods:
+
+```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
+
+```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
+}
+
+// Get command output
+const result = await exec`git rev-parse HEAD`;
+if (result.hasSucceeded) {
+  const commitHash = result.output.trim();
+  say(`Current commit: ${commitHash}`);
+}
+
+// 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
+}
+
+// ✅ New: Explicit success/failure handling
+const result = await exec`failing-command`;
+if (result.hasFailed) {
+  // Handle failure explicitly
+}
 ```
 
 ### HTTP Requests (`fetch`)
@@ -414,20 +514,477 @@ copyFile('template.js', 'output.js');
 ```
 
 ### User Interaction
+
+#### `ask()` - Interactive User Input
+
+The `ask()` function provides flexible ways to get user input with smart parameter detection and multiple modes:
+
 ```javascript
-// Get user input
+// === 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);
+
+// 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 });
+
+// === ADVANCED OPTIONS SYNTAX ===
+
+// 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...'
+});
+
+// Password input (hidden)
+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'
+});
+```
+
+#### 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** | | |
+| `defaultValue` | String/Number | Sets default value for text/number input | `'John'`, `3000` |
+| `defaultValue` | Boolean | Auto-detects as confirmation prompt | `true`, `false` |
+| `choices` | Array | Auto-detects as selection list | `['A', 'B', 'C']` |
+| **Options Object** | | |
+| `multiple` | Boolean | Enables multiple selections (requires `choices`) | `true` |
+| `multiline` | Boolean | Opens system editor for multi-line input | `true` |
+| `editor` | Boolean | Opens system editor for multi-line input (same as `multiline`) | `true` |
+| `default` | Any | Default value or content (when using options object) | `'default value'` |
+| `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);
+}
+
+/**
+ * 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!');
+}
+
+/**
+ * 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
+
+```javascript
 // Output messages
-say('Building project...');          // Normal output
-yell('BUILD COMPLETE!');             // Emphasized output
+say('Building project...');          // Normal output with !
+yell('BUILD COMPLETE!');             // Emphasized ASCII art output
 
-// Wrap long operations
+// Wrap long operations with progress
 await task('Installing dependencies', async () => {
   await exec`npm install`;
 });
 ```
 
+## 🤖 AI-Powered Tasks
+
+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.
+
+### Quick Setup
+
+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.
+
+# 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
+```
+
+### 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`)
+
+### Custom AI Providers
+
+For enterprise and custom setups, you can import and register any AI provider manually:
+
+```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 });
+
+// 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)
+    }
+  }
+});
+
+// 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)
+    }
+  }
+});
+
+// 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'
+        });
+      }
+    }
+  }
+});
+
+// Reset to environment variable configuration
+ai.reset();
+
+// Check current configuration
+const config = ai.getConfig();
+console.log('Current AI config:', config);
+```
+
+### AI Task Examples
+
+```javascript
+const { ai, writeToFile, say } = global.bunosh;
+
+/**
+ * Generate project documentation with AI
+ */
+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!');
+}
+
+/**
+ * Analyze and optimize code with AI suggestions
+ */
+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}`);
+}
+
+/**
+ * Generate test cases from code
+ */
+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}`);
+}
+
+/**
+ * Create commit messages from git diff
+ */
+export async function smartCommit() {
+  const diff = await exec`git diff --staged`;
+  
+  if (diff.hasFailed || !diff.output.trim()) {
+    say('No staged changes found');
+    return;
+  }
+  
+  const commit = await ai(
+    `Generate a commit message for these changes: ${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)'
+    }
+  );
+  
+  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);
+}
+```
+
+### Simple Text Generation
+
+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);
+}
+
+/**
+ * Translate content
+ */
+export async function translate(text, language = 'Spanish') {
+  const translation = await ai(`Translate to ${language}: ${text}`);
+  say(`🌐 Translation to ${language}:`);
+  console.log(translation);
+}
+```
+
+### Progressive Enhancement
+
+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
+
+Transform your development workflow with AI-powered automation! Generate documentation, analyze code, create tests, write commit messages, and much more.
+
 ## Command Features
 
 ### Automatic CLI Generation