Metadata-Version: 2.4
Name: RepoPackPy
Version: 0.1.9
Summary: Pack/unpack any source workspace into portable JSON, with MCP server support.
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pathspec>=0.12
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# RepoPack

Pack/unpack **any source workspace regardless of technology stack** (Python, Node.js, React, Angular, Vue, Rust, Go, Java, C#, and more) into a portable, structured JSON payload — and restore it faithfully from that payload.

## Features

- **Universal ignore engine** — respects root and nested `.gitignore` files plus stack-agnostic defaults (node_modules, __pycache__, .venv, target/, dist/, secrets, lock files, …)
- **Polyglot stack detection** — auto-detects Node.js, React, TypeScript, Angular, Next.js, Vue, Python, Rust, Go, Java, C# from project sentinel files
- **Binary safety** — text files encoded as UTF-8; binaries skipped by default or included as Base64 with `--include-binary`
- **5 MB guard** — files larger than 5 MB are skipped with a warning
- **Dry-run mode** — preview exactly which files would be packed or unpacked before committing with `--dry-run`
- **Path traversal shield** — `unpack` validates every path against the destination root before writing anything; blocks `../`, absolute paths, and injection attempts (CWE-22)
- **Secure PyPI version check** — uses `http.client.HTTPSConnection` (not `urlopen`) to enforce HTTPS at the type level
- **MCP server** — expose pack/unpack as tools to any MCP-compatible AI client (Claude Desktop, etc.)
- **Automated security auditing** — weekly `pip-audit` + `bandit` CI scans on all dependencies

## Installation

### From PyPI (recommended)

```bash
pip install RepoPackPy
```

Requires Python 3.10+.

### Quick start after install

```bash
# Verify the install
repopack --version
repopack --help

# Pack your project
repopack pack . -o my-workspace.json

# Preview what would be packed (no output written)
repopack pack . --dry-run

# Restore it somewhere else
repopack unpack my-workspace.json -t ./restored

# Preview what would be unpacked (nothing written)
repopack unpack my-workspace.json -t ./restored --dry-run
```

### For development

```bash
git clone https://github.com/ShanKonduru/RepoPack.git
cd RepoPack
pip install ".[dev]"
```

> **Note:** Install without `-e` (editable) so `pip-audit` can audit the package metadata correctly.

## CLI Usage

```
repopack pack [DIRECTORY] [-o output.json] [--include-binary] [--custom-ignore ".next,dist"] [--dry-run]
repopack unpack <input.json> [-t TARGET_DIR] [--force] [--dry-run]
repopack serve
```

### Options

| Command | Flag | Description |
|---|---|---|
| `pack` | `-o / --output` | Write packed JSON to this file (prints to stdout if omitted) |
| `pack` | `--include-binary` | Include binary files encoded as Base64 |
| `pack` | `--custom-ignore` | Comma-separated extra ignore patterns |
| `pack` | `--dry-run` | List files that would be packed — encoding, size, path — without writing anything |
| `unpack` | `-t / --target` | Destination directory (default: current directory) |
| `unpack` | `--force` | Overwrite existing files |
| `unpack` | `--dry-run` | List files that would be extracted or skipped without writing anything |

### Examples

```bash
# Pack current directory
repopack pack . -o workspace.json

# Dry-run: see what would be packed
repopack pack . --dry-run

# Pack a specific project, include binaries
repopack pack ~/projects/my-app -o my-app.json --include-binary

# Unpack into a new directory
repopack unpack workspace.json -t ./restored

# Dry-run: see what would be unpacked (and what would be skipped)
repopack unpack workspace.json -t ./restored --dry-run

# Unpack and overwrite existing files
repopack unpack workspace.json -t ./restored --force
```

#### Sample `--dry-run` output

```
# pack --dry-run
Dry run — would pack 42 files (186320 bytes)
Root    : /home/user/my-app
Stack   : Node.js, React, TypeScript
  utf-8       1024  src/App.tsx
  utf-8        512  src/index.tsx
  base64      8192  public/favicon.ico
  ...

# unpack --dry-run
Dry run — destination: /home/user/restored
  Would extract : 40
  Would skip    : 2
  create                src/App.tsx
  create                src/index.tsx
  skip (exists)         README.md
  ...
```

## JSON Payload Schema

```json
{
  "version": "1.0",
  "metadata": {
    "created_at": "2026-07-26T12:00:00Z",
    "root_directory_name": "my-app",
    "detected_stack": ["Node.js", "React", "TypeScript"],
    "total_files": 38,
    "total_bytes": 128450
  },
  "files": [
    { "path": "src/App.tsx", "encoding": "utf-8", "content": "..." },
    { "path": "public/favicon.ico", "encoding": "base64", "content": "..." }
  ]
}
```

## MCP Server Tools

When running `repopack serve`, two tools are registered via FastMCP:

| Tool | Parameters | Description |
|---|---|---|
| `export_workspace` | `workspace_path, output_json_path, include_binary, dry_run` | Pack a directory into JSON |
| `import_workspace` | `json_input, destination_path, overwrite, dry_run` | Unpack JSON into a directory |

Set `dry_run=true` on either tool to get a plain-text report without reading file content or writing to disk.

## Security

### Path traversal protection

Every path in an incoming JSON payload is validated before the filesystem is touched:

- Absolute paths are rejected.
- Any path component equal to `..` is rejected.
- The resolved output path is checked with `os.path.commonpath` to confirm it stays inside the destination root.

This blocks directory traversal attacks (CWE-22) regardless of how the JSON was produced.

### PyPI version check

The `--version` flag checks for newer releases on PyPI using `http.client.HTTPSConnection` directly, which enforces HTTPS at the type level and is not susceptible to `file://` or custom-scheme abuse (bandit B310 / CWE-22).

### CI security scanning

Every push and weekly schedule runs:

- **`pip-audit --strict`** — checks all third-party dependencies against known CVE databases.
- **`bandit -r repopack/ -ll -ii`** — static analysis for common Python security issues.

## Project Structure

```
repopack/
├── pyproject.toml
├── README.md
└── repopack/
    ├── __init__.py
    ├── cli.py          # Typer CLI (pack / unpack / serve)
    ├── mcp_server.py   # FastMCP server
    ├── packer.py       # Directory walker & JSON builder
    ├── unpacker.py     # JSON extractor & path-safe reconstructor
    └── utils.py        # Ignore engine, binary detector, stack detection
tests/
└── test_repopack.py
```

## Running Tests

```bash
pytest tests/ -v
```

## Dependencies

- [typer](https://typer.tiangolo.com/) — CLI framework
- [mcp](https://github.com/modelcontextprotocol/python-sdk) — MCP SDK (FastMCP)
- [pathspec](https://github.com/cpburnz/python-pathspec) — gitignore wildmatch pattern matching
