npm package: @openpets/excel
Description: Comprehensive Excel file management plugin for reading, writing, and manipulating Excel workbooks, sheets, and cell data
Latest version: 1.0.1

# Excel File Manager Plugin

A comprehensive Excel file management plugin for OpenCode that provides functionality for reading, writing, and manipulating Excel workbooks, sheets, and cell data.

## Features

- **File Management**: List, create, and delete Excel files
- **Data Operations**: Read and write CSV data (placeholder for full Excel functionality)
- **Cell Operations**: Get and update specific cell values
- **Sheet Management**: List sheets in workbooks
- **Connection Testing**: Verify plugin setup and permissions

## Quick Start

### 1. Setup

```bash
cd pets/excel
npm install
```

### 2. Configure Environment

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

Optional: Set custom data directory:

```env
EXCEL_DATA_DIR=./my-excel-files
```

### 3. Test the Plugin

```bash
# Test connection
opencode run "test excel connection"

# List files
opencode run "list excel files"

# Create sample data
opencode run "create sample excel file with headers Name,Age,City"
```

## Available Commands

### Connection & Setup
- `test excel connection` - Test plugin functionality and file system access

### File Operations
- `list excel files` - List all Excel/CSV files in the data directory
- `create sample excel file` - Create a sample CSV file with test data
- `read excel file [filename]` - Read data from a CSV file
- `delete excel file [filename]` - Delete an Excel or CSV file

### Data Operations
- `get cell value from [filename] sheet [sheetname] cell [address]` - Get specific cell value
- `update cell in [filename] sheet [sheetname] cell [address] with value [value]` - Update cell value

## Usage Examples

### Basic Workflow

```bash
# Test the plugin
opencode run "test excel connection"

# Create a sample file
opencode run "create sample excel file with filename employees and headers Name,Age,Department"

# Read the file
opencode run "read excel file employees.csv"

# List all files
opencode run "list excel files"
```

### Data Manipulation

```bash
# Create a file with custom data
opencode run "create sample excel file with filename sales and headers Product,Price,Quantity and rows [['Laptop',999,10],['Mouse',29,50]]"

# Read specific data
opencode run "read excel file sales.csv"

# Clean up
opencode run "delete excel file sales.csv"
```

## File Structure

```
excel/
├── data/              # Default directory for Excel files
│   ├── test-data.csv  # Sample data file
│   └── *.xlsx         # Your Excel files
├── index.ts           # Main plugin implementation
├── package.json       # Plugin configuration
├── opencode.json      # OpenCode loader config
├── .env.example       # Environment variables template
└── README.md          # This documentation
```

## Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `EXCEL_DATA_DIR` | Directory path for storing Excel files | `./data` | No |

## Data Format

### CSV Files
The plugin currently works with CSV files as a placeholder for full Excel functionality. Each CSV file should have:

- Headers in the first row
- Data rows in subsequent rows
- Comma-separated values

### Sample Data Structure

```csv
Name,Age,City,Occupation
John Doe,30,New York,Developer
Jane Smith,25,Los Angeles,Designer
```

## Current Limitations

- **CSV Only**: Currently supports CSV files instead of full Excel (.xlsx) functionality
- **Basic Operations**: Limited to file-level operations and simple CSV parsing
- **No Formulas**: Does not support Excel formulas or advanced features

## Future Enhancements

The plugin is designed to be easily upgraded to full Excel functionality:

1. **Excel Library Integration**: Add `xlsx` library for true Excel file support
2. **Advanced Cell Operations**: Support for formulas, formatting, and ranges
3. **Multiple Sheet Support**: Full workbook and sheet management
4. **Data Validation**: Cell validation and data type enforcement
5. **Chart Operations**: Create and manipulate charts
6. **Template Support**: Work with Excel templates

## Development

### Adding New Tools

1. Add tool definition to `index.ts` in the `tools` array
2. Follow the naming convention: `excel-[action]-[resource]`
3. Use proper Zod schema validation
4. Return JSON responses with consistent format

### Example Tool Structure

```typescript
{
  name: "excel-my-tool",
  description: "What this tool does",
  schema: z.object({
    param: z.string().describe("Parameter description")
  }),
  async execute(args) {
    try {
      // Your logic here
      return JSON.stringify({
        success: true,
        data: result
      }, null, 2)
    } catch (error: any) {
      return JSON.stringify({
        success: false,
        error: error.message
      }, null, 2)
    }
  }
}
```

## Error Handling

All tools return consistent error responses:

```json
{
  "success": false,
  "error": "Error message",
  "details": { "additional": "context" }
}
```

## Testing

```bash
# Run all tests
npm run test:all

# Test connection
npm run test:connection

# Test file reading
npm run test:read
```

## Troubleshooting

### Common Issues

1. **File Not Found**: Check that the file exists in the data directory
2. **Permission Denied**: Ensure the plugin has read/write access to the data directory
3. **Invalid Format**: Verify CSV files are properly formatted with headers

### Debug Mode

Enable debug logging by setting the log level in your environment:

```bash
export LOG_LEVEL=debug
opencode run "test excel connection"
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your enhancements
4. Test thoroughly
5. Submit a pull request

## License

MIT License - see the main OpenPets repository for details.