#LunaPack

#Features

• A bundle that is the program, not a wrapper around it
  The archive is appended to the LunaPack launcher, so the produced file is the launcher — and the launcher is the program the user starts. The arguments of the bundle are the arguments of the bundled program, the exit code is its exit code, and a bundle that was started by a double-click takes its own console window away before a program that draws a window starts, so the application is alone on the desktop. A copy of the executable would not do this; a plain archiver cannot do it at all.

• The libraries of the program are found and carried
  A Windows program is the executable and the libraries it loads, and the names of those libraries are written in the import table of the executable. LunaPack reads that table — and the tables of the libraries in it — and carries the libraries that sit next to the program, so a bundle of a program with its DLLs needs nothing but the program and the output path. See The dependencies of the program.

• Every entry is checksummed, and every entry is fingerprinted
  The SHA-256 checksum of an entry is computed over the original content, so it validates the data the user actually gets and not the compressed form. The MD5 fingerprint of the same content is carried next to it, because the MD5 is what the platform tooling shows, and a user who wants to compare the file with what their file manager reports has nothing to compare against otherwise. The fingerprint of the produced file is reported as well, and it is computed while the file is written, so a 300 MB package is never read back for it.

• Compression that is a choice, not a default
  --compression-method picks none, gzip, lz4 or auto. auto compresses every entry with gzip but keeps the raw bytes when gzip would make the entry bigger. The LZ4 implementation lives in this package, because the MoonBit toolchain ships none, and what it produces is a standard .lz4 frame: the lz4 tool decompresses it and this package decompresses what that tool produces. The frames are checked against the values the format publishes, not against the tool — see Verification.

• Encryption to a public key, or to a passphrase
  The mechanism is the one of the reference implementation this package follows: a key is established with the recipient, HKDF-SHA512 turns it into the key of the package, and every entry is sealed on its own with ChaCha20-Poly1305 under a key and a nonce derived for it. The additional data of an entry holds its place in the package and its name, so neither can be changed without the seal breaking. A check in the manifest tells a wrong key from a damaged package.

• Every primitive is implemented here, and checked against its vector
  SHA-512, HMAC, HKDF, PBKDF2, ChaCha20, Poly1305, X25519 and Ed25519 — the toolchain ships none of them. Each one is checked against the vector that its standard publishes (FIPS 180-4, RFC 4231, RFC 5869, RFC 8439, RFC 7748, RFC 8032), and the derivation is checked against the reference implementation itself: the master key, the key and the nonce of a record, and the sealed record are compared byte for byte with the values the reference produces.

• A package that says what it is, and a host that can prove it
  The manifest of a package carries the SHA-256 of its own bytes, and a sealed package carries a MAC of it as well, so a manifest that was changed is refused instead of being obeyed. A damaged package is refused rather than taken for something else, the package is written in one piece so a crash cannot leave half of one behind, and the program of a bundle is checked before it is started.
  The one thing a package cannot settle by itself is whether it is the package the publisher meant, because the digest inside it is not a secret. The host settles it: lunapack sign writes a detached Ed25519 signature next to the package and lunapack verify --signature checks it, or the host publishes the digest and lunapack verify --expected-sha256 checks that.

• An icon that survives the round trip
  When the application carries an icon, the bundle gets it as well, so Explorer shows the application's own icon instead of the launcher's. The icon is read from the application executable with a small PE reader and written into the bundle with the Windows resource API, which creates the resource section the launcher does not have. All icon sizes are copied, so the bundle looks right at every zoom level.

• Install scripts that run on the platform they were written for
  The script body is stored verbatim in the manifest together with the platform it targets, which is inferred from the file extension. At unpack time the script matching the host platform runs and a script for a different platform is skipped, so one package can safely be unpacked anywhere.

• One format, two front ends
  The same library and the same container behind lunapack (a native binary) and moonx riantr/LunaPack@latest (the WebAssembly build on the registry). The archive is found from the tail of the file in both cases, so verify, info and unpack work on a bundle exactly as they work on a plain package.

#What you get

#Install

moon add riantr/LunaPack@0.1.23

import {
  "riantr/LunaPack@0.1.23",
}

///|
import {
  "riantr/LunaPack" @lib,
}

///|
import {
  "riantr/LunaPack" @lp,
}

#What the release was checked on

#What changed in 0.1.23

• The libraries of the program are found and carried. A Windows program is not one file: it is the executable and the libraries it loads, and a bundle that carried only the executable started and then stopped with STATUS_DLL_NOT_FOUND (0xC0000135). The names of those libraries are written in the import table of the executable, and LunaPack reads that table now — and the delay-load directory with it, and the tables of the libraries in turn. The libraries that sit next to the program are carried next to it in the bundle, which is where the program looks for them.
  A bundle is therefore made with the program and the output path alone:

  lunapack --input-exe=./build/myapp.exe --output-exe=./dist/myapp.exe

  The libraries of the system and the API sets (api-ms-win-…, whose files do not exist at all) are left out, and so is every library that is not next to the program: it is either part of the system or one the program finds somewhere else, and neither is something a bundle can carry. The list of what was found is printed, so that a bundle whose size nobody can explain does not happen, and --no-auto-deps says that only the files named with --Files are carried.
  What is not found, because nothing in the binary says it: a library the program opens with LoadLibrary when it runs, and every data file it reads. Those are still named with --Files.
  The section "The dependencies of the program" has the whole of it.

• The suite grew from 158 to 179 tests, and the battery of mutations grew from 21 to 33: every guard of the new discovery was taken out of the code once, and the test that covers it went red. The table under "Every guard was taken out once" lists them.

• Nothing else changed: the tool behaves exactly as it behaved in 0.1.22.

#What changed in 0.1.22

• The README says how to bundle from another module. The tool was always meant to be run by a build, and moonx riantr/LunaPack@0.1.22 ... runs it on a machine that has no MoonBit toolchain. What was missing was the recipe that wires it into the build of another module: MoonBit has no hook that runs on an import — a dependency is not allowed to run commands in the build of whoever depends on it, and that is on purpose — but it has a rule in moon.mod and a dev_build in moon.pkg, and a rule can run moonx. The section "Bundling from another module" has the configuration and the two things that have to be kept in mind: a dev_build runs before the build, so the rule has to build the application first, and the version of LunaPack has to be named, or every build can pick a different packer.

• Nothing else changed: the tool behaves exactly as it behaved in 0.1.21.

#What changed in 0.1.21

• A warm start shows a bar. A bundle that is started a second time does not unpack the payload again: it reads the payload back and compares it with the package, which is what proves the cache still holds what it belongs to. That read-back now tells the caller how far it has come, so a bundle that owns a console draws a verify bar while it reads the payload back. Before this, a warm start drew nothing at all while it read a hundred megabytes from the disk, and a start that says nothing looks like a start that hangs.
  Measured on a bundle of 151 files (150 MB) that owns a console: the start after the first drew 151 verify frames where it had drawn none.

• The payload of a bundle that cannot be unpacked next to it is cached anyway. The folder next to the executable cannot always be written to, and the payload used to go to a folder made by @fs.tmpdir — which makes a folder of its own on every call and never uses one twice. The cache was therefore never reused: every start unpacked the whole payload again, into a folder that was thrown away at the end of it. The payload goes to the cache of the user instead — %LOCALAPPDATA%/LunaPack/cache/<hash>/ on Windows, $XDG_CACHE_HOME/lunapack/ or $HOME/.cache/lunapack/ elsewhere, and LUNAPACK_CACHE_HOME names the place itself — which is the same on every start. The temporary folder of the system is only used when none of them can be written to, and then for that one start only.
  Measured on the same bundle, with the folder next to it made unusable: the start after the first went from 16.4 s to 4.1 s, and it stopped leaving a copy of the payload behind in the temporary folder.

• A path that cannot be looked at is answered with "no". @fs.exists raises when the path cannot be looked at — a file in the way of a folder is such a path — and the launcher asked it about the places it was about to write to. The answer ended the start. The launcher now goes on to the next place instead.

• The generated interface of the package is up to date. The 0.1.20 release shipped the three functions of the launcher auto-download without regenerating pkg.generated.mbti, so the committed interface still said 0.1.19. The file is now what moon info produces.

#What changed in 0.1.20

• --launcher auto-download. A self-extracting bundle is a native LunaPack executable with the archive appended. When LunaPack runs as Wasm (for example under moonx) it has no native executable of its own to use as the bundle stub, so bundle could only produce a non-self-extracting file. --launcher with no file now downloads the native launcher for the current system from this release (lunapack-<os>-<arch>[.exe]) and shows a progress bar plus a 正在下载 launcher status line while it works. An explicit path still works as before; LUNAPACK_LAUNCHER_URL overrides the source for mirrors or air-gapped installs, and the download is cached per version.

• --studio alias. LunaPack --studio (and --Studio, --studio=true, --Studio=true) now launch LunaPack Studio, mirroring the existing --GUI / --gui spelling variants.

• Executable bit on POSIX. The produced self-extracting bundle is now made executable on Linux/macOS so it can run on its own.

#What changed in 0.1.19

• LunaFlow-driven hardening. The collect_files traversal in pack.mbt used while true and was flagged by the static analyzer as a possible infinite loop. More importantly, on a real filesystem a symlink cycle would actually loop forever. The loop now terminates on an explicit stack-empty check and remembers visited directories, so every directory is expanded at most once — termination is provable and symlink cycles are broken.

• Crypto bounds guards. md5_compress and sha512_compress now check the block length up front (off + 64 / off + 128); a contract violation can no longer become an out-of-bounds read. The callers still always pass block-aligned offsets.

• Documented analyzer false positives. The TAINT-INDEX entries on dirname/basename (platform.mbt), hex_to_bytes (hex.mbt), parse_flags (cli.mbt) and decimal (studio.mbt) were reviewed: each index is bounded by an explicit length guard, so they are not real bugs. Comments now say so.

• Tests and checks. moon check --target native is clean and the full suite (150 tests) passes.

#What changed in 0.1.18

• LunaPack and LunaPack Studio are one product. There is one version, one tag and one GitHub release. Studio is an optional asset of that release, not a second package on Mooncakes and not a separately numbered program. The 0.1.18 in moon.mod, in CLI_VERSION and in the Studio window are the same number; a whitebox test reads moon.mod and refuses to let them drift.

• --GUI opens the graphical front end. lunapack --GUI finds a Studio build next to the CLI (or in the versioned cache), downloads lunapack-studio-<os>-<arch>.zip from this version's release when it is missing, and shows a live progress bar while it streams the archive. The download is extracted in pure MoonBit - no unzip, tar or PowerShell is needed - and entry names are checked so a crafted archive cannot write outside the install directory. HTTPS_PROXY / NO_PROXY are honoured, and loopback mirrors always bypass the proxy.

  lunapack --GUI
  lunapack --GUI --input-file=./myapp.exe --output-file=./myapp-bundle.exe \
           --Files=./assets --Files=./docs --compression-method=lz4

  The flags are forwarded, not acted on: the window opens with those fields already filled in. --cli=<path> is added automatically so the window drives the very LunaPack that started it, even when Studio was downloaded into a cache folder far from the checkout. Override the location with LUNAPACK_STUDIO, the cache with LUNAPACK_STUDIO_HOME, or the source with LUNAPACK_STUDIO_URL (useful for a mirror or an air-gapped install).

• The flag documentation now matches the parser. The no-subcommand (moonx riantr/LunaPack@latest ...) front end reads --input-exe / --input-file and --output-exe / --output-file. The bundle subcommand reads -i / --input and -o / --output. The long -exe / -file spellings pass the unknown-flag check but are ignored by bundle, which then reports "bundle requires -i <input_exe> and -o <output_exe>". This was found by driving a real bundle with those flags; the examples below now say which form each flag belongs to.

• Startup arguments are part of the contract. Studio parses every alias in both --flag value and --flag=value form, including repeatable --Files, and folds them into its form. Empty forwarded fields keep the defaults; an explicit --cli is never overwritten by auto-discovery.

• Two defects found by running the real 188 MB asset. Windows packers write \ as the separator inside a zip; taken verbatim those names became mixed-separator paths and @fs.mkdir reported "The system cannot find the path specified". Entry names are normalised to / before any path is built, and a trailing separator no longer turns a directory entry into a file. A real 246-file / 419 MB extraction now completes. The other defect was a window that inherits the CLI's stdout and keeps a pipe open, so lunapack --GUI | ... never saw EOF. Redirecting the child's streams into studio.log fixed it on the development toolchain, but the @process output API then changed shape (see above) and no stdout=/stderr= argument can be written that compiles on every toolchain. Since this module ships as source, portability wins: the streams are inherited and a piped invocation reaches EOF when the window is closed.

• The suite grew from 135 to 150 tests on both the native and the Wasm backend. The new cases cover GUI-flag detection, argument forwarding, download URL construction, proxy bypass, redirect resolution, Windows zip separators, zip-slip rejection and the version/asset-name drift detector.

#What changed in 0.1.17

• --files and --Files are the same flag. This documentation and every example write --Files, and the parser matched a flag name exactly, so a command line that reached for --files was refused with unknown flag--files. It is read as the same flag now, in the moonx form and in the subcommand form alike, and the two spellings can be mixed in one command line: the folders come back in the order they were given, because the values are collected in one pass over the arguments rather than as two lists that are joined afterwards.
• Nothing else became case-insensitive. --file is still a mistake and is still reported, as is every other near miss. An exact list is what turns a misspelled flag into an error instead of a command that quietly does something else, and that property is kept: the one flag with two spellings is listed twice, deliberately, and the test that lists every flag the tool reads now checks both.
• --os is accepted, which it never was. build_options read --os and this page documented it, but the name was missing from the list of known flags, so every command line that set the platform was refused with unknown flag --os: a package for another platform could not be made at all. It was found by putting the flags the tool reads next to the flags the tool knows and looking for the difference, and it was the only flag in that gap.
• A test that failed about once in 256 runs does not any more. The test that changes a signed package wrote Z over byte 30 to break the signature. Byte 30 is inside the random salt of the manifest block, so one time in 256 it was already a Z, nothing changed, and the signature still held — which is what happened to one wasm run of the gate sweep before this release, while two runs straight after it passed. The byte is turned into a different one now instead of into a fixed one.

#What changed in 0.1.16

• The fifteen seconds of the menu now pass. 0.1.15 counted down by waiting one second on the console input handle and reading when the wait said there was something. That wait is on the handle, and a console signals the handle for anything at all: a window that gained focus, a window that was resized, the mouse. Measured on this machine: a wait on the input handle of a console with no key pressed returns WAIT_OBJECT_0 in 0–95 ms, every time. The read that followed is ReadConsoleW, which in the line-input mode of a console waits for a whole line — for ever, when nobody is typing. The countdown therefore never counted a second: a double-clicked bundle with a cache that is not complete sat on the menu showing 2 in 15 s and never started.
• The wait is no longer taken for an answer. What is on the buffer is looked at before anything is read: only a KEY_EVENT that went down and carries a character is an answer. Everything else — the focus change, the resize, the mouse, the key that was let go, the arrow key with no character — is taken off the buffer with ReadConsoleInputW instead of being read as text, because leaving it there would signal the very next wait and no second would pass either.
• The rule is a plain function, so it can be tested without a console. has_key_press(records, count) walks the 20-byte INPUT_RECORDs and says whether one of them can answer a question. The test holds four buffers — a focus change, a key going up, an arrow key, and the 2 pressed — and each of the four conditions has to hold for the last one to be the answer. The mutation that takes the condition out — "anything the console reports is an answer", which is exactly what 0.1.15 shipped — turns that test red and only that test.

#What changed in 0.1.15

• A first start asks what it should do. A bundle that is double-clicked, carries no argument of its own, and has never unpacked its payload prints three lines before it does anything:

  LunaPack: <name> <version>
    [1] install it to a folder
    [2] run it from the folder next to this file
    your choice [1/2], 2 in 15 s:

  Fifteen seconds without an answer take 2, and the line then says so — your choice [1/2]: 2 (nobody chose) — rather than leaving the wait unexplained. A bundle that nobody is watching still starts on its own.
• 1 is the unpack path and not a second implementation of it. It asks for a folder, offering %LOCALAPPDATA%\Programs\<name> when Enter is pressed, and then runs the code unpack runs — the pre and post scripts of the package included — and starts the program from that folder with the folder as its working directory. What a bundle installs is therefore what lunapack unpack produces, and the two cannot drift apart.
• The menu is only for a person. It needs all four of: no argument, a console the bundle created for itself, stdin that is a real console (asked of GetConsoleMode), and a payload that is not already cached in full. A script, a pipe, a start from a terminal and every start after the first one go straight to the program, so nothing waits fifteen seconds for an answer that cannot come.
• The unpacking shows a bar. The line is rewritten in place: a bar of 24 cells, the percentage, the files done out of the total, the megabytes done out of the total, and the name of the entry being written. The whole line, its unpack/verify label included, is 78 characters — cut or padded to exactly that, so the tail of the line before it cannot be left on the screen. On the path that unpacks next to the bundle there are two bars, unpack and then verify, because the payload is read back after it arrives; the install path shows the first one.
• The bar cannot claim more than the whole. A count of bytes larger than the total the manifest gives is clamped at 100%, so a package whose last entry is bigger than the sum of the manifest reads as finished rather than as a defect in the unpacking. The mutation that removes the clamp turns the test of the bar red.
• A name the console cannot show is left out. The entries of a package are whatever the packer put in it, so the name at the end of the line is printed only when it is plain ASCII; guessing at a code page would turn the bar into noise.
• The bar is written to the console handle, not through a buffer. The launcher calls WriteFile on the standard output handle it got from GetStdHandle, which is what lets it write while a package is being unpacked and after a console was handed on. Nothing of this is visible to the interface of the package: progress.mbt is private, extract_to, unpack and cache_matches keep the signatures they had, and a bar is an optional argument the launcher passes.

#What changed in 0.1.14

• A double-clicked bundle of an application with a window starts at all. bundle used to copy the subsystem of the bundled program onto the launcher, so an application that draws a window produced a bundle that says "windowed". A windowed program has no standard streams at all, and the MoonBit runtime does not survive that: the process is gone before the first line of main runs — no window, no message, and not even a cache folder. That is what every double-clicked bundle of a GUI application did, and it is why the same file worked from a command line (a console was there) and did nothing at all from the desktop. Measured on this machine: the tool's own binary, its subsystem field changed to GUI and nothing else, exits with 1 and writes nothing when it is started with no standard streams; the same bytes started from a console print their usage.
• The console the bundle is given is taken away instead. The bundle keeps the console subsystem of the launcher, which is what makes it start, and the launcher takes away the console that comes with it. It asks GetConsoleProcessList whether the console has only this process on it — the console of a terminal has the shell on it as well, and that one is never touched, because it is the window the user is typing into — and it does so only for a program whose PE header says it draws a window; a console program keeps the window its output goes to.
• The program is started before the console goes away. FreeConsole destroys a console that has no other process on it, and after that the standard handles of the launcher lead nowhere: a spawn that hands them on fails with "the handle is invalid". The launcher therefore starts the program with CreateProcessW of its own, keeps the process handle, frees the console, and waits — so the exit code of the bundle is still the exit code of the program, which is the contract the command line depends on.
• The subsystem of the launcher is no longer rewritten. (windowed) no longer appears in the summary of bundle, and a non-PE input can no longer dictate anything about the bundle. set_pe_subsystem and pe_subsystem_of are unchanged for library users; the launcher reads the subsystem of the program it starts.

#What changed in 0.1.13

• A cache is handed out on what it holds, not on its name. The payload is unpacked into a folder of its own and moved into the place the next run looks at, and the move was the one step the launcher never looked at: the folder that arrived was named like a complete cache whether all of it arrived or only part of it did. The reported cache held 296 of the 376 files the package carries — the missing 80 were a contiguous tail — with the completion marker in it, and the bundle started the application from it. The application then failed to load Microsoft.WindowsAppRuntime.dll, which was one of the files the move had left behind: a DllNotFoundException from deep inside an application that has nothing to do with unpacking. The folder is read back after it arrives now, and a folder that does not hold what the package carries is removed rather than started. The fall back to a temporary directory — used when no cache can be written next to the executable — is read back in the same way; it checked the main program only, so a sibling library that did not arrive was never noticed, which is the same failure by another road.
• The module is MIT. LICENSE carried the Apache-2.0 text and moon.mod carried its identifier. Nothing in this package needs the patent grant or the notice file that Apache-2.0 asks for: every primitive is written here rather than taken from another project, so there is no third-party notice to preserve. The license of a published version cannot be changed after the fact, so it takes effect here.

#What changed in 0.1.12

• A bundle that cannot start says so. Through moonx there is no native launcher, so the application itself becomes the stub: the result holds the whole payload and cannot unpack itself. The warning that said so was printed before the summary, where a list of a few hundred checksums hides it, and the command still ended with bundled N files. It is the last line now, it names the file, it says that the file carries the payload but no launcher, and it goes to stderr as well as to stdout. This cost a real user an afternoon: a 124 MB file that held every dependency and could not start.
• A bundle that is refused leaves nothing behind. The archive is written before the launcher is looked at, so a launcher that turns out to be missing left *.lunapack-archive.tmp in the directory that was asked for the bundle. The cleanup reaches the archive from the moment it is written.
• The mutation battery runs on a Windows checkout again. Its anchors are written with LF endings and .gitattributes keeps a .ps1 on CRLF, so every anchor that spanned more than one line stopped matching and reported ANCHOR NOT FOUND — the battery quietly stopped proving anything. The comparison is made on one line ending now.

#What changed in 0.1.11

• The native build builds on every platform again. The Windows-only GetModuleFileNameW declaration was guarded with target="native", which is true on Linux and macOS as well, so the linker looked for a Windows symbol there and the release workflow could not build those two binaries. The declaration and its caller are guarded with all(target="native", platform="windows") now; on other platforms the launcher keeps the argv[0] fallback it had before 0.1.10. The Windows build and the Wasm build were never affected, and the container layout does not change.

#What changed in 0.1.10

• The command that was typed is the command that runs. --input-file and --output-file are names for --input-exe and --output-exe now, and a flag the tool does not know is refused instead of being dropped. An empty output path is refused as well. Without those three changes an unknown flag could scan a whole directory and then fail with a rename to an empty file name — which is exactly what a real moonx riantr/LunaPack@latest run with the two aliases did.
• A failure says that it failed. Every command that cannot do what it was asked now exits with 1 instead of 0. The VERIFY OK / VERIFY FAILED / error: ... markers on stdout stay, so a script that reads the output keeps working.
• A check that was asked for is a check that is made. verify --extracted no longer lets an intact extracted directory hide a damaged package, and unpack honours --signature, --public-key and --expected-sha256 before it writes a single file.
• On Windows the launcher knows which file it is. It locates itself with GetModuleFileNameW instead of argv[0], which a caller can forge. A bundle carries its own copy of the launcher, so a bundle made before this release has to be rebuilt to pick up the fix. On other platforms the launcher keeps the argv[0] fallback it had before.
• A package cannot turn off its own integrity. A format 6 package whose integrity marker is missing or damaged is refused rather than downgraded to "legacy"; real format 5 packages are still read, with a warning. A non-PE file can no longer dictate the subsystem the launcher reads, because the PE signature and the header bounds are checked before the field is believed.
• Malformed input is damage, not a crash. The LZ4 decoder checks its bounds, caps the expansion of a hostile frame and reads the DictID flag from the bit the format assigns to it. Windows install scripts get their bare file name, so cmd does not read the path as a switch, LUNAPACK_DEST is absolute, and an unreadable --pre-install script fails the command instead of discarding every other option.

#What changed in 0.1.9

• The public key of a pair holds both of its public keys. A pair serves two purposes — the key a package is sealed to, and the key a signature is checked with — and the file held only the first of them. keygen writes both now, and the two are derived from the secret with a label of their own, so the key that opens a package is not the key that signs one.
• The signature of a package holds. In 0.1.8 the signature was checked against the encryption public key, so a signature made with the secret key of the pair never held: the feature was published and it did not work. The Linux end-to-end suite found it, and the chain that the command line walks is held by a unit test now, so it does not depend on a POSIX host to be checked.
• A damaged package says that it is damaged. verify on a file that carries the marker of a package but is not one says so, and a file that carries no marker at all says that it is not a package. The two are not the same thing, and the wording keeps them apart.

#What changed in 0.1.8

• The manifest carries its own integrity. Every package now holds a block with the SHA-256 of its manifest, and a sealed package holds a MAC of it as well. A manifest that was changed is refused, and the reason is named.
• A damaged package is refused instead of being taken for something else. A file that carries the marker of a package but is not one is an error, not a file that is not a package. A bundle that cannot be unpacked does not fall back to printing its usage.
• A package is written in one piece. The package is written into a file of its own, flushed to the disk and only then does it take the place of the target. A target that was a whole package is still a whole package after a crash, and a file that is written is never half-written.
• The cache of a bundle is checked on every start, and the program is checked before it runs. A payload that was changed after it was unpacked is unpacked again, and a program that does not match the package is not started.
• The paths of the entries are checked. A path that walks out of the destination with .. is refused before anything is written.
• Every checksum is computed twice, and the MD5 is computed as well, so that a fault in the machine is not mistaken for a fault in the package.
• The host can sign a package. lunapack sign writes a detached Ed25519 signature next to the package, and lunapack verify --signature checks it. lunapack verify --expected-sha256 checks a digest the host published. Both are checked before the package is opened.
• The Ed25519 implementation is new, and it is checked against vectors that another implementation produced, so a signature that is right here is right against every other implementation of RFC 8032.

#What changed in 0.1.7

• The short coordinate runs. moonx riantr/LunaPack@latest resolves and starts the tool. The root package riantr/LunaPack is now the executable as well as the library, so the registry stores the prebuilt WebAssembly module under the module's own name and there is no second package to name. Before this release the same coordinate failed with "Prebuilt wasm asset does not exist", because the entry point lived in a second package.
• The entry point left cmd/main. The CLI is cli.mbt in the root package and the cmd/ directory is gone. A consumer's import path does not change: import { "riantr/LunaPack" @lib } names the same API, and the generated pkg.generated.mbti is byte-identical to the one 0.1.6 published.
• The price of the short coordinate is named, not hidden. A main package's blackbox tests are on a deprecation path and a dependency that imports a main package is deprecated. Both are described under Packages and targets, with the alternative that avoids them.

#What changed in 0.1.6

• There is a logo. LunaPack.png is what the README shows and what the registry's docs page renders; LunaPack_Logo.png is the same artwork at 1024×1024, for anyone who wants the full-resolution file. Both are published with the module, and the README's image path is relative, so the registry rewrites it to the asset URL.
• A missing interpreter is named in the error. The runtime's spawn failure says "The system cannot find the file specified." and names no file, so a missing sh read like a defect. The error now says which interpreter was missing — cannot run the interpreter \sh`: …` — and the temporary script file is removed on that path too, instead of being left in the installation directory.
• The README was restructured to the shape the sibling riantr/tesseract uses — title, logo, intro, Features, What you get, Install, then the technical sections, Quick Start, Example, Gates and drift detectors, Used By and Attribution — because a reader who has seen one of those modules should not have to learn a second layout. The technical content is the same content; the sections around it are new.

#What changed in 0.1.5

• The single file behaves like the program it carries. The arguments, the exit code, the subsystem and the standard streams of the bundle are the ones of the bundled program, so a windowed application does not flash a console window and a program that asks a question gets an answer.
• The end-to-end suite covers the bundle subcommand and the named launcher. A bundle that is made with --launcher now starts with the launcher that was named — byte for byte — and a launcher that does not exist is refused instead of producing a bundle that cannot start.

#Packages and targets

#Releases

#Publishing to Mooncakes

moon login                 # once
moon publish --dry-run     # validate
moon publish               # publish riantr/LunaPack
moonx riantr/LunaPack@latest --input-exe=... --output-exe=... --Files=...

#The bundle

myapp.exe  =  [ LunaPack launcher ]  +  [ archive: myapp.exe, res/app.cfg, ... ]

$ ./myapp.exe
LunaPack: starting D:/apps/.lunapack/9c445884d23653fb/myapp.exe

#The dependencies of the program

# Only the program and the output: the libraries next to the program are
# found and carried as well.
lunapack --input-exe=./build/myapp.exe --output-exe=./dist/myapp.exe

discovered 2 dependencies next to the program:
  mylib.dll
  otherlib.dll

• the libraries the program imports, and the libraries those libraries import;
• only the ones that are next to the program: a library that is not there is either part of the system or one the program finds somewhere else, and neither is something a bundle can carry;
• not the libraries of the system: the system loads those from its own copy whatever the program carries next to itself;
• not the API sets (api-ms-win-…), whose names the system resolves and whose files do not exist at all.

• a library the program opens with LoadLibrary when it runs;
• every data file it reads — a configuration, a model, an image.

The import table is a Windows thing. A program for Linux names its libraries in the dynamic section of an ELF image and a program for macOS in the load commands of a Mach-O image, and neither is read yet.

#The launcher

# A bundle for Windows, made with the launcher of the release.
lunapack bundle -i ./myapp.exe -o ./myapp.exe \
  --Files=./build --launcher ./lunapack-windows-x86_64.exe

The bundle is self-extracting when the launcher is a native LunaPack binary. The one that runs on this machine is used by default, so a native LunaPack always produces a self-extracting file. A bundle produced through moonx runs on WebAssembly and has no native binary of its own, so it needs one named with --launcher — see above.

Without one, moonx still writes a file that holds the whole payload, and that file does not start on its own: starting it runs the bundled program with none of its files unpacked next to it, which for most programs means it fails at once. The two files look identical from the outside — same name, same size, a whole payload inside — so the last line that the command prints says which of the two was made, and it also goes to stderr. A bundle that is only meant to carry a payload can be unpacked with lunapack unpack; a bundle that is meant to be started needs the launcher.

#Bundling from another module

# The package of the application, as one file. This is the artifact to publish.
moonx riantr/LunaPack@0.1.23 pack -i ./app -o app.appkg

# The self-extracting single file.
moonx riantr/LunaPack@0.1.23 bundle -i ./app.exe -o app.exe --Files=./assets --launcher

# moon.mod
rule(
  name: "lunapack",
  command: "moonx riantr/LunaPack@0.1.23 bundle -i \"$input\" -o \"$output\" --Files=./assets --launcher",
)

# moon.pkg
dev_build(rule: "lunapack", input: "build/app.exe", output: "dist/app.exe")

#A single file that behaves like the program

• The arguments of the bundle are the arguments of the bundled program.
• The exit code of the bundle is the exit code of the bundled program.
• The bundle keeps the console subsystem of the launcher, because a program with no standard streams at all does not survive the start of the runtime on Windows. A bundle that was started by a double-click takes that console away before it starts a program that draws a window, so a windowed program is started without a console window standing next to it, and a console program keeps the window its output goes to.
• The standard input, output and error are the ones of the bundle, so a program that asks a question gets an answer.

$ ./myapp.exe --version
myapp 2.6.0
$ echo $?
0

#The icon

$ lunapack --input-exe=./myapp.exe --output-exe=./myapp.exe --Files=./build
  md5  6b1b1e1f0a2c3d4e5f60718293a4b5c6  myapp.exe
  ...
scanned 392 files
bundled 392 files -> ./myapp.exe (icon copied)
output md5  0f1e2d3c4b5a69788796a5b4c3d2e1f0  myapp.exe

lunapack verify  myapp.exe
lunapack info    myapp.exe
lunapack unpack  -i myapp.exe -o ./out

#The package

#The format

+--------------------+  offset 0
| magic "APPKGD02"   |  8 bytes
+--------------------+  offset 8
| entry payloads     |  stored back to back, raw, gzip, lz4 or sealed
+--------------------+
| integrity block    |  40 bytes, or 72 for a sealed package
+--------------------+
| manifest (UTF-8    |
| JSON)              |
+--------------------+
| magic "APPKGD02"   |  8 bytes
| manifest offset    |  8 bytes, little-endian int64
| manifest length    |  8 bytes, little-endian int64
+--------------------+  end of file

{
  "format_version": 6,
  "name": "myapp",
  "version": "1.4.0",
  "os": "linux",
  "arch": "x86_64",
  "checksum_algo": "sha256",
  "compression": "auto",
  "created_at": "2026-11-04T04:10:20Z",
  "main_program": "myapp.exe",
  "pre_install": { "platform": "posix", "body": "#!/bin/sh\n..." },
  "post_install": null,
  "entries": [
    {
      "path": "res/app.cfg",
      "mode": 420,
      "size": 22500,
      "stored_size": 913,
      "codec": "gzip",
      "checksum": "0a77c24c45d0c61f906862c4706f5dd739166985e8fc5c6344dadd9220507b28",
      "md5": "1520e796ba25554696b3cef6e913cc90",
      "offset": 8
    }
  ]
}

• size is the original file size, stored_size the space it occupies in the package.
• checksum is the SHA-256 of the original content, so it validates the data the user actually gets, not the compressed form.
• md5 is the MD5 fingerprint of the same content. It is a convenience for comparing against what the platform tooling shows, not the integrity guarantee.
• mode holds UNIX permission bits (0o644 / 0o755); they are ignored on Windows.
• main_program names the entry that is the application executable.
• encryption says how the package is sealed, and is null when it is not sealed at all.

#The integrity of a package

# The host signs the package with its secret key.
lunapack sign myapp.appkg --secret-key host.key --output myapp.appkg.sig

# Whoever holds the public key checks the signature.
lunapack verify myapp.appkg --signature myapp.appkg.sig --public-key host.pub

lunapack verify myapp.appkg --expected-sha256 <the digest the host published>

lunapack-public-key v1
x25519 751d2616ba1be8341b35f6cf2d73978e2cccecd1decd0f898b421a99618bc35f
ed25519 a8414c851959a5449aad50fe53b9d976028fd3122248cf87331bd0e0a8ea526e

• A package that was damaged is refused, not taken for a file that is not a package. A bundle that cannot be unpacked is not a program without arguments.
• A package whose manifest was changed is refused, with the reason named.
• A sealed package is refused when the key is wrong, when the manifest was changed, and when a key is given for a package that says it is not sealed. The key is the claim of the reader that the package is encrypted to them, and a package that says the opposite has been changed.
• A path in the manifest that walks out of the destination with .. is refused before anything is written.

#Compression

#Encryption

# Make a pair of keys. The public key goes to the machine that seals the
# packages, the secret key to the machine that opens them.
lunapack keygen --public-key recipient.pub --secret-key recipient.key

# Seal a package to the owner of the public key.
lunapack pack -i ./app -o app.appkg \
  --encryption-method x25519 --public-key recipient.pub

# Open it again with the secret key.
lunapack unpack -i app.appkg -o ./out --secret-key recipient.key

# Or with a passphrase.
lunapack pack -i ./app -o app.appkg \
  --encryption-method passphrase --passphrase-file passphrase.txt
lunapack unpack -i app.appkg -o ./out --passphrase-file passphrase.txt

lunapack-public-key v1
x25519 751d2616ba1be8341b35f6cf2d73978e2cccecd1decd0f898b421a99618bc35f
ed25519 a8414c851959a5449aad50fe53b9d976028fd3122248cf87331bd0e0a8ea526e

lunapack keygen --public-key recipient.pub --secret-key recipient.key \
  --passphrase-file passphrase.txt

#Install scripts

• LUNAPACK_DEST — absolute path of the destination directory
• LUNAPACK_PHASE — pre_install or post_install

#Running it

#Via moonx (published on Mooncakes)

moonx riantr/LunaPack@latest \
  --input-exe=[input-exe-path] \
  --output-exe=[output-exe-path] \
  --Files=[Pack-Folder]

moonx riantr/LunaPack@latest \
  --input-file="x64/Release/App.exe" \
  --output-file="App.exe" \
  --Files="x64/Release"

#The graphical front end (--GUI)

lunapack --GUI
lunapack --GUI --input-file=./myapp.exe --output-file=./myapp-bundle.exe \
         --Files=./assets --compression-method=lz4 --name=demo --version=1.0.0

#The subcommands

lunapack pack   -i <input_dir> -o <output.appkg> [options]
lunapack bundle -i <exe> -o <output.exe> [--Files <dir>]... [options]
lunapack unpack -i <package>   -o <dest_dir>    [--skip-scripts]
lunapack verify <package>      [--extracted <dir>]
lunapack sign   <package>      --secret-key <file> [--output <file>]
lunapack info   <package>
lunapack keygen --public-key <file> --secret-key <file>

Which flag names does bundle actually read? Only -i / --input and -o / --output. The --input-exe, --input-file, --output-exe and --output-file spellings belong to the no-subcommand front end used by moonx riantr/LunaPack@latest ... (and to --GUI, which forwards them to the window). They are in the known-flag list so they are not reported as typos, but do_bundle does not consume them: passing them to bundle produces "bundle requires -i <input_exe> and -o <output_exe>". The examples in this file use the form that matches the command they show.

lunapack verify myapp.exe --extracted .lunapack\b7e21c9f4d0a8356

lunapack sign myapp.appkg --secret-key host.key --output myapp.appkg.sig

lunapack-signature v1
algorithm ed25519
package 0f2a...            <- the SHA-256 of the package
manifest 8c41...           <- the SHA-256 of the manifest
signature 3b90...          <- the Ed25519 signature of the two

verify: OK (392 files)
verify: OK (392 files in .lunapack/b7e21c9f4d0a8356)
VERIFY OK

verify: OK (392 files)
verify: md5 mismatch for appsettings.json: expected 86ff00ef... got 3ddcb685...
verify: FAILED (392 files checked)
VERIFY FAILED

#As a native binary

moon build --release
# -> _build/native/release/build/LunaPack.exe   (every platform)

#Options

#A worked example

# Bundle an application and its resources into one self-extracting file.
lunapack --input-exe=./build/myapp \
         --output-exe=./dist/myapp \
         --Files=./build

# Or produce a plain archive instead.
lunapack pack -i ./myapp -o myapp.appkg \
  --name myapp --version 1.4.0 \
  --pre-install setup.sh --post-install setup.sh

lunapack verify  myapp.appkg
lunapack unpack  -i myapp.appkg -o /opt/myapp

  md5  6f5902ac237024bdd0c176cb93063dc4  a.txt
  md5  3db2050fcf84bb631dcae417d3db518c  sub/b.txt
scanned 2 files
packed 2 files -> myapp.appkg
output md5  63da650c906fe3ab1446b121a4edd4ca  myapp.appkg

unpacked 2 files -> /opt/myapp
  md5  6f5902ac237024bdd0c176cb93063dc4  a.txt
  md5  3db2050fcf84bb631dcae417d3db518c  sub/b.txt
verified 2 files, 0 mismatches

lunapack ^
  --input-exe="D:/src/App/bin/Release/net10.0-windows/App.exe" ^
  --output-exe="D:/dist/App.exe" ^
  --Files="D:/src/App/bin/Release/net10.0-windows"

#Verification

#Every guard was taken out once

#What this is not

• The exit code of a command says whether it worked: 0 when it did, 1 when it did not. The status is on stdout as well (VERIFY OK / VERIFY FAILED / error: ...), so a script that reads the output still works. A single-file bundle reports the exit code of the program it carries, exactly.
• UNIX permission bits cannot be set on Windows, so they are only applied on POSIX hosts.
• The checksum is computed over the original content; verify therefore has to decompress every entry.
• The fingerprint of the produced file is computed while it is written, so the file is never read back for that. The launcher stub is the one exception: it is hashed after the icon was written into it, because writing the icon changes its bytes.
• The big integers of the core are not constant time, so the X25519 of this package is not either. The control flow of the ladder does not depend on the secret, but the time of the arithmetic does. For the use here — a key exchange on the machine that holds the secret key — that is not the threat, but it is a reason to look elsewhere when it is.
• The encryption protects the content of the entries. The names of the entries and their sizes are in the manifest, which is not encrypted.
• The launcher stub is the LunaPack executable of the machine that built the bundle, so a bundle runs on the platform it was created on. Under moonx (Wasm) no native stub exists, so the bundle falls back to carrying the payload inside the application executable — such a bundle holds the data but does not extract itself.
• The extraction cache lives next to the bundle (.lunapack/<hash>/). When that folder cannot be written, the cache of the user is used instead (%LOCALAPPDATA%/LunaPack/cache/<hash>/, or $XDG_CACHE_HOME, $HOME/.cache, or LUNAPACK_CACHE_HOME). That place is the same on every start, so the payload is unpacked once there as well; only when none of them can be written to does the temporary folder of the system take the payload, and that folder is then used for that one start only.
• Copying the icon is Windows only, because an icon is a Windows resource.
• Bundling writes the archive to a temporary file next to the output, so there must be enough free disk space for it.
• The package is built on moonbitlang/core/async, which the toolchain ships as an experimental package. The MoonBit developers have confirmed that the stable releases will use it, so the package follows the toolchain rather than pinning an older release of the runtime.

#Quick Start

moon add riantr/LunaPack

lunapack bundle -i ./build/myapp -o ./dist/myapp --Files ./build
./dist/myapp --version

lunapack --GUI --input-file=./build/myapp --output-file=./dist/myapp --Files=./build

lunapack pack   -i ./myapp -o myapp.appkg
lunapack verify myapp.appkg
lunapack unpack -i myapp.appkg -o /opt/myapp

moon test                                  # 179 tests
moon build --release --target native       # the binary
moon build --release --target wasm         # the WebAssembly module

#Example

///|
async fn main {
  // A plain archive: a directory, compressed per entry, checksummed per entry.
  let opts = @lp.new_pack_options(
    "myapp", // the name of the package
    "1.4.0", // the version of the package
    "linux", // the os tag
    "x86_64", // the arch tag
    None, // the pre-install script
    None, // the post-install script
    "auto", // the compression
  )
  @lp.pack("./myapp", "myapp.appkg", opts)

  // The same application as a single self-extracting file. The launcher is the
  // running program itself, and the main program is recorded by the bundle.
  @lp.bundle("./build/myapp", "./dist/myapp", ["./build"], opts, "")

  // Read the manifest back, and check the package.
  let m = @lp.read_package_manifest("myapp.appkg")
  let ok = @lp.verify("myapp.appkg", None)
  @lp.unpack("myapp.appkg", "/opt/myapp", true, None)
}

///|
async fn main {
  match @lp.probe_archive("./dist/myapp") {
    Some((offset, manifest)) => {
      println("the archive starts at " + offset.to_string())
      println("it holds " + manifest.entries.length().to_string() + " entries")
    }
    None => println("this file carries no LunaPack archive")
  }
}

///|
async fn main {
  let m = @lp.read_package_manifest("secret.appkg")
  match m.encryption {
    Some(info) => {
      let key = @lp.recover_encryption(info, "recipient.key", "")
      @lp.unpack("secret.appkg", "./out", true, Some(key))
    }
    None => ()
  }
}

#Gates and drift detectors

#Used By

• cli.mbt — the command line of this module, the front end over the library that lives in the same package.
• integrity.mbt — the integrity block: the digest and the MAC of the manifest, and the checksums that are computed twice.
• ed25519.mbt — the signature that the host publishes next to a package.
• signature.mbt — the signature file and the checks of the host material.
• scripts/test_linux.sh — the end-to-end suite, which drives the binary that the module builds.
• scripts/mutation_battery.ps1 — the development tool that takes every guard out of the code once and checks that the test covering it goes red.

#Attribution

• License: MIT (see LICENSE).
• The mechanism of the encryption and the shape of the container follow the reference implementation this package follows. Every primitive it needs is implemented in this package, because the MoonBit toolchain ships none of them, and each one is checked against the vector that its standard publishes.
• The LZ4 codec is an implementation of the format, not a port of a library: what it produces is a standard .lz4 frame, and the test suite checks the frames against the values the format publishes.
• The Ed25519 signature is an implementation of RFC 8032, not a port of a library. It is checked against vectors that another implementation produced, so a signature that is right here is right against every other implementation of the standard.