# bashrs WASM Runtime - Usage Guide

Complete guide for using the bashrs WASM bash runtime in your browser or Node.js applications.

## Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Supported Features](#supported-features)
- [Limitations](#limitations)
- [Performance](#performance)
- [Troubleshooting](#troubleshooting)

---

## Quick Start

### Browser (ES Modules)

```html
<!DOCTYPE html>
<html>
<head>
    <title>bashrs WASM Demo</title>
</head>
<body>
    <script type="module">
        import init, { execute_script } from './pkg/bashrs.js';

        // Initialize WASM
        await init();

        // Execute bash script
        const result = execute_script(`
            echo "Hello from WASM!"
            name="World"
            echo "Hello, $name"
        `);

        console.log('Output:', result.stdout);
        console.log('Exit code:', result.exit_code);
    </script>
</body>
</html>
```

### Node.js

```javascript
import init, { execute_script } from './pkg/bashrs.js';

async function main() {
    // Initialize WASM
    await init();

    // Execute bash script
    const result = execute_script(`
        echo "Running in Node.js!"
        cd /tmp
        pwd
    `);

    console.log(result.stdout);
}

main();
```

---

## Installation

### Option 1: Build from Source

```bash
# Clone repository
git clone https://github.com/paiml/bashrs.git
cd bashrs/rash

# Build WASM
wasm-pack build --target web --no-default-features --features wasm

# Copy to your project
cp -r pkg /path/to/your/project/
```

### Option 2: Use Pre-built Package

```bash
# Download from releases (when available)
wget https://github.com/paiml/bashrs/releases/download/vX.X.X/bashrs-wasm.tar.gz
tar -xzf bashrs-wasm.tar.gz
```

### Option 3: CDN (Future)

```html
<script type="module">
    import init, { execute_script } from 'https://cdn.example.com/bashrs/pkg/bashrs.js';
    await init();
</script>
```

---

## API Reference

### Functions

#### `execute_script(source: string): ExecutionResult`

Executes a bash script in the WASM runtime.

**Parameters:**
- `source` (string): Bash script source code

**Returns:** `ExecutionResult` object with:
- `stdout` (string): Standard output
- `stderr` (string): Standard error
- `exit_code` (number): Exit code (0 = success)

**Example:**
```javascript
const result = execute_script('echo "Hello"');
console.log(result.stdout);  // "Hello\n"
console.log(result.exit_code);  // 0
```

#### `version(): string`

Returns the bashrs version.

**Example:**
```javascript
const ver = version();
console.log(ver);  // "6.2.0"
```

### Types

#### `ExecutionResult`

```typescript
interface ExecutionResult {
    stdout: string;      // Captured stdout
    stderr: string;      // Captured stderr
    exit_code: number;   // Exit code (0 = success)

    // Methods
    to_json(): string;   // Get result as JSON
}
```

---

## Examples

### Example 1: Simple Echo

```javascript
const result = execute_script('echo "Hello, WASM!"');
console.log(result.stdout);  // Output: Hello, WASM!
```

### Example 2: Variable Assignment and Expansion

```javascript
const script = `
name="Claude"
version="1.0"
echo "Welcome to $name v$version"
`;

const result = execute_script(script);
console.log(result.stdout);  // Output: Welcome to Claude v1.0
```

### Example 3: Directory Navigation

```javascript
const script = `
pwd
cd /tmp
pwd
cd /home
pwd
`;

const result = execute_script(script);
console.log(result.stdout);
// Output:
// /
// /tmp
// /home
```

### Example 4: Multi-line Scripts

```javascript
const script = `
echo "Step 1: Initialize"
name="deployment"
echo "Step 2: Deploy $name"
cd /tmp
echo "Step 3: Verify location"
pwd
echo "Step 4: Complete"
`;

const result = execute_script(script);
console.log(result.stdout);
```

### Example 5: Error Handling

```javascript
try {
    const result = execute_script('unknowncommand');
    console.log('Output:', result.stdout);
} catch (error) {
    console.error('Execution failed:', error);
}
```

### Example 6: Complex Script

```javascript
const deployScript = `
# Deployment script
APP_NAME="myapp"
VERSION="1.0.0"
RELEASE="release-$VERSION"

echo "Deploying $APP_NAME v$VERSION"

# Navigate to releases directory
cd /tmp
echo "Current directory: $(pwd)"

echo "Deployment complete!"
`;

const result = execute_script(deployScript);
if (result.exit_code === 0) {
    console.log('✅ Deployment successful');
    console.log(result.stdout);
} else {
    console.error('❌ Deployment failed');
    console.error(result.stderr);
}
```

### Example 7: Interactive Web App

```html
<!DOCTYPE html>
<html>
<head>
    <title>Bash Script Executor</title>
</head>
<body>
    <h1>Execute Bash in Your Browser</h1>
    <textarea id="script" rows="10" cols="60">
echo "Hello from WASM!"
name="User"
echo "Welcome, $name"
    </textarea>
    <button onclick="runScript()">Execute</button>
    <pre id="output"></pre>

    <script type="module">
        import init, { execute_script } from './pkg/bashrs.js';

        await init();

        window.runScript = function() {
            const script = document.getElementById('script').value;
            try {
                const result = execute_script(script);
                document.getElementById('output').textContent = result.stdout;
            } catch (e) {
                document.getElementById('output').textContent = 'Error: ' + e;
            }
        };
    </script>
</body>
</html>
```

---

## Supported Features

### ✅ Built-in Commands

- **`echo`** - Print text to stdout
  ```bash
  echo "Hello"
  echo hello world
  echo $variable
  ```

- **`cd`** - Change directory
  ```bash
  cd /tmp
  cd /home
  cd ..  # Parent directory
  cd .   # Current directory
  ```

- **`pwd`** - Print working directory
  ```bash
  pwd
  ```

### ✅ Variables

- **Assignment**
  ```bash
  name="value"
  count="123"
  ```

- **Expansion**
  ```bash
  echo $name
  echo $count
  ```

- **Undefined Variables**
  ```bash
  echo $undefined  # Expands to empty string
  ```

### ✅ Comments

```bash
# This is a comment
echo "visible"  # Inline comment
```

### ✅ Multi-line Scripts

```bash
echo "Line 1"
echo "Line 2"
echo "Line 3"
```

### ✅ Virtual Filesystem

- Standard Unix directories: `/`, `/tmp`, `/home`
- Directory creation: `mkdir`
- Directory navigation: `cd`, `pwd`
- Path resolution: `.`, `..`, absolute/relative paths

---

## Limitations

### ❌ Not Yet Supported

- **Pipes**: `cmd1 | cmd2`
- **Redirects**: `>`, `>>`, `<`, `2>`
- **Command substitution**: `$(cmd)`, `` `cmd` ``
- **Loops**: `for`, `while`, `until`
- **Conditionals**: `if`, `case`
- **Functions**: `function name() { }`
- **Arrays**: `array=(a b c)`
- **Arithmetic**: `$((1 + 2))`
- **External commands**: `ls`, `cat`, `grep`, etc.

### ⚠️ Differences from Real Bash

1. **No process spawning** - All execution is in-process
2. **Virtual filesystem** - No access to real filesystem
3. **Limited builtins** - Only `echo`, `cd`, `pwd`
4. **No subshells** - Everything runs in same context
5. **No job control** - No background jobs, `&`, `fg`, `bg`

---

## Performance

### Benchmarks

| Operation | Time | Notes |
|-----------|------|-------|
| WASM load | <5s | One-time initialization |
| Simple echo | <1ms | Minimal overhead |
| Variable expansion | <2ms | String manipulation |
| Complex script (20 lines) | <10ms | Includes cd, pwd, variables |

### Optimization Tips

1. **Load WASM once** - Cache the initialized module
2. **Reuse executor** - Don't reinitialize for each script
3. **Minimize script length** - Smaller scripts = faster execution
4. **Avoid unnecessary work** - Remove debug echo statements

### Memory Usage

- **WASM binary size**: ~1.0 MB
- **Runtime memory**: <10 MB per execution
- **Overhead**: Minimal (<1 MB)

---

## Troubleshooting

### Problem: "Failed to load WASM"

**Solution:**
- Ensure correct MIME type: `application/wasm`
- Check server CORS headers
- Verify file path is correct

**Example (using ruchy):**
```bash
ruchy serve --port 8000
```

### Problem: "Unknown command: xyz"

**Solution:**
- Only `echo`, `cd`, `pwd` are supported
- Check for typos in command names
- Verify command is a builtin

### Problem: "Not a directory: /path"

**Solution:**
- Directory must exist in virtual filesystem
- Create with `mkdir` first
- Standard dirs: `/`, `/tmp`, `/home`

### Problem: Variable not expanding

**Solution:**
- Check variable assignment syntax: `name="value"`
- Use `$variable` for expansion
- Undefined variables expand to empty string

### Problem: Slow WASM load

**Solution:**
- WASM loads once per page
- Cache the initialized module
- Use CDN for faster delivery
- Consider lazy loading

---

## Advanced Usage

### Catching Errors

```javascript
try {
    const result = execute_script('cd /nonexistent');
} catch (error) {
    console.error('Script failed:', error.message);
}
```

### Checking Exit Codes

```javascript
const result = execute_script('echo "test"');
if (result.exit_code === 0) {
    console.log('Success:', result.stdout);
} else {
    console.error('Failed with code:', result.exit_code);
}
```

### Performance Monitoring

```javascript
const start = performance.now();
const result = execute_script('echo "benchmark"');
const duration = performance.now() - start;
console.log(`Execution took ${duration.toFixed(2)}ms`);
```

### JSON Output

```javascript
const result = execute_script('echo "test"');
const json = result.to_json();
console.log(json);
// {"stdout":"test\n","stderr":"","exit_code":0}
```

---

## Integration Examples

### React

```jsx
import { useState, useEffect } from 'react';
import init, { execute_script } from './pkg/bashrs.js';

function BashExecutor() {
    const [wasmReady, setWasmReady] = useState(false);
    const [output, setOutput] = useState('');

    useEffect(() => {
        init().then(() => setWasmReady(true));
    }, []);

    const runScript = (script) => {
        if (!wasmReady) return;
        const result = execute_script(script);
        setOutput(result.stdout);
    };

    return (
        <div>
            <button onClick={() => runScript('echo "Hello from React!"')}>
                Execute
            </button>
            <pre>{output}</pre>
        </div>
    );
}
```

### Vue

```vue
<template>
    <div>
        <button @click="runScript">Execute</button>
        <pre>{{ output }}</pre>
    </div>
</template>

<script>
import init, { execute_script } from './pkg/bashrs.js';

export default {
    data() {
        return {
            wasmReady: false,
            output: ''
        };
    },
    async mounted() {
        await init();
        this.wasmReady = true;
    },
    methods: {
        runScript() {
            const result = execute_script('echo "Hello from Vue!"');
            this.output = result.stdout;
        }
    }
};
</script>
```

---

## Contributing

Found a bug or want a feature? Check out:
- [GitHub Issues](https://github.com/paiml/bashrs/issues)
- [WASM Roadmap](./WASM-RUNTIME-ROADMAP.md)

---

## License

MIT License

---

**🤖 Generated with [Claude Code](https://claude.com/claude-code)**
**Co-Authored-By: Claude <noreply@anthropic.com>**
