jsmdcui 0.8.0 → 0.10.1

package/single-exe/README.md

@@ -1,27 +1,276 @@
-# This is completely optional
-- I still recommend using the methods in the root README.md
-- Bun's Android build is currently not supported
+# Bun Single-File Executable Bootstrap
 
-# Usage
-- First run `bun ./packAssets.sh` to bundle the assets into `assets.tar`
-- Then run the build script like this
+Build a Bun application and its runtime assets into one executable while
+keeping the regular main module free of Bun-specific asset imports.
 
-  ```shell
-  bun build --compile --bytecode --minify ./entry.mjs --outfile=binname
-  ```
+You can copy and adapt this build setup for your own project by changing its
+main-module path and asset list as described below.
 
-- You'll get a binname executable
+- Bundle an asset tree alongside the application code in one executable.
+- Keep the regular main module available to the Node.js ESM execution path.
+- Read embedded resources first with an optional external-file fallback.
+- List, extract, or bypass embedded assets with built-in CLI flags.
+- Build for the current platform or pass a Bun cross-compilation target.
 
-# Single Executable Intro
+> This workflow is optional; the standard methods in the root README remain
+> available. Bun's Android build is currently not supported.
 
-This folder contains the Bun single-exe bootstrap used by the project.
+## Quick start for jsmdcui
+
+From the repository root, build for the current platform:
+
+```shell
+bun ./src/index.js --build-exe
+./mdcui --version
+```
+
+`--build-exe` runs `packAssets.sh` automatically and writes the `mdcui`
+executable to the current directory. To pass a Bun compilation target, use:
+
+```shell
+bun ./src/index.js --build-for <target>
+```
+
+Any additional arguments after `--build-exe`, or after the target passed to
+`--build-for`, are forwarded to the `bun build` command:
+
+```shell
+bun ./src/index.js --build-exe --sourcemap
+bun ./src/index.js --build-for <target> --sourcemap
+```
+
+The following presence-based build constants select distribution defaults:
+
+- `MDCUI_DEFAULT_EDIT`: open files as editable text by default.
+- `MDCUI_DEFAULT_DEMO`: add `--demo` when launched without arguments.
+- `MDCUI_DEFAULT_DEMO_WUI`: add `--wui` when launched without arguments.
+
+Choose only one of these three default-mode constants for each build.
+`MDCUI_OVERWRITE_DEMO` is an optional modifier for a demo or WUI build.
+
+For example, build a default text editor with:
+
+```shell
+bun ./src/index.js --build-exe \
+  --define MDCUI_DEFAULT_EDIT=true
+```
+
+To build a bundled terminal demo that replaces its local copy:
+
+```shell
+bun ./src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+`MDCUI_DEFAULT_DEMO=true` makes an executable launched without arguments behave
+as if `--demo` was passed. `MDCUI_OVERWRITE_DEMO=true` makes every selected demo
+replace an existing local copy; it does not select a demo by itself.
+
+For a browser UI that automatically adds `--wui` when launched without
+arguments, use `MDCUI_DEFAULT_DEMO_WUI` instead:
+
+```shell
+bun ./src/index.js --build-exe \
+  --define MDCUI_DEFAULT_DEMO_WUI=true \
+  --define MDCUI_OVERWRITE_DEMO=true
+```
+
+To perform the same steps manually, run these commands from `single-exe/`:
+
+```shell
+bun ./packAssets.sh
+bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=mdcui
+```
+
+## Adapting this folder to another project
+
+This folder is a reusable starting point, not a drop-in package. The current
+`entry.mjs` and `packAssets.sh` contain jsmdcui paths, so another project must
+complete the following integration steps.
+
+The adopting project needs Bun for packing and compiling, a `tar` command for
+`packAssets.sh`, and an ES-module setup. Keep `"type": "module"` in
+`package.json`, or rename the copied `.js` modules to `.mjs` and update their
+imports. The supported uncompiled Node path requires Node.js 20.11 or newer
+because `compiled.js` uses `import.meta.dirname`.
+
+`assetsHelper.js` and `compiled.js` are Node-compatible under those conditions.
+`assetsLoader.mjs` and `entry.mjs` are Bun-only and must not be imported by the
+regular Node entry path.
+
+### 1. Copy the bootstrap directory
+
+Copy the entire `single-exe/` directory to the root of the other project and
+keep its name and relative position unless you also update the paths in
+`compiled.js` and `packAssets.sh`. A typical layout is:
+
+```text
+my-project/
+├── single-exe/
+│   ├── assetsHelper.js
+│   ├── assetsLoader.mjs
+│   ├── compiled.js
+│   ├── entry.mjs
+│   └── packAssets.sh
+└── src/
+    └── index.js
+```
+
+`assets.tar` is generated by `packAssets.sh`; it does not need to exist before
+the first packing step.
+
+### 2. Point `entry.mjs` at the main program
+
+Keep the asset loader as the first import and change the path passed to the
+final `await import()` so it points to the other project's real entry module:
+
+```js
+#!/usr/bin/env bun
+
+import "./assetsLoader.mjs";
+await globalThis.assetsLoaderPromise;
+await import("../src/index.js");
+```
+
+> **Important:** Keep the final import dynamic. Do not replace it with a static
+> `import "../src/index.js"`, because static dependencies are evaluated before
+> the asset Promise is awaited.
+
+Only the Bun single-file executable build should use this bootstrap entry.
+Continue to run the regular main module directly when using Node:
+
+```shell
+node ./src/index.js
+```
+
+### 3. Choose which files to embed
+
+Edit the resource list in `packAssets.sh`; the script runs `tar` for you. It
+changes to the project root, writes `single-exe/assets.tar`, and packs every
+listed runtime resource required by the compiled program. Paths stored in the
+archive become the lookup keys used by `assetsHelper.js`; use keys such as
+`public/app.css`, without a leading `./`. The normal `--build-exe` and
+`--build-for` flows invoke this script automatically, so you do not need to run
+`tar` yourself.
+
+For example:
+
+```sh
+#!/bin/sh
+
+script_dir=$(dirname "$0")
+cd "$script_dir/.." || exit 1
+
+tar -cvf single-exe/assets.tar public templates README.md
+```
+
+Do not retain jsmdcui's `demos`, `runtime`, `src/cui`, or `testapp.md` entries
+unless the adopting project actually contains and needs them.
+
+### 4. Read embedded assets with an external fallback
+
+Import the Node-compatible helpers from `assetsHelper.js`. They return `null`
+when the embedded store is unavailable or a path is not present:
+
+```js
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readInternalAssetText } from "../single-exe/assetsHelper.js";
+import { REPO_ROOT } from "../single-exe/compiled.js";
+
+async function readResourceText(path) {
+  return readInternalAssetText(path) ??
+    await readFile(resolve(REPO_ROOT, path), "utf8");
+}
+```
+
+In the source tree, `REPO_ROOT` is the project root. In a compiled executable,
+it is the executable's directory, which is also where `--assets-extract`
+places the external resource tree. Apply the same embedded-first fallback to
+every file that must work in both modes. Use `readInternalAssetBytes()` when
+a resource should be returned as bytes instead of decoded text.
+Use `listInternalAssetPaths()` to list embedded asset paths and
+`listInternalAssetDirs()` to list embedded directories.
+
+### 5. Add the optional build commands to the regular CLI
+
+Before normal argument parsing, call `buildEarlyExit` from the regular main
+module:
+
+```js
+const compiledHelper = await import("../single-exe/compiled.js").catch(() => null);
+await compiledHelper?.buildEarlyExit?.(process.argv, "my-bin");
+```
+
+The second argument is the output filename; it defaults to `single.exe` when
+omitted. This enables:
+
+```shell
+bun ./src/index.js --build-exe
+bun ./src/index.js --build-for <target>
+```
+
+Both commands run `packAssets.sh` before `bun build`. The second form passes
+`<target>` through as Bun's `--target=<target>` value.
+
+Alternatively, build manually from inside `single-exe/`:
+
+```shell
+bun ./packAssets.sh
+bun build --format=esm --compile --minify --bytecode ./entry.mjs --outfile=my-bin
+```
+
+### 6. Verify both execution paths
+
+Verify the compiled asset archive and then run the program normally:
+
+```shell
+./my-bin --assets-list
+./my-bin
+```
+
+Also run the uncompiled main module with Node.js 20.11 or newer to verify that
+all required files have a working external fallback:
+
+```shell
+node ./src/index.js
+```
+
+Use `./my-bin --assets-extract` to write the packed tree beside the executable.
+After extraction, `./my-bin --assets-external` skips the embedded store and is
+useful for testing the external-resource path.
+
+### Why `assetsLoaderPromise` is used
+
+A more tightly coupled ESM design could export the assets with top-level
+`await`, then make the main module import `assetsLoader.mjs` directly. This
+project deliberately does not do that because `assetsLoader.mjs` contains
+Bun's compiled-file import:
+
+```js
+import assets from "./assets.tar" with { type: "file" };
+```
+
+If the regular main module imported `assetsLoader.mjs`, that Bun-specific
+`type: "file"` dependency would enter the main module graph. Node would then be
+unable to load the program before it could select an external-file fallback.
+
+Instead, only Bun's `entry.mjs` imports the Bun-specific loader, awaits its
+Promise, and then dynamically imports the regular main module. The main module
+does not import the loader, inspect the Promise, or contain Bun bootstrap code.
+Under the supported Node.js 20.11+ ESM path, Node runs that clean main module
+directly with external files. The Promise is therefore an intentional
+Node-compatibility boundary inside the Bun-only bootstrap, not a failure to use
+a more modern dependency or top-level-`await` design.
 
 ## Entry Flow
 
 - `entry.mjs` imports `assetsLoader.mjs` first
 - `assetsLoader.mjs` loads `assets.tar` with `Bun.Archive` and mounts it as `globalThis.internalAssets`
 - `assetsLoaderPromise` is exposed on `globalThis`
-- The main program waits for `assetsLoaderPromise` if it exists
+- `entry.mjs` awaits `assetsLoaderPromise`
+- `entry.mjs` dynamically imports the main program after the assets are ready
 
 That keeps the main program bootable even if asset loading reports errors.
 
@@ -32,6 +281,12 @@ That keeps the main program bootable even if asset loading reports errors.
 - Asset loading never rejects the bootstrap promise
 - When loading succeeds, the archive is available through `globalThis.internalAssets`
 
+This loader is not zero-copy: it materializes every bundled file in memory and
+keeps the resulting bytes in `globalThis.internalAssets`. Large asset archives
+can therefore increase startup and ongoing RAM usage. For workloads where that
+matters, I also wrote an experimental Linux-only zero-copy hack:
+[bun-assets-zerocopy](https://github.com/jjtseng93/bun-assets-zerocopy).
+
 ## CLI Flags
 
 - `--assets-list`
@@ -46,35 +301,3 @@ That keeps the main program bootable even if asset loading reports errors.
   - Skips loading bundled assets into `globalThis.internalAssets`
   - Forces the main program and runtime helpers to use the external file tree
   - Keeps the bootstrap alive while leaving `internalAssets` falsy
-
-## Adapting this folder
-
-This single-exe folder is intended for reuse by other projects. Usually you
-only need to edit these project-specific files first:
-
-- `entry.mjs`
-- `packAssets.sh`
-
-Then the main program can import `buildEarlyExit` from `compiled.js` and call
-it before normal CLI parsing. `--build-exe` and `--build-for <target>` will run
-`packAssets.sh` first, so `assets.tar` is generated as part of the build flow.
-
-```js
-const compiledHelper = await import("./single-exe/compiled.js").catch(() => null);
-await compiledHelper?.buildEarlyExit?.(process.argv, "my-bin");
-```
-
-- `--build-exe` builds with no Bun target.
-- `--build-for <target>` passes `<target>` to `bun build --target=<target>`.
-- The second argument is the output filename. If omitted, it defaults to `single.exe`.
-
-The main program should also switch its repo/resource root when running as a
-compiled binary. Use `IS_COMPILED` and `REPO_ROOT` from
-`compiled.js`; when compiled, treat the executable directory as the repo root
-used for external fallback files such as `static/`, `README.md`, or other files
-packed by `packAssets.sh`.
-
-```js
-const compiledHelper = await import("./single-exe/compiled.js").catch(() => null);
-const repoRoot = compiledHelper?.REPO_ROOT
-```

package/single-exe/compiled.js

@@ -12,9 +12,12 @@ const SINGLE_EXE_DIR = resolve(REPO_ROOT, "single-exe");
 const SINGLE_EXE_ENTRY = resolve(SINGLE_EXE_DIR, "entry.mjs");
 
 
-export function isCompiledBinary() {
-  const argv = process.argv
-  return Boolean(argv?.[1]?.startsWith?.("/$bunfs/"));
+export function isCompiledBinary(argv = process.argv) {
+  const entry = argv?.[1];
+  return Boolean(
+    entry?.startsWith?.("/$bunfs/") ||
+    entry?.startsWith?.("B:/~BUN")
+  );
 }
 
 export function getExeDirname() {
@@ -35,10 +38,11 @@ export function getDirnameFromUrl(importMetaUrl) {
   return dirname(fileURLToPath(importMetaUrl));
 }
 
-export async function buildExecutable(target = "",build_outfile="single.exe") {
+export async function buildExecutable(target = "",build_outfile="single.exe", bunArgs = []) {
  
   const outfile = resolve(process.cwd(), build_outfile);
   const normalizedTarget = String(target || "").trim();
+  const extraBunArgs = Array.from(bunArgs ?? [], String);
   if(!globalThis.Bun || IS_COMPILED)
   {
     console.log("Build exe can only be run by Bun in the source tree");
@@ -68,6 +72,7 @@ export async function buildExecutable(target = "",build_outfile="single.exe") {
         `--outfile=${outfile}`,
         `--metafile-md=${outfile}.meta.md`,
         ...(normalizedTarget ? [`--target=${normalizedTarget}`] : []),
+        ...extraBunArgs,
       ],
     },
   ];
@@ -142,8 +147,8 @@ export async function buildEarlyExit(argv,build_outfile) {
       console.error("Missing target value for --build-for");
       process.exit(2);
     }
-    process.exit(await buildExe(target,build_outfile));
+    process.exit(await buildExe(target, build_outfile, argv.slice(buildForIndex + 2)));
   }
 
-  process.exit(await buildExe(null,build_outfile));
+  process.exit(await buildExe(null, build_outfile, argv.slice(buildExeIndex + 1)));
 }

package/single-exe/entry.mjs

@@ -3,7 +3,8 @@
 // 1. Injects assets to global.internalAssets
 //   as { "./path/in/tar":file.bytes() }
 // 2. Sets global.assetsLoaderPromise
-import "./assetsLoader.mjs"
-
-import "../src/index.js"
+// 3. Starts the main program only after the assets are ready
+import "./assetsLoader.mjs";
 
+await globalThis.assetsLoaderPromise;
+await import("../src/index.js");

package/single-exe/packAssets.sh

@@ -4,4 +4,4 @@ sd=$(dirname "$0")
 
 cd "$sd"/..
 
-tar -cvf single-exe/assets.tar demos runtime README.md CHANGELOG.md src/cui/server.mjs src/cui/rpc.mjs testapp.md
+tar -cvf single-exe/assets.tar demos runtime README.md CHANGELOG.md cdp-maze.js src/cui/server.mjs src/cui/rpc.mjs testapp.md

package/src/cui/kitty-debug.mjs

@@ -1,7 +1,7 @@
 import { appendFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-export const KITTY_DEBUG_LOG = resolve(import.meta.dir, "../..", "kitty-placement.log");
+export const KITTY_DEBUG_LOG = resolve(import.meta.dirname, "../..", "kitty-placement.log");
 export const KITTY_DEBUG_ENABLED = /^(1|true|yes|on)$/i.test(
   String(process.env.JSMDCUI_KITTY_DEBUG ?? ""),
 );