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

cd pets/excel
npm install

2. Configure Environment

Copy .env.example to .env and configure:

cp .env.example .env

Optional: Set custom data directory:

EXCEL_DATA_DIR=./my-excel-files

3. Test the Plugin

# 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

# 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

# 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

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

{
  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:

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

Testing

# 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:

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.