npm package: @spatio-labs/spatio
Description: Spatio - Plugin-based spatial computing CLI
Author: Spatio Labs
Latest version: 0.0.1

# Spatio CLI

A plugin-based spatial computing CLI for building custom terminal workspaces.

## Quick Start

```bash
# Install dependencies
npm install

# Start Spatio in current directory
npm run start

# Or build and run
npm run build
./dist/cli.js start
```

## Architecture

Spatio follows the VSCode/Vim plugin model:

- **CLI Binary**: Global `spatio` command
- **Plugin Directory**: `~/.spatio/plugins/` (hidden directory)
- **Registry System**: Dynamic pane type registration
- **Event Bus**: Inter-pane communication
- **Workspaces**: Project-specific configurations

## Plugin Directory Structure

```
~/.spatio/
├── plugins/                    # Installed plugins
│   ├── developer-suite/
│   │   ├── pane.json          # Plugin manifest
│   │   └── index.js           # Plugin code
│   └── trading-tools/
├── config/
│   ├── settings.json          # Global settings
│   └── keybindings.json       # Custom keybindings
└── workspaces/
    └── recent.json            # Recent workspace list
```

## Commands

```bash
# Workspace Management
spatio start                         # Start local workspace (current directory)
spatio start global                  # Start global workspace (multi-directory)
spatio workspace list                # List workspaces
spatio workspace create my-project   # Create workspace

# Plugin Management
spatio plugin list                   # List installed plugins
spatio plugin install developer-suite # Install plugin
spatio plugin create my-plugin       # Create new plugin

# Development
spatio plugin install . --dev        # Install local plugin for development
```

### Workspace Modes

**Local Mode**: `spatio start`
- Workspace tied to current directory
- Perfect for project-specific work
- Filesystem-based organization

**Global Mode**: `spatio start global`
- Work across multiple directories simultaneously
- Spatial organization independent of filesystem
- Perfect for cross-project workflows
- Navigate between different codebases in one workspace

## Core Components

### Registry (`src/core/registry.ts`)
Central registry for all pane types and plugins. Supports:
- Dynamic pane type registration
- Plugin lifecycle management
- Type safety with TypeScript

### Event Bus (`src/core/event-bus.ts`)
Inter-pane communication system with:
- Request/response patterns
- Event history
- Subscription management
- Targeted and broadcast events

### Plugin Loader (`src/core/plugins/enhanced-plugin-loader.ts`)
Advanced plugin system supporting:
- Directory-based plugins
- NPM package plugins
- Permission system
- Hot reloading (development mode)

### Pane Manager (`src/ui/pane-manager.ts`)
Zellij-style pane management with:
- Dynamic layouts
- Focus management
- Keyboard navigation
- Modal dialogs for pane selection

## Plugin Development

### Creating a Plugin

```bash
spatio plugin create my-awesome-plugin
cd my-awesome-plugin
spatio plugin install . --dev
```

### Plugin Manifest (`pane.json`)

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "displayName": "My Awesome Plugin",
  "description": "Does awesome things",
  "author": "Your Name",
  "main": "index.js",
  "categories": ["utilities"],
  "permissions": ["filesystem"],
  "spatioVersion": "^1.0.0"
}
```

### Plugin Code Structure

```javascript
module.exports = {
  name: 'my-plugin',
  version: '1.0.0',
  paneTypes: [{
    type: 'my-pane',
    name: 'My Pane',
    description: 'Custom pane implementation'
  }],
  async init(registry) {
    registry.registerPaneType({
      type: 'my-pane',
      name: 'My Pane',
      description: 'Custom pane implementation',
      constructor: MyPaneClass,
      category: 'utilities'
    });
  }
};
```

## Key Features

- **Zero Built-in Panes**: Clean architecture with no hardcoded pane types
- **Advanced Plugin Architecture**: Enhanced plugin loader with permissions
- **Event Bus**: Full inter-pane communication system
- **Zellij-style UI**: Complete pane manager with focus, resize, navigation
- **Plugin SDK**: TypeScript definitions and development tools
- **~/.spatio Directory**: VSCode/Vim-style plugin management

## Development

The Spatio CLI provides a clean, plugin-based foundation for building spatial computing applications.

### Running in Development

```bash
npm run dev    # Watch mode
npm run build  # Build for production
npm start      # Run built version
```

### Architecture Goals

1. **Plugin Ecosystem**: Like VSCode extensions or Vim plugins
2. **Spatial Computing**: Organize information in 2D workspace
3. **Terminal Native**: Full keyboard navigation, no mouse required
4. **Extensible**: Third-party developers can create pane types
5. **Professional**: Production-ready plugin system and APIs

## Plugin Ecosystem

Plugins are maintained in separate repositories:
- **Core Panes**: `@spatio/core-panes` - Essential pane types (charts, logs, terminal)
- **Developer Tools**: `@spatio/developer-suite` - Git integration, process monitor, file watcher
- **Custom Plugins**: Community-created pane types and tools

Install plugins with:
```bash
spatio plugin install @spatio/core-panes
spatio plugin install @spatio/developer-suite
```