p7mextract Development Guide

Instructions for working with the p7mextract codebase, a Bash CLI tool for extracting content from digitally signed `.p7m` files (PKCS#7 format) on macOS.

Project Context

p7mextract is a macOS-specific Bash utility that extracts content from digitally signed `.p7m` files using OpenSSL's smime capability. It automatically detects between DER and PEM encoding formats. The tool is designed as a single executable script with comprehensive test coverage using the Bats testing framework.

Development Commands

When working with this project, use these Make targets:

Testing Framework

The project uses **Bats** (Bash Automated Testing System) with the following helper libraries:

**Important:** Bats libraries must be installed at `/opt/homebrew/lib/` (Apple Silicon) or `/usr/local/lib/` (Intel Macs).

Code Architecture

The main executable (`p7mextract`, approximately 300 lines) is structured in these sections:

1. **Color/Output Helpers** — Functions like `msg_success()`, `msg_error()`, `msg_warning()`, `msg_prompt()` with Unicode icons for user-friendly output

2. **Utility Functions**:

- `get_default_output()` — Smart filename detection (e.g., `file.pdf.p7m` → `file.pdf`)

- `check_dependencies()` — Validates required tools are available

- `confirm_overwrite()` — Interactive overwrite confirmation

- `get_human_size()` — Human-readable file size formatting

3. **Core Extraction** — `extract_p7m()` function that tries DER format first, falls back to PEM if needed, and cleans up on failure

4. **Main Function** — Handles argument parsing (`-o`/`--output`, `-h`/`--help`), input validation, and interactive prompts with sensible defaults

Test Organization

Git Workflow Rules

**Critical:** Never push directly to the `master` branch. The branch has protection rules requiring:

Always create a feature branch and open a pull request for any modifications.

Platform Requirements

This tool is macOS-specific and requires:

Development Guidelines

When modifying the codebase:

1. **Before making changes**, read the main `p7mextract` script to understand the current implementation

2. **Run tests frequently** using `make test` to ensure changes don't break existing functionality

3. **Add test coverage** for new features in `test/p7mextract.bats`

4. **Maintain the single-file design** — all functionality should remain in the main executable

5. **Preserve macOS compatibility** — test commands work on macOS specifically

6. **Follow the existing code structure** — keep functions organized in the documented sections

7. **Use the helper functions** for consistent output formatting and error handling

8. **Test both DER and PEM formats** when modifying extraction logic

Common Tasks

Adding a New Feature

1. Create a feature branch from `master`

2. Implement the feature in the `p7mextract` script

3. Add corresponding test cases in `test/p7mextract.bats`

4. Run `make test` to verify all tests pass

5. Open a pull request to `master`

Fixing a Bug

1. Create a branch for the fix

2. Add a test case that reproduces the bug (should fail initially)

3. Implement the fix in the main script

4. Verify the new test passes and existing tests still pass

5. Open a pull request

Modifying Extraction Logic

1. Review the `extract_p7m()` function carefully

2. Consider both DER and PEM format handling

3. Ensure cleanup logic handles failure cases

4. Test with actual `.p7m` files (fixtures are generated automatically)

5. Verify error messages are user-friendly

Key Files Reference