ARMS - Archive and Replacement Management System

ARMS is a command-line utility for creating and extracting markdown-based file archives with intelligent text replacement capabilities. It enables efficient file packaging, distribution, and template-based project initialization through a human-readable markdown format.

Installation

pip install arms

Quick Start

Create a markdown archive from a ZIP file:

arms -c -i source.zip -f archive.md

Extract files from a markdown archive:

arms -x -f archive.md -o ./output

Usage

ARMS operates in two modes: create and extract.

Create Mode

Generate a markdown archive from a ZIP file with optional text replacement.

Basic creation:

arms --create --input source.zip --file archive.md

With text replacement:

arms -c -i template.zip -f output.md NewProject:OldProject mycompany:democorp

Lock files from replacement:

arms -c -i source.zip -f archive.md --locked "*.json,*.yml" NewName:OldName

Output to stdout:

arms -c -i source.zip > archive.md

Extract Mode

Extract files from a markdown archive to a target directory.

Basic extraction:

arms --extract --file archive.md --output ./destination

Preserve existing files (add .patch suffix):

arms -x -f archive.md -o ./dest --patch

Extract from stdin:

cat archive.md | arms -x -o ./destination

Extract to current directory:

arms -x -f archive.md

Command-Line Options

Mode Selection (Required)

-c, --create - Create markdown archive from a ZIP file
-x, --extract - Extract files from a markdown archive

Input/Output Options

-i INPUT_FILE, --input INPUT_FILE - Input ZIP file path (required for create mode)
-o OUTPUT_DIR, --output OUTPUT_DIR - Output directory for extraction (defaults to current directory)
-f FILE_NAME, --file FILE_NAME - Markdown archive file path (uses stdin/stdout if omitted)

Processing Options

-l LOCKED, --locked LOCKED - Comma-separated file patterns to exclude from text replacement
-p, --patch - Add .patch suffix to duplicate files during extraction (default: overwrite existing files)

Replacement Rules

rules - Space-separated replacement rules in format new:old

Features

Intelligent Text Replacement

ARMS performs full-style text replacement, automatically handling multiple naming conventions:

camelCase - myVariableName
PascalCase - MyClassName
snake_case - my_variable_name
kebab-case - my-variable-name
SCREAMING_SNAKE_CASE - MY_CONSTANT_NAME

Example:

arms -c -i template.zip MyProject:DemoProject

This replaces:

DemoProject → MyProject
demoProject → myProject
demo_project → my_project
demo-project → my-project
DEMO_PROJECT → MY_PROJECT

File Pattern Locking

Prevent specific files from undergoing text replacement using glob patterns:

arms -c -i source.zip --locked "package.json,*.lock,config/*" NewName:OldName

Patterns match against both full paths and basenames.

Binary File Support

ARMS automatically detects and handles binary files:

Text files are preserved as-is in the markdown archive
Binary files are Base64-encoded with a base64 language tag
Detection uses UTF-8 decoding with NUL byte checking

Conflict Resolution

During extraction, ARMS handles existing files based on the --patch flag:

Default behavior (--patch not set): Overwrite existing files directly
With --patch: Append .patch suffix to avoid overwriting

Example:

# Overwrites file.txt if it exists
arms -x -f archive.md -o ./output

# Creates file.txt.patch if file.txt exists
arms -x -f archive.md -o ./output --patch

Use Cases

Project Template Distribution

Create reusable project templates with customizable names and identifiers:

# Package template
arms -c -i spring-boot-template.zip -f template.md \
  YourProject:DemoApp yourcompany:example

# Initialize new project
arms -x -f template.md -o ./my-new-project

LLM Context Generation

Package codebases into markdown format for use as LLM context:

# Create archive
arms -c -i codebase.zip -f context.md

# Use with LLM
cat context.md  # Copy to LLM prompt

Configuration Management

Distribute configuration files with environment-specific replacements:

# Prepare production configs
arms -c -i configs.zip -f prod-config.md \
  prod-db.example.com:dev-db.localhost \
  production:development

# Deploy configurations
arms -x -f prod-config.md -o /etc/myapp

Documentation Bundling

Archive documentation and code samples together:

arms -c -i docs.zip -f documentation.md

Archive Format

ARMS uses a structured markdown format:

Text files:

**path/to/file.txt**:

File content with multiple lines

Binary files:

**path/to/image.png**:
```base64
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==


This format provides:
- Human readability for text files
- Safe encoding for binary files
- Version control compatibility
- LLM-friendly structure

## Technical Details

### File Type Detection

Text files are identified by:
1. Successful UTF-8 decoding
2. Absence of NUL bytes (`\x00`)

If either condition fails, the file is treated as binary and Base64-encoded.

### Directory Handling

- ZIP entries marked as directories are skipped
- Parent directories are created automatically during extraction
- Empty directories are not preserved in archives

### Fence Detection

ARMS uses dynamic backtick fence detection:
- Scans file content for existing backtick sequences
- Uses one more backtick than the maximum found
- Minimum of 3 backticks per CommonMark specification

## Requirements

- Python 3.7 or higher
- lesscli >= 0.2.0

## Version

2.0.0

## License

MIT License

## Author

qorzj

## Repository

https://pypi.python.org/pypi/arms

Metadata

Release files for arms 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for arms 2.1.0
File	Size	Uploaded
arms-2.1.0.tar.gz	10.9 kB	Nov 19, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for arms 2.1.0
File	Interpreter	ABI	Platform	Reset
arms-2.1.0-py3-none-any.whl 8.7 kB Nov 19, 2025	Python 3	none	any	Details

Total release size: 19.6 kB

Release files / arms-2.1.0.tar.gz

Download URL	arms-2.1.0.tar.gz
Size	10.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`911302c379b70f35f065b6b1052a8eb8be3757b79709eb8c174bf41bbe9a3265`
BLAKE2b-256 checksum How to use checksums	`159bab61a6bf3049b332072541fdde5f2afd47966fac679ee82e68a66c073e23`
Upload date	Nov 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.11.8`

Release files / arms-2.1.0-py3-none-any.whl

Download URL	arms-2.1.0-py3-none-any.whl
Size	8.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`dd61376b3290dd52dcdf607040f6eb9219d83e84d7bb342a1173f5501c19c184`
BLAKE2b-256 checksum How to use checksums	`10b9c36a9f389c94260a56ef4ceadb4db93c9e3eb35a26fef448f34d8ee19f2b`
Upload date	Nov 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.11.8`