update readme

Author: lalalune

README.md

@@ -1,230 +1,230 @@
-# ElizaOS Plugin
+# ElizaOS Shell Plugin
 
-This is an ElizaOS plugin built with the official plugin starter template.
+A powerful shell execution plugin for ElizaOS that provides agents with a virtual shell environment. This plugin enables agents to execute shell commands, navigate directories, and maintain command history across conversations.
 
-## Getting Started
+## Features
 
-```bash
-# Create a new plugin (automatically adds "plugin-" prefix)
-elizaos create -t plugin solana
-# This creates: plugin-solana
-# Dependencies are automatically installed and built
+- **Persistent Shell State**: Maintains working directory and environment across command executions
+- **Natural Language Support**: Agents can describe commands in natural language (e.g., "list all files in the current directory")
+- **Command History**: Tracks all executed commands and their outputs for context
+- **File Operation Tracking**: Monitors file creations, modifications, and deletions
+- **Security Features**: Audit trails and safe command execution
+- **Smart Wildcard Handling**: Automatically quotes wildcards for find and grep commands
 
-# Navigate to the plugin directory
-cd plugin-solana
+## Installation
 
-# Start development immediately
-elizaos dev
+```bash
+npm install @elizaos/plugin-shell
 ```
 
-## Development
+## Usage
 
-```bash
-# Start development with hot-reloading (recommended)
-elizaos dev
+Add the plugin to your ElizaOS agent configuration:
 
-# OR start without hot-reloading
-elizaos start
-# Note: When using 'start', you need to rebuild after changes:
-# bun run build
+```typescript
+import { shellPlugin } from '@elizaos/plugin-shell';
 
-# Test the plugin
-elizaos test
+const agent = new Agent({
+  plugins: [shellPlugin],
+  // ... other configuration
+});
 ```
 
-## Testing
+## Actions
 
-ElizaOS provides a comprehensive testing structure for plugins:
+### runShellCommand
 
-### Test Structure
-
-- **Component Tests** (`__tests__/` directory):
-
-  - **Unit Tests**: Test individual functions/classes in isolation
-  - **Integration Tests**: Test how components work together
-  - Run with: `elizaos test component`
+Executes shell commands with persistent state management.
 
-- **End-to-End Tests** (`e2e/` directory):
+**Examples:**
+```typescript
+// Direct command
+"Run the command: ls -la"
 
-  - Test the plugin within a full ElizaOS runtime
-  - Run with: `elizaos test e2e`
+// Natural language
+"Show me all TypeScript files in the src directory"
+"Create a new directory called 'test-output'"
+"Check what's in the package.json file"
+```
 
-- **Running All Tests**:
-  - `elizaos test` runs both component and e2e tests
+**Features:**
+- Maintains working directory between commands
+- Supports pipes, redirects, and command chaining
+- Handles wildcards intelligently
+- Tracks file operations
 
-### Writing Tests
+### clearShellHistory
 
-Component tests use Vitest:
+Clears the command history for the current conversation.
 
+**Example:**
 ```typescript
-// Unit test example (__tests__/plugin.test.ts)
-describe('Plugin Configuration', () => {
-  it('should have correct plugin metadata', () => {
-    expect(starterPlugin.name).toBe('plugin-starter');
-  });
-});
-
-// Integration test example (__tests__/integration.test.ts)
-describe('Integration: HelloWorld Action with StarterService', () => {
-  it('should handle HelloWorld action with StarterService', async () => {
-    // Test interactions between components
-  });
-});
+"Clear the shell history"
 ```
 
-E2E tests use ElizaOS test interface:
+### killAutonomous
 
-```typescript
-// E2E test example (e2e/starter-plugin.test.ts)
-export class StarterPluginTestSuite implements TestSuite {
-  name = 'plugin_starter_test_suite';
-  tests = [
-    {
-      name: 'example_test',
-      fn: async (runtime) => {
-        // Test plugin in a real runtime
-      },
-    },
-  ];
-}
+Stops any long-running or background processes.
 
-export default new StarterPluginTestSuite();
+**Example:**
+```typescript
+"Stop the autonomous process"
 ```
 
-The test utilities in `__tests__/test-utils.ts` provide mock objects and setup functions to simplify writing tests.
+## Configuration
 
-## Publishing & Continuous Development
+The plugin works out of the box with no required configuration. Optional settings can be provided:
 
-### Initial Setup
+```typescript
+const shellPlugin = {
+  name: "shell",
+  description: "Shell command execution with state management",
+  services: [new ShellService()],
+  actions: [runShellCommandAction, clearShellHistoryAction, killAutonomousAction],
+  providers: [shellProvider],
+};
+```
 
-Before publishing your plugin, ensure you meet these requirements:
+## Shell Service
 
-1. **npm Authentication**
+The `ShellService` class provides the core functionality:
 
-   ```bash
-   npm login
-   ```
+- **Persistent Working Directory**: Each conversation maintains its own working directory
+- **Command Execution**: Safe execution with proper error handling
+- **History Management**: Tracks commands, outputs, and file operations
+- **State Persistence**: Maintains shell state across agent interactions
 
-2. **GitHub Repository**
+## Security Considerations
 
-   - Create a public GitHub repository for this plugin
-   - Add the 'elizaos-plugins' topic to the repository
-   - Use 'main' as the default branch
+- Commands are executed with the permissions of the ElizaOS process
+- All commands are logged in the audit trail
+- Special characters are properly escaped
+- Consider running ElizaOS in a sandboxed environment for production use
 
-3. **Required Assets**
-   - Add images to the `images/` directory:
-     - `logo.jpg` (400x400px square, <500KB)
-     - `banner.jpg` (1280x640px, <1MB)
+## Development
 
-### Initial Publishing
+### Building
 
 ```bash
-# Test your plugin meets all requirements
-elizaos publish --test
-
-# Publish to npm + GitHub + registry (recommended)
-elizaos publish
+npm run build
 ```
 
-This command will:
+### Testing
 
-- Publish your plugin to npm for easy installation
-- Create/update your GitHub repository
-- Submit your plugin to the ElizaOS registry for discoverability
+The plugin includes comprehensive test coverage:
 
-### Continuous Development & Updates
+```bash
+# Run all tests
+npm test
 
-**Important**: After your initial publish with `elizaos publish`, all future updates should be done using standard npm and git workflows, not the ElizaOS CLI.
+# Run unit tests only
+npm run test:unit
 
-#### Standard Update Workflow
+# Run E2E tests only
+npm run test:e2e
 
-1. **Make Changes**
+# Run tests in watch mode
+npm run test:watch
+```
 
-   ```bash
-   # Edit your plugin code
-   elizaos dev  # Test locally with hot-reload
-   ```
+### Test Structure
 
-2. **Test Your Changes**
+- **Unit Tests** (`src/tests/shell.test.ts`): Test individual components in isolation
+- **E2E Tests** (`src/tests/e2e/`): Test real shell interactions
+  - `shell-basic.ts`: Basic command execution
+  - `shell-stateful.ts`: State persistence and directory navigation
+  - `shell-advanced.ts`: Complex commands and workflows
+  - `shell-security.ts`: Security and edge cases
 
-   ```bash
-   # Run all tests
-   elizaos test
+## Examples
 
-   # Run specific test types if needed
-   elizaos test component  # Component tests only
-   elizaos test e2e       # E2E tests only
-   ```
+### Basic File Operations
+```typescript
+// List files
+"Show me what files are in this directory"
 
-3. **Update Version**
+// Create a file
+"Create a file called README.md with the content 'Hello World'"
 
-   ```bash
-   # Patch version (bug fixes): 1.0.0 → 1.0.1
-   npm version patch
+// Read a file
+"What's in the config.json file?"
 
-   # Minor version (new features): 1.0.1 → 1.1.0
-   npm version minor
+// Delete a file
+"Remove the temporary.txt file"
+```
 
-   # Major version (breaking changes): 1.1.0 → 2.0.0
-   npm version major
-   ```
+### Directory Navigation
+```typescript
+// Change directory
+"Go to the src directory"
 
-4. **Publish to npm**
+// Check current location
+"Where am I?"
 
-   ```bash
-   npm publish
-   ```
+// Create and navigate
+"Create a new folder called 'output' and go into it"
+```
 
-5. **Push to GitHub**
-   ```bash
-   git push origin main
-   git push --tags  # Push version tags
-   ```
+### Complex Operations
+```typescript
+// Find files
+"Find all JavaScript files in the project"
 
-#### Why Use Standard Workflows?
+// Search content
+"Search for 'TODO' in all TypeScript files"
 
-- **npm publish**: Directly updates your package on npm registry
-- **git push**: Updates your GitHub repository with latest code
-- **Automatic registry updates**: The ElizaOS registry automatically syncs with npm, so no manual registry updates needed
-- **Standard tooling**: Uses familiar npm/git commands that work with all development tools
+// Pipe commands
+"Count how many TypeScript files are in the src directory"
+```
 
-### Alternative Publishing Options (Initial Only)
+## API Reference
 
-```bash
-# Publish to npm only (skip GitHub and registry)
-elizaos publish --npm
+### ShellService
 
-# Publish but skip registry submission
-elizaos publish --skip-registry
-
-# Generate registry files locally without publishing
-elizaos publish --dry-run
+```typescript
+class ShellService {
+  async executeCommand(command: string, workingDir?: string): Promise<ShellCommandResult>
+  async getCommandHistory(conversationId?: string): Promise<CommandHistoryEntry[]>
+  async clearCommandHistory(conversationId?: string): Promise<void>
+  getCurrentWorkingDirectory(conversationId?: string): string
+}
 ```
 
-## Configuration
+### Types
+
+```typescript
+interface ShellCommandResult {
+  output: string;
+  error: string | null;
+  exitCode: number;
+  executedCommand: string;
+  workingDirectory: string;
+}
 
-The `agentConfig` section in `package.json` defines the parameters your plugin requires:
-
-```json
-"agentConfig": {
-  "pluginType": "elizaos:plugin:1.0.0",
-  "pluginParameters": {
-    "API_KEY": {
-      "type": "string",
-      "description": "API key for the service"
-    }
-  }
+interface CommandHistoryEntry {
+  command: string;
+  output: string;
+  error: string | null;
+  exitCode: number;
+  timestamp: Date;
+  workingDirectory: string;
+  fileOperations?: FileOperation[];
 }
 ```
 
-Customize this section to match your plugin's requirements.
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass (`npm test`)
+2. Code follows the existing style
+3. New features include tests
+4. Documentation is updated
+
+## License
 
-## Documentation
+MIT
 
-Provide clear documentation about:
+## Support
 
-- What your plugin does
-- How to use it
-- Required API keys or credentials
-- Example usage
-- Version history and changelog
+For issues and feature requests, please use the GitHub issue tracker.