Project Vault (pv) 🏦

The Unified Project Lifecycle Manager: Backup, Restore, and Teleport Projects Anywhere.

Project Vault (pv) is your command-line companion for managing project state. It combines the power of atomic backups, cloud synchronization, and time-travel restoration into a single, unified tool. Think of it as Time Machine for your dev projects — portable, reproducible, and cloud-ready.

⚡ Quick Start (The "5-Minute Rule")

Prerequisites

• Python 3.10+
• Pip (Python Package Installer)
• Docker (Optional, for database backups)

Installation

# Clone the repository
git clone https://github.com/dhruv13x/project-vault.git
cd project-vault

# Install in editable mode with development tools
pip install -e .[dev]

Run

Verify the installation:

pv --version

Demo

Create a snapshot of your current project and list it:

# 1. Initialize (optional, for auto-ignore)
pv init --smart

# 2. Create a local snapshot
pv vault . --name "initial-commit"

# 3. List snapshots
pv list

✨ Features

🛡️ Core Reliability

• Atomic Snapshots: Never lose data due to a partial backup. Snapshots are verified and immutable.
• Content Addressable Storage (CAS): Deduplication at the file level. Save space by storing unique files only once.
• Symlink Support: Preserves symlinks (or optionally follows them), ensuring complex project structures remain intact.

🚀 Performance

• ZStandard Compression: High-speed, high-ratio compression for efficient storage and transfer.
• Incremental Backups: Only changed files are processed, making subsequent backups lightning fast.

☁️ Cloud & Security

• Cloud Sync (S3/B2): Push and pull your vaults to any S3-compatible storage.
• Encrypted Configuration: Securely handle credentials (optional integration).
• Integrity Checks: Verify the health of your local vault and cloud storage.

🧩 Developer Experience

• TUI (Textual UI): Browse snapshots and restore files using an interactive terminal interface (pv browse).
• Smart Ignorance: Auto-generates .pvignore based on project type (Python, Node, Rust, etc.).
• Rich Output: Beautiful, color-coded terminal output using rich.

🛠️ Configuration

Project Vault can be configured via environment variables, a local pv.toml, or pyproject.toml.

Environment Variables

CLI Arguments

Common arguments for pv vault (create snapshot):

Common arguments for pv list:

🏗️ Architecture

Project Vault is a self-contained monorepo orchestrating specialized internal engines for backup and restore.

Directory Tree

project-vault/
├── src/                        # Source Code
│   ├── cli.py                  # Entry Point (pv)
│   ├── cli_dispatch.py         # Command Routing
│   ├── common/                 # Shared Utilities (Config, Crypto, S3/B2)
│   ├── projectclone/           # Backup Engine (Snapshot Creation)
│   ├── projectrestore/         # Restore Engine (Snapshot Application)
│   ├── projectvault/           # Database & Driver Logic
│   └── tui.py                  # Textual User Interface
└── tests/                      # Orchestration & Integration Tests

Data Flow

1. Input: User runs pv vault in a project directory.
2. Filter: Rules from .pvignore are applied.
3. Capture: The internal Clone Engine scans files, computes hashes, and stores unique objects in the CAS (Content Addressable Storage).
4. Manifest: A JSON manifest is created, linking file paths to CAS objects.
5. Sync (Optional): pv push uploads new CAS objects and the manifest to Cloud Storage (S3/B2).
6. Restore: pv vault-restore uses the Restore Engine to read the manifest, fetch objects from CAS, and reconstruct the directory state.

🐞 Troubleshooting

Common Issues

Debug Mode

To enable verbose logging and see stack traces, you can run the CLI module directly:

# Run with python directly for detailed tracebacks
python3 src/cli.py [command]

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started, report bugs, or suggest features.

Dev Setup

1. Clone & Install:

   git clone https://github.com/dhruv13x/project-vault
   cd project-vault
   # Install package in editable mode with dev dependencies
   pip install -e .[dev]
   

2. Run Tests:

   python3 -m pytest
   

🗺️ Roadmap

• Encryption: Client-side encryption for zero-knowledge cloud backups.
• Daemon Mode: Background watcher for auto-backups on file change.
• Web UI: A lightweight web interface for browsing vaults remotely.
• Plugin System: Hooks for custom pre/post backup actions (e.g., database dumps).