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)

pip install RepoPackPy

Requires Python 3.10+.

Quick start after install

# 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

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 validate <input.json> [DIRECTORY]
repopack fix      <input.json> [DIRECTORY] [--include-binary]
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
validate	(none)	Compare JSON against the live workspace; exit 1 if outdated
fix	--include-binary	Re-pack workspace into the JSON file, adding/removing/refreshing as needed

Examples

# 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

# Validate: check if workspace.json is complete and up to date
repopack validate workspace.json .

# Fix: update workspace.json with all latest files and folders
repopack fix workspace.json .

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
  ...

Sample validate output

Status  : OUTDATED
JSON    : workspace.json
Workspace: /home/user/my-app
  Missing from JSON : 2
  Extra in JSON     : 1
  Stale in JSON     : 3
  Up to date        : 36

Missing (in workspace, not in JSON):
  + src/NewComponent.tsx
  + src/utils/helper.ts

Extra (in JSON, not in workspace):
  - src/OldComponent.tsx

Stale (content changed since packing):
  ~ README.md
  ~ src/App.tsx
  ~ package.json

Sample fix output

Updated : workspace.json
Workspace: /home/user/my-app
  Added    : 2 files
  Removed  : 1 files
  Refreshed: 3 files
  Total    : 42 files (189440 bytes)

JSON Payload Schema

{
  "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
validate_workspace_tool	json_path, workspace_path	Report missing, extra, and stale files vs the live workspace
fix_workspace_tool	json_path, workspace_path, include_binary	Re-pack and overwrite the JSON with all latest files and folders

Set dry_run=true on export_workspace or import_workspace 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

pytest tests/ -v

Dependencies

• typer — CLI framework
• mcp — MCP SDK (FastMCP)
• pathspec — gitignore wildmatch pattern matching