unpackmime

A command line tool to unpack MIME multipart archives into files.

AI Note

I'm finding mime-multipart is a great way to talk to LLMs like Claude and ChatGPT, but the usage style is a little different so common mime tools like munpack are kind of clumsy.

In that AI spirit, this code (and this readme, except this section) were generated by Claude 3.5 in response to the detailed prompt in the prompt.md file. I had to do some debugging iterations as well, but maybe giving it a few tries would have done it as well.

Meant for use with packmime and llpipe.

Overview

unpackmime reads a MIME multipart archive and extracts each part into a separate file in the current directory. It is designed to be more lenient than standard MIME parsers, handling both CRLF and LF line endings and not requiring strictly valid MIME headers.

Installation

npm install -g unpackmime

Usage

unpackmime [options] <filename>

Options:
  --force           Overwrite existing files
  --patch           Allow overwriting files that are tracked in git and have no uncommitted changes
  --preserve        Preserve last-modified times from the archive
  --dryrun         Show what would be extracted without actually creating files
  --exclude-from=FILE  Read exclude patterns from FILE (defaults to .gitignore)

filename: Path to the MIME archive file, or "-" to read from stdin

Examples

# Extract from a file
unpackmime archive.mime

# Extract from stdin
curl https://example.com/archive | unpackmime -

# Preview what would be extracted
unpackmime --dryrun archive.mime

# Extract and preserve timestamps
unpackmime --preserve archive.mime

# Extract, allowing overwrites of clean git files
unpackmime --patch archive.mime

File Safety

By default, unpackmime is cautious about overwriting files:

• Won't overwrite existing files without --force or --patch
• Won't write outside the current directory
• Won't write to paths matching .gitignore patterns
• Won't write to .git directories

The --patch option is safer than --force as it only allows overwriting files that are:

1. Tracked in git
2. Have no uncommitted changes

Form Fields

HTML form fields in the MIME archive are treated as files and stored in a form-fields/ directory. For example, a form field named "user" becomes form-fields/user.

File Modes

• Files with an X-Unix-Mode header have their mode set accordingly (e.g., X-Unix-Mode: 0755)
• If --preserve is used, last-modified times from the archive are preserved

Errors and Warnings

• Attempts to write outside the current directory tree will fail
• Attempts to overwrite existing files will fail (unless --force or --patch is used)
• Truncated archives will show a warning but extract all complete parts
• Invalid parts are skipped with a warning

Debug Output

You can enable debug logging with the DEBUG environment variable:

# Show all debug output
DEBUG=mime:* unpackmime archive.mime

# Show only parser output
DEBUG=mime:parser unpackmime archive.mime

# Show parser and boundary detection
DEBUG=mime:parser,mime:boundary unpackmime archive.mime

MIME Format Notes

The parser is intentionally lenient:

• Accepts both CRLF and LF line endings
• Doesn't require Content-Type headers
• Accepts either filename= or name= parameters
• Handles base64 encoded content automatically
• Processes form-data fields