Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (66 loc) · 2.72 KB

AGENTS.md

File metadata and controls

84 lines (66 loc) · 2.72 KB

VPS Sync — Agent Notes

What: Bash-based sync system between WSL and VPS with git/rsync hybrid. Entry: ~/.vps-sync/sync.sh

Architecture (Post-Refactor)

~/.vps-sync/
├── sync.sh              # Main entrypoint, thin orchestration
├── config.conf          # VPS_HOST, VPS_USER, VPS_PASS, paths
├── lib/
│   ├── remote.sh        # RemoteExecutor + SyncStrategy abstractions
│   └── deploy_db.py     # Standalone Python DB module
├── helpers/
│   └── deploy.sh        # Thin wrapper → deploy_db.py
└── exclude.txt          # Rsync exclusions (NOTE: .git/ NOT excluded)

Key Modules:

  • lib/remote.sh — Centralized SSH/rsync transport. Interface: remote_exec(), sync_push(), sync_pull(), strategy_push(), strategy_pull()
  • lib/deploy_db.py — SQLite management for deployment metadata. Testable standalone.

Critical Conventions

Authentication Flow:

  • Scripts check VPS_PASS env var. If set → use sshpass, else → plain SSH.
  • lib/remote.sh hides this complexity from callers.

Sync Strategy (Git vs Rsync):

  • strategy_push/pull auto-detect git repos and use appropriate method.
  • do_rsync() in sync.sh consolidates all rsync calls (was duplicated 8+ places).

Deploy Subcommands:

# CORRECT: separate subcommands
~/.vps-sync/sync.sh deploy nginx <project>
~/.vps-sync/sync.sh deploy systemd <project>

# INCORRECT: old behavior (called both)
~/.vps-sync/sync.sh deploy <project>

Common Tasks

Test a single function:

# Source the lib, test in isolation
source ~/.vps-sync/config.conf
source ~/.vps-sync/lib/remote.sh
remote_exec "ls -la"

Check syntax:

bash -n ~/.vps-sync/sync.sh
bash -n ~/.vps-sync/lib/remote.sh
python3 -m py_compile ~/.vps-sync/lib/deploy_db.py

Verify after changes:

# Dry run - check connection first
~/.vps-sync/sync.sh status

# Test push/pull for one project
~/.vps-sync/sync.sh push my-project

Gotchas

  • .git/ in exclude.txt: Intentionally commented out — repos sync whole .git/ directories.
  • Logging: Unified log_msg() in sync.sh with 5 legacy wrappers for compatibility. info() doesn't write to log file.
  • Deploy DB: Auto-initializes schema. deploy_db.py is the source of truth, not the bash wrapper.
  • Git Identity: Required for --auto commits. Set globally or commits fail silently in some contexts.

Config Reference

Key vars in config.conf:

  • VPS_HOST, VPS_PORT, VPS_USER, VPS_PASS — connection
  • LOCAL_PROJECTS — usually ~/projects
  • VPS_PROJECTS — usually /home/dev
  • DOTFILES_DIRS — synced with dotfiles push/pull
  • SSH_OPTS — -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null