From 71f0006dea1642f340ab13518d04c3e2eaa8fd13 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Thu, 5 Feb 2026 19:31:30 +0000 Subject: [PATCH] Initial upload with CI/CD workflow --- README.md | 228 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 226 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7a06434..dac33de 100644 --- a/README.md +++ b/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. \ No newline at end of file +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 Layout name + -t, --terminal Terminal type (tmux, screen, iterm2) + -s, --session Session name to capture + -f, --format Output format (json, yaml) + -d, --description Layout description + --tags Tags (comma-separated) +``` + +#### Restore +```bash +terminal-layout-sync restore [name] [options] + +Options: + -s, --session 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 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 -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 ` 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.