Spatio CLI

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

Quick Start

# 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

# 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

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

Plugin Manifest (pane.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

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

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:

spatio plugin install @spatio/core-panes
spatio plugin install @spatio/developer-suite