Metadata-Version: 2.4
Name: hamidrezam
Version: 0.1.0
Summary: Hamidrezam — safe, intelligent software-project backup tool (library + CLI)
Author-email: Hamidreza Moghaddam Kohi <info@hamidrezamoghaddam.ir>
Maintainer-email: Hamidreza Moghaddam Kohi <info@hamidrezamoghaddam.ir>
License-Expression: MIT
Project-URL: Homepage, https://hamidrezamoghaddam.ir/
Keywords: backup,archive,project,cli,developer-tools,zip
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# Hamidrezam — Safe, Intelligent Software-Project Backups

Hamidrezam (`pip install hamidrezam`) is a professional Python library + CLI that creates **clean, optimized project archives** while guaranteeing one non-negotiable invariant:

> **Hamidrezam NEVER modifies the source project.**

Excluded files (`node_modules`, `.venv`, caches, build artifacts, …) are excluded **only from the archive**. They are never deleted, moved, renamed, or touched on disk. Hamidrezam streams selected files **directly into the ZIP** — no temporary cleaned copies.

```bash
pip install hamidrezam
hamidrezam backup ./my-project
# -> ./backups/my-project_2026-09-20_10-50-00.zip
```

Expected output:

```text
✓ Project scanned
✓ Exclusions applied
✓ Archive created
✓ Manifest generated
✓ Archive verified
```

## Why Hamidrezam?

Developer machines accumulate gigabytes of reproducible data: virtualenvs, `node_modules`, `__pycache__`, `.next/`, `.tox/`, ML runs, logs. Copying all of it for a backup is slow and wasteful — but hand-deleting it is dangerous. Hamidrezam automates the safe middle ground:

- **Safe** — read-only scan; source hashes unchanged (covered by a dedicated integrity test).
- **Predictable** — every decision has a reason (`hamidrezam explain`).
- **Transparent** — exclusion report + in-archive manifest with SHA-256 per file.
- **Fast** — single-pass streaming, chunked hashing, no temp copies.
- **Cross-platform** — `pathlib` throughout; Windows/Linux/macOS.
- **Configurable** — CLI > `.hamidrezam.toml` > global config > defaults.
- **Scriptable & extensible** — typed Python API + `BackupWriter` abstraction (ZIP today, `tar.gz` reserved).

## Features

- Auto-detection of Python, Node.js/npm/pnpm/Yarn, React, Next.js, Vue, Nuxt, PHP, Laravel, Docker, AI/ML, generic/mixed projects.
- Sensible default exclusions (dependencies, venvs, caches, artifacts, temp, ML outputs) with opt-in knobs for `dist/`/`build/`, IDE dirs, ML outputs.
- Secrets (`.env*`, `secrets.json`, …) and large-file policies: `include` / `exclude` / `warn` (default `warn` = include + warning).
- `--dry-run` planning, `explain` auditing, `verify` integrity checks, safe `restore` with traversal protection.
- Output-inside-source self-inclusion guard; never-silently-overwrite naming.
- Zero runtime dependencies (stdlib only; `tomli` backport on Python < 3.11).

## Installation

```bash
pip install hamidrezam
```

Requires Python ≥ 3.9. Verify:

```bash
hamidrezam version
python -m hamidrezam version
```

## Quick start

```bash
hamidrezam backup ./my-project
hamidrezam backup ./my-project --dry-run
hamidrezam backup ./my-project --include-git
hamidrezam backup ./my-project --format zip
hamidrezam backup . --exclude "*.log" --exclude "data/tmp/"
hamidrezam verify ./backups/my-project_2026-09-20_10-50-00.zip
hamidrezam restore ./backups/my-project_2026-09-20_10-50-00.zip ./restored --overwrite
hamidrezam explain ./my-project
hamidrezam list ./backups/my-project_2026-09-20_10-50-00.zip
```

## CLI usage

```text
hamidrezam backup <source> [--output ./backups] [--name NAME] [--format zip]
                     [--dry-run] [--include-git]
                     [--exclude GLOB]... [--include GLOB]...
                     [--secret-mode warn|include|exclude]
                     [--large-mode warn|include|exclude] [--max-size 2GB]
                     [--symlink-mode preserve|skip|follow] [--no-compression]
hamidrezam restore <backup.zip> <destination> [--overwrite]
hamidrezam verify <backup.zip> [--check-hashes]
hamidrezam explain <source>
hamidrezam list <backup.zip>
hamidrezam version
python -m hamidrezam <same as above>
```

Include/exclude precedence: **output-safety > `--include` > protected source-of-truth files > `--exclude` > secrets/large policies > default rules > include**. In short: explicit `--include` wins over default excludes; explicit `--exclude` still wins over protected files (your explicit choice); the archive can never include itself.

## Python API

```python
from hamidrezam import BackupManager, BackupConfig

manager = BackupManager()
result = manager.backup(source="./my-project", output="./backups")
print(result.archive_path, result.verified)

config = BackupConfig(include_git=False, secret_mode="warn", max_size="2GB")
manager = BackupManager(config=config)
dry = manager.backup("./project", dry_run=True)
print(dry.files_included, dry.files_excluded)
```

Typed results: `BackupResult`, `ScanResult`, `VerificationResult`, `RestoreResult`, `BackupStatistics` (with `archive_path`, `files_included/excluded`, `bytes_included/excluded`, `duration`, `sha256`, `warnings`, …).

## Supported project types

No manual `--type` flag needed. Signals include `pyproject.toml`/`requirements.txt`/`Pipfile` → Python; `package.json` → Node.js (+ `package-lock.json` → npm, `pnpm-lock.yaml` → pnpm, `yarn.lock` → Yarn; `react`/`next`/`vue`/`nuxt` deps → frameworks); `composer.json` → PHP, `artisan` → Laravel; `Dockerfile`/`docker-compose.yml`/`compose.yml` → Docker; notebooks/`wandb`/`.mlflow` → AI/ML. Multiple labels can apply at once.

## Default exclusions

| Area | Excluded (from archive only) |
|---|---|
| Python | `.venv/`, `venv/`, `env/`, `ENV/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.tox/`, `.nox/`, `.coverage`, `htmlcov/`, `*.pyc/pyo/pyd`, `*.egg-info/` |
| Node/frontend | `node_modules/`, `.npm/`, `.yarn/`, `.pnpm-store/`, `.next/`, `.nuxt/`, `.parcel-cache/`, `.turbo/`, `.cache/`, `coverage/` |
| AI/ML | `.ipynb_checkpoints/`, `.mlflow/`, `wandb/`, `runs/`, `logs/`, `.cache/` (+ `outputs/`, `checkpoints/` unless `include_outputs=true`) |
| General | `.cache/`, `tmp/`, `temp/`, `*.tmp`, `*.temp`, `.DS_Store`, `Thumbs.db`, `*.swp/swo` |
| Build | `dist/`, `build/` unless `include_dist_build=true` |
| IDE | `.idea/`, `.vscode/` only when `include=false` (default `true` = preserved) |
| Git | `.git/` unless `--include-git` / `[git] include=true` |

Never excluded by default: `README.md`, `LICENSE`, `.gitignore`, `.gitattributes`, `Dockerfile`, compose files, `package.json`, lock files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `poetry.lock`, `uv.lock`, `Pipfile.lock`, `composer.lock`), `requirements.txt`, `pyproject.toml`, `composer.json`. Model weights (`*.pt/.pth/.onnx/.safetensors/.ckpt/.bin`) are never auto-excluded for being large — they trigger `warn`.

## Configuration (`.hamidrezam.toml`)

Place in the project root; see `examples/.hamidrezam.toml`:

```toml
[backup]
format = "zip"
compression = true
output = "./backups"

[git]
include = false

[secrets]
mode = "warn"

[large_files]
mode = "warn"
max_size = "2GB"

[symlinks]
mode = "preserve"

[ide]
include = true

[build]
include_dist_build = false

[ml]
include_outputs = false

[custom]
exclude = ["*.log"]
include = []
```

Priority: **CLI args > `.hamidrezam.toml` > global config (`~/.config/hamidrezam/config.toml` or `~/.hamidrezam.toml`) > defaults**.

## Secrets policy

`.env`, `.env.local/.production/.development/.staging`, `secrets.json`, `credentials.json` (plus generic `.env.*`; `.env.example` is treated as a safe template). Default `warn`: included + listed as a warning. Use `exclude` to drop, `include` to silence the warning.

## Large files

Any file over `max_size` (default `2GB`; accepts `500MB`, `1024`, …) follows `large_files.mode` (default `warn`). Never silently dropped.

## Git handling

`.git/` excluded by default (`include_git=false`). Enable per-run (`--include-git`) or per-project (`[git] include=true`). `.gitignore`/`.gitattributes` are always preserved.

## Restore

```bash
hamidrezam restore backup.zip ./restored-project --overwrite
```

Validates the archive, rejects `../` and absolute entries, confines writes to the destination, preserves structure, skips existing files unless `--overwrite`, restores symlinks best-effort (falls back to regular files on Windows without privilege).

## Verification

Every backup auto-verifies (ZIP integrity + manifest schema). Re-check later:

```bash
hamidrezam verify backup.zip
hamidrezam verify backup.zip --check-hashes   # re-hash contents vs manifest
```

Each archive embeds `.hamidrezam/manifest.json` with `tool`, `version`, `created_at`, `project_name`, `profiles`, `statistics`, `warnings`, and per-file `path/size/sha256/modified_time` (relative paths only).

## Security

- No blind extraction; all member names validated.
- Symlinks never followed outside the project; loops detected via `(st_dev, st_ino)`.
- Broken links, special files (sockets/FIFOs/devices), permission errors → skipped with warnings, never fatal.
- Secrets/large files surface as warnings, never silently leaked/dropped.

## Examples

- `examples/.hamidrezam.toml` — annotated config.
- `examples/basic_backup.py` — `python examples/basic_backup.py` after install.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
python -m build
```

## Testing

```bash
pytest            # full suite
pytest tests/unit
pytest tests/integration
```

Covers scanner (nesting/empty/unicode/spaces), exclusions, secrets, large files, ZIP+manifest+hashes, restore/overwrite/traversal, symlinks (broken/outside/skip), CLI exit codes, and the mandatory **source-integrity** test (hashes + paths + mtimes identical before/after backup).

## Roadmap

- `tar.gz` writer (`TarGzBackupWriter` via the existing `BackupWriter` interface).
- Opt-in `.gitignore`-aware mode, negation (`!`) support.
- Progress bars, JSON output (`--json`), exclusion-size report table.
- `hamidrezam init` config generator.

## Known limitations (0.1.0)

- Only `zip` format (`--format tar.gz` fails with a clear future-reserved message).
- `.gitignore` patterns are parsed by `GitIgnoreRule` for API use but not auto-applied to backups (avoids surprising drops of `.env`-style files).
- `runs/`, `logs/`, `tmp/`, `temp/`, `outputs/`, `checkpoints/` directory names are excluded wherever they appear; rename intentional source dirs or use `--include` to keep them.
- Symlink restore on Windows may fall back to regular files without Developer Mode/admin.

## License

MIT — see `LICENSE`.

## Author

**Hamidreza Moghaddam Kohi** — Full Stack Developer · AI · Automation
Website: <https://hamidrezamoghaddam.ir/> · Email: <info@hamidrezamoghaddam.ir>
