StructX

A portable project container format and CLI for packing, inspecting, organizing, validating and extracting entire software projects as a single .strx file.

What is StructX?

StructX transforms entire project directories into single, compressed container files while preserving the complete internal structure. Instead of managing hundreds or thousands of separate files, you can work with a single .strx file that contains everything.

Why StructX?

• Portable: Share entire projects as a single file
• Compressed: Efficient Zstandard compression reduces file size
• Validated: Built-in integrity checking with SHA-256 checksums
• Organized: Preserves complete directory hierarchies
• Fast: Selective extraction without unpacking everything
• Safe: Path traversal protection and validation

Installation

npm install -g structx

Or use directly with npx:

npx structx <command>

Usage

Pack a project

structx pack ./MyProject

Creates MyProject.strx containing all files from the directory.

Unpack a project

structx unpack MyProject.strx

Extracts all files to MyProject/ directory.

List files

structx list MyProject.strx

Shows all files in the container with sizes.

Show information

structx info MyProject.strx

Displays metadata including:

• Project name
• File count
• Total and compressed sizes
• Compression ratio
• File type breakdown
• Creation and modification dates

Extract specific file

structx extract MyProject.strx src/main.ts

Extracts only the specified file without unpacking everything.

Validate integrity

structx validate MyProject.strx

Verifies container integrity and all file checksums.

Initialize project

structx init

Creates .strxconfig file for project-specific settings.

Commands

| Command | Description | |---------|-------------| | structx init | Initialize StructX project configuration | | structx pack <source> | Pack directory into .strx file | | structx unpack <file> | Unpack .strx file to directory | | structx list <file> | List files in container | | structx info <file> | Show container information | | structx extract <file> <path> | Extract specific file | | structx validate <file> | Validate container integrity |

Options

Pack

structx pack <source> [-o, --output <path>]

• -o, --output: Specify output file path

Unpack

structx unpack <file> [-o, --output <path>]

• -o, --output: Specify output directory path

Extract

structx extract <file> <path> [-o, --output <path>]

• -o, --output: Specify output file path

Format Overview

The .strx format is a binary container with the following structure:

┌────────────────────────────┐
│ STRX MAGIC (4 bytes)       │
├────────────────────────────┤
│ VERSION (1 byte)           │
├────────────────────────────┤
│ METADATA (JSON)            │
├────────────────────────────┤
│ FILE INDEX (JSON)          │
├────────────────────────────┤
│ FILE DATA (compressed)     │
├────────────────────────────┤
│ CHECKSUM (SHA-256)         │
└────────────────────────────┘

Features

• Compression: Zstandard compression with level 3
• Integrity: SHA-256 checksums for container and individual files
• Versioning: Format version for future compatibility
• Metadata: Project name, dates, sizes, file counts
• Index: Complete file listing with paths, sizes, offsets
• Safety: Path sanitization and traversal protection

Supported Files

StructX supports all file types including:

• Source code (.ts, .js, .tsx, .jsx, .py, etc.)
• Configuration (.json, .yaml, .yml, etc.)
• Documentation (.md, .txt, etc.)
• Images (.png, .jpg, .svg, etc.)
• Audio (.wav, .mp3, .ogg, etc.)
• Binary files (.pak, .dll, .exe, etc.)
• Any other file type

Examples

Basic workflow

# Pack a project
structx pack ./MyGame

# Check what's inside
structx list MyGame.strx

# View detailed information
structx info MyGame.strx

# Validate integrity
structx validate MyGame.strx

# Extract single file
structx extract MyGame.strx src/config.json

# Unpack everything
structx unpack MyGame.strx

Custom output paths

# Pack with custom output
structx pack ./src -o project-backup.strx

# Unpack to custom directory
structx unpack project.strx -o ./restored

# Extract to custom location
structx extract project.strx data/config.json -o my-config.json

Development

Build

npm install
npm run build

Development mode

npm run dev

Testing

npm test

Local installation

npm install
npm run build
npm link

Now you can use structx command locally.

Technical Details

• Language: TypeScript
• Runtime: Node.js 18+
• Compression: Zstandard via @mongodb-js/zstd
• CLI: Commander.js
• Hashing: Node.js crypto (SHA-256)
• Format Version: 1

Limitations

• Files are fully loaded into memory during packing
• Entire container is validated during integrity check
• No incremental updates (full repack required for modifications)

These limitations may be addressed in future versions.

License

MIT License - see LICENSE file for details.

Contributing

StructX is designed to be simple and focused. When contributing:

• Maintain the 3-source-file architecture
• Keep dependencies minimal
• Ensure cross-platform compatibility
• Add tests for new features
• Follow existing code style

StructX - Pack your projects, not your patience.