mtc-project-sync-script/CLAUDE.md

Project Sync Toolkit

A bash toolkit for synchronizing projects between remote servers and local development machines.

Overview

The main script sync-project.sh downloads a project from a remote server via tar archive and generates helper scripts for ongoing synchronization. It's designed to be symlinked from a projects directory so multiple projects can share the same toolkit.

Architecture

sync-project.sh          # Main orchestrator - generates all helper scripts
sync-git-project.sh      # Full project setup via git clone (--git mode)
shared.sh                # Shared functions and variables
MANUAL                   # CLI help text (displayed by -h flag)
lazygit                  # Binary uploaded to server for git operations
scripts/                 # Helper script templates
    local-remote.sh      # Push files to server (rsync)
    remote-local.sh      # Pull files from server (rsync)
    ssh.sh               # SSH access with --db, --git, --todo flags
    sftp-watch.sh        # Continuous sync using watchexec
    watch-build.sh       # Build and deploy automation
    split-conflicts.sh   # Git conflict resolution helper
    find_image_size.php  # Image aspect ratio analyzer

How It Works

Default Mode (tar sync)

1. User runs ./sync-project.sh from their projects directory (via symlink)
2. Script prompts for: server, password, path (default ~/public_leo), local folder
3. Creates tar archive on server, downloads and extracts locally
4. Generates helper scripts with embedded credentials (from templates in scripts/)
5. On full sync: syncs terminal info, uploads lazygit, updates .gitignore

Git Mode (--git)

1. User runs ./sync-project.sh --git
2. Script prompts for: server, password, path, local folder
3. Clones repository via git over SSH
4. Performs full project setup (12 steps):
   • Clone repository, check for .npmrc
   • Copy Docker env file (.docker/config/.env.local → .env)
   • Clean Docker volumes (stop/remove containers and volumes)
   • Run docker-setup.sh
   • Copy server .env to .server.env
   • Modify local .env (APP_NAME, APP_KEY from server)
   • Create .env.prod.local with production credentials
   • Add helper scripts (ssh.sh)
   • Upload lazygit to server
   • SSH key management (generate or download staging.key)
   • Add staging.key to SSH agent
   • Database setup (db:wipe + make db-sync)

Modes

• Default: Full setup with all scripts, lazygit, terminfo sync
• --git: Full project setup via git clone with Docker, env, SSH keys, and database
• --sftp-only: Helper scripts only, no lazygit or .gitignore updates
• --files-only: Quick sync, excludes node_modules/vendor, no scripts generated

Key Conventions

• All SSH/SCP commands use $SSH_OPTS for consistent options (currently: auto-accept new hosts)
• Paths starting with ~ are resolved to full paths via SSH before use
• Helper scripts get credentials injected as variables at the top, then template content appended
• Conflict prevention uses .remote-in-progress flag file
• Terminal detection checks $TERM for "ghostty" or "kitty" substrings

Shared Functions (shared.sh)

• pause_for_user <message> - Display message and wait for Enter key
• get_env_value <file> <key> - Extract value from .env file (strips quotes, CRLF)
• set_env_value <file> <key> <value> - Add or update value in .env file
• add_to_gitignore <entry> - Add entry to .gitignore if not present

Generated Script Structure

Each helper script is built by:

1. Writing a header with #!/bin/bash, set -e, and credential variables
2. Appending the corresponding template from scripts/ directory

Testing

• -h flag should display MANUAL and exit
• Path resolution requires valid SSH credentials
• Terminfo sync only runs on full sync (no flags) and requires infocmp
• See verification.md for comprehensive test cases for --git mode