WIP: Add macOS PAK Tools app with Auto Guide, projects and recovery #5

Closed

Shambhala222 wants to merge 1 commit from macos-auto-guide into main

Shambhala222 commented

2026-09-07 12:38:34 -05:00

(Migrated from github.com)

Original emulator and PAK tools: Drakmor. macOS port, Auto Guide and UI enhancements: Shambhala222. This is a community contribution for upstream review, not an official release.

Included

Auto Guide with numbered dialogs, progress, acceptance prompts, Continue, Step Back and cancellation.
Saved JSON projects, journalled file operations, complete-game assembly and recovery. PAK files use same-volume moves, while unpacked files are copied from the original. Cross-volume moves require copying.
Separate emulator/index maintenance, explicit emulator roles, and hash recognition for the two 0.4.2.1 defaults. Unknown binaries require capability confirmation.
macOS selection/scrolling improvements, Help menu, credits and application icon.
English/German guides and editable PDF sources, plus the original upstream Russian PDF.
A portable PyInstaller spec and source/build instructions in tools/macos/README.md. Emulator binaries are optional local build inputs and are not committed.

The shared CLI changes are limited to verification/comparison progress reporting and index exclusions for Mac metadata and setup backups. Progress is on stderr to preserve structured stdout. The Mac front end reuses the existing GUI's profile helpers instead of shipping another copy of the Windows GUI.

Validation and review notes

I manually tested the Mac package's recording Auto Guide, existing-TOML route, Step Back, PAK completion and Recovery. The manual workflow has not been fully tested. This submission includes integration adjustments for the repository layout which have not had another end-to-end game test. During submission preparation, checks were limited to Python syntax parsing, git diff --check, a scan for personal paths and credentials, and confirming that Git preserves the PDF bytes. No new game/PAK runs or automated workflow tests were performed.

This is a draft because the project/recovery layer is substantial and needs upstream review, especially interruption, cross-volume and changed-file cases. Recovery retains changed/unrecognized files and can leave a small recovered project JSON. Project files reference local paths and should be treated as trusted local state. The original package was used on Apple Silicon; Intel/universal builds and signing/notarization are not covered.

No game assets, recordings, personal project JSON, SPRX binaries, compiled app or distribution ZIP are included. Existing GPLv3/LZ4 notices are retained. Development used AI assistance; the icon's generation prompt is included with the assets.

This adds a separate macOS front end for the existing AMPR PAK tools. A user can start with a complete game folder, follow the recording or existing-TOML route, build a complete PAK game, and retain the original for recovery. The existing Windows GUI is unchanged. Original emulator and PAK tools: **Drakmor**. macOS port, Auto Guide and UI enhancements: **Shambhala222**. This is a community contribution for upstream review, not an official release. ### Included - Auto Guide with numbered dialogs, progress, acceptance prompts, Continue, Step Back and cancellation. - Saved JSON projects, journalled file operations, complete-game assembly and recovery. PAK files use same-volume moves, while unpacked files are copied from the original. Cross-volume moves require copying. - Separate emulator/index maintenance, explicit emulator roles, and hash recognition for the two 0.4.2.1 defaults. Unknown binaries require capability confirmation. - macOS selection/scrolling improvements, Help menu, credits and application icon. - English/German guides and editable PDF sources, plus the original upstream Russian PDF. - A portable PyInstaller spec and source/build instructions in `tools/macos/README.md`. Emulator binaries are optional local build inputs and are not committed. The shared CLI changes are limited to verification/comparison progress reporting and index exclusions for Mac metadata and setup backups. Progress is on stderr to preserve structured stdout. The Mac front end reuses the existing GUI's profile helpers instead of shipping another copy of the Windows GUI. ### Validation and review notes I manually tested the Mac package's recording Auto Guide, existing-TOML route, Step Back, PAK completion and Recovery. The manual workflow has **not** been fully tested. This submission includes integration adjustments for the repository layout which have not had another end-to-end game test. During submission preparation, checks were limited to Python syntax parsing, `git diff --check`, a scan for personal paths and credentials, and confirming that Git preserves the PDF bytes. No new game/PAK runs or automated workflow tests were performed. This is a draft because the project/recovery layer is substantial and needs upstream review, especially interruption, cross-volume and changed-file cases. Recovery retains changed/unrecognized files and can leave a small recovered project JSON. Project files reference local paths and should be treated as trusted local state. The original package was used on Apple Silicon; Intel/universal builds and signing/notarization are not covered. No game assets, recordings, personal project JSON, SPRX binaries, compiled app or distribution ZIP are included. Existing GPLv3/LZ4 notices are retained. Development used AI assistance; the icon's generation prompt is included with the assets.