Initial upload with CI/CD workflow

README.md

@@ -1,3 +1,227 @@
-# terminal-layout-sync
+# Terminal Layout Sync CLI
 
-A CLI tool for saving, restoring, and syncing terminal workspace layouts across machines. Captures tmux/screen/iTerm2 configurations.
+A CLI tool for developers to save, restore, and sync terminal workspace layouts across machines. Captures tmux/screen/iTerm2 configurations and enables easy recreation or cloud sync via dotfiles.
+
+## Overview
+
+Terminal Layout Sync helps you:
+- **Save** your current terminal workspace layout to a config file
+- **Restore** saved layouts to new or existing terminal sessions
+- **Import/Export** layouts as portable JSON files
+- **Sync** layouts between machines via git/dotfiles
+- **Templates** - use predefined layouts for common development scenarios
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/terminal-layout-sync.git
+cd terminal-layout-sync
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Install globally (optional)
+npm install -g .
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Save current terminal layout
+terminal-layout-sync save
+
+# Restore a saved layout
+terminal-layout-sync restore my-layout
+
+# List all saved layouts
+terminal-layout-sync list
+
+# Export a layout to a file
+terminal-layout-sync export my-layout -o my-layout.json
+
+# Import a layout from a file
+terminal-layout-sync import my-layout.json
+```
+
+### Command Options
+
+#### Save
+```bash
+terminal-layout-sync save [options]
+
+Options:
+  -n, --name <name>         Layout name
+  -t, --terminal <type>     Terminal type (tmux, screen, iterm2)
+  -s, --session <name>      Session name to capture
+  -f, --format <format>     Output format (json, yaml)
+  -d, --description <desc>  Layout description
+  --tags <tags>             Tags (comma-separated)
+```
+
+#### Restore
+```bash
+terminal-layout-sync restore [name] [options]
+
+Options:
+  -s, --session <name>   Session name to restore to
+  -a, --attach           Show attach command after restore
+  --dry-run              Show commands without executing
+```
+
+#### List
+```bash
+terminal-layout-sync list [options]
+
+Options:
+  -f, --format <format>   Output format (table, json)
+  -v, --verbose           Show verbose output
+```
+
+#### Import/Export
+```bash
+# Export a layout
+terminal-layout-sync export [name] -o output.json
+
+# Import a layout
+terminal-layout-sync import <file> -n new-name
+```
+
+#### Sync with Git
+```bash
+# Initialize git repo for layouts
+terminal-layout-sync sync --init --remote https://github.com/user/layouts.git
+
+# Push changes
+terminal-layout-sync sync --push
+
+# Pull changes
+terminal-layout-sync sync --pull
+```
+
+#### Templates
+```bash
+# List available templates
+terminal-layout-sync template --list
+
+# Apply a template with variables
+terminal-layout-sync template --apply dev --var PROJECT_DIR=/path/to/project
+
+# Create a template from a saved layout
+terminal-layout-sync template --create
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TERMINAL_LAYOUT_DIR` | Directory to store layouts | `~/.config/terminal-layouts` |
+| `TERMINAL_LAYOUT_DEFAULT_FORMAT` | Default format for layout files | `json` |
+| `GIT_SYNC_ENABLED` | Enable git sync feature | `true` |
+
+### Configuration File
+
+Located at `~/.config/terminal-layouts/config.json`:
+
+```json
+{
+  "layoutDir": "~/.config/terminal-layouts/layouts",
+  "defaultFormat": "json",
+  "gitSyncEnabled": true,
+  "templatesDir": "~/.config/terminal-layouts/templates"
+}
+```
+
+## Templates
+
+Built-in templates are included for common scenarios:
+
+### Development (dev)
+Standard development environment with editor and terminals.
+
+Variables:
+- `PROJECT_DIR` - Project root directory
+- `EDITOR` - Default editor command
+
+### Debug (debug)
+Layout for debugging applications with multiple terminal panes.
+
+Variables:
+- `PROJECT_DIR` - Project root directory
+- `SERVER_URL` - Debug server URL
+- `LOG_LEVEL` - Logging level
+
+### Production (prod)
+Production environment monitoring and management layout.
+
+Variables:
+- `ENVIRONMENT` - Production environment name
+- `SERVER_HOST` - Server hostname
+- `SSH_USER` - SSH username
+
+## Examples
+
+### Save and Restore Workflow
+```bash
+# In your current tmux session
+terminal-layout-sync save --name my-dev-setup --description "My daily development setup"
+
+# On another machine or new terminal
+terminal-layout-sync restore my-dev-setup
+```
+
+### Cross-Machine Sync
+```bash
+# On machine A
+terminal-layout-sync sync --init --remote git@github.com:user/terminal-layouts.git
+terminal-layout-sync sync --push
+
+# On machine B
+git clone git@github.com:user/terminal-layouts.git ~/.config/terminal-layouts/layouts
+terminal-layout-sync list
+```
+
+### Using Templates
+```bash
+# Apply development template
+terminal-layout-sync template --apply dev --var PROJECT_DIR=/home/user/projects/myapp
+
+# The layout is saved and ready to restore
+terminal-layout-sync restore dev-instance
+```
+
+## Supported Terminals
+
+- **tmux** - Full support on Linux and macOS
+- **screen** - Full support on Linux
+- **iTerm2** - macOS only with AppleScript support
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| No tmux/screen session found | Start a new session or specify session name |
+| Layout file corrupted | Validate JSON syntax, use backup file |
+| Permission denied accessing layouts directory | Check directory permissions, create if missing |
+| Git sync failed (no remote configured) | Run `git remote add origin <url>` first |
+| Template not found | Check template name spelling, list available templates |
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `npm test`
+5. Run linting: `npm run lint`
+6. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.