buninu 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.1.8 - 2026-08-17
+
+### Changed
+
+- Run an optional `libmain.so` from Android's native-library PATH at startup,
+  falling back to the normal Android welcome message when it is unavailable.
+
+## 0.1.7 - 2026-08-17
+
+### Added
+
+- Add `buninu --export [output.tgz]` to create a gzip-compressed tar archive of
+  the current Buninu installation. The archive retains exactly one top-level
+  directory and defaults to `./buninu.tgz`. An existing output is backed up and
+  restored if archive creation or replacement fails.
+- Add `apps/cmdlist` as the validated source of POSIX multicall commands.
+  Normal startup now recreates every listed command as a `shloader` symlink,
+  including after npm installs that omit package symlinks.
+- Add the Buninu-only `# syntax: markdown` first-line marker for Markdown
+  highlighting in extensionless files such as `apps/cmdlist`.
+
+### Changed
+
+- Update the default and Android startup greetings to point users to
+  `glow apps/cmdlist`.
+- Update `musl-la` to prefer Android's native `libld-musl.so`, fall back to the
+  bundled loader, add the target ELF directory and existing `LD_LIBRARY_PATH`
+  to its library search path, and support `-e` for the environment-variable
+  launch mode.
+- Document how to add POSIX multicall commands and their separate Windows
+  batch launchers.
+
+### Fixed
+
+- Keep the POSIX startup wrapper and Android greeting command on one line so
+  process listings do not expose embedded LF (`Ctrl+J`) characters.
+
 ## 0.1.5 - 2026-08-16
 
 ### Fixed

package/README.md

@@ -4,14 +4,13 @@
 
 > **Early development:** Buninu is still at an early stage of development.
 > Features, configuration, and command-line behavior may change between releases.
-> The current early release implements and supports Linux first. Android and
-> Windows support are planned, but are not ready yet.
+> Linux, Android, and Windows can run the current early implementation, but
+> their support and portability behavior are still being tested and refined.
 
 - Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun that runs across operating systems
 
 - It starts a browser-accessible terminal through jsgotty. The architecture is
-  designed for Android, Linux, and Windows, but the current implementation is
-  Linux-only.
+  designed for Android, Linux, and Windows.
 
 - Name expansions:
   * English: **BUNinu Is Not Unix** 🐮
@@ -29,10 +28,14 @@ and self-bootstrapping design.
 ## Differences from upstream
 
 ### The bundled jsmdcui
+
   * Is configured editor-first by MDCUI_DEFAULT_EDIT
   * The command `jmi` with a Markdown file opens the normal terminal editor.(js micro editor)
   * The command `jsmdcui` preserves its original behavior: `apps/jsmdcui/jsmdcui.sh`, which starts its `tui` entry point with `--mdcui` when running markdown Apps, and forwards all command-line arguments.
+  * Adds the Buninu-only `# syntax: markdown` marker for Markdown highlighting in extensionless files; upstreaming may be considered later.
+
 ### The bundled jsgotty
+
   * No longer depends on or ships `node-pty`. 
   * Its PTY is provided by Bun's terminal API.
 
@@ -69,14 +72,114 @@ npx buninu --credential user:pass
 npx buninu --port 9000
 ```
 
+## Command-line information
+
+```text
+-h, --help       Show command-line help
+-V, --version    Show the Buninu, Bun, platform, and architecture versions
+--readme          Render README.md in the terminal
+--changelog       Render CHANGELOG.md in the terminal
+```
+
+## Export
+
+Export the current Buninu installation as a gzip-compressed tar archive:
+
+```sh
+npx buninu --export
+npx buninu --export /path/to/buninu.tgz
+```
+
+The default output is `./buninu.tgz`. The archive contains exactly one
+top-level directory so consumers can remove one component while extracting.
+Export requires `tar` in `PATH`; when replacing an existing output,
+Buninu restores the previous file if archive creation or replacement fails.
+
 ## Environment
 
 `BUNINU_HOME` is the absolute path to the installed Buninu package root.
 The jsgotty process, startup command, and interactive shell start with this
 directory as their working directory. Buninu also appends
-`$BUNINU_HOME/bin` to `PATH`.
+`$BUNINU_HOME/bin` to `PATH` (`Path` on Windows).
+
+Buninu preserves inherited environment variables and supplies these fallbacks:
+
+- `HOME`: inherited value, or `BUNINU_HOME` when unset.
+- `TMPDIR`: inherited value; on Android, use the app cache directory when it
+  exists or `$BUNINU_HOME/tmp` otherwise; on other platforms, use the system
+  temporary directory.
+- `SHELL`: inherited value, or a detected platform-appropriate shell.
+- `TERM`: `xterm-256color` when unset.
+- `COLORTERM`: `truecolor` when unset.
+
+The Buninu Android APK launcher also supplies user-aware external-storage
+paths obtained from Android APIs:
+
+- `PKG_DDIR`: `/storage/emulated/<user-id>/Android/data/<package>`.
+- `PKG_MDIR`: `/storage/emulated/<user-id>/Android/media/<package>`.
+
+## Add a command
+
+On POSIX systems, Buninu exposes its commands through the multicall
+`shloader`. The command names are listed one per line in `apps/cmdlist`:
+
+```text
+# syntax: markdown
+
+# Lines beginning with # are comments
+glow
+jsgotty
+jsmdcui
+```
+
+Blank lines and comment lines are ignored. Keep comments on their own lines;
+inline comments are not supported. Command names may contain ASCII letters,
+digits, `.`, `_`, and `-`, and must begin with a letter or digit.
+
+For example, to add a command named `hello`, create
+`apps/hello/hello.js`:
+
+```js
+console.log("Hello from Buninu");
+```
+
+Then add its name to `apps/cmdlist`:
+
+```text
+hello
+```
+
+Restart Buninu normally. During startup, `bin/init.js` reads the list and
+rebuilds `bin/hello` as a symbolic link to `shloader`. The command is then
+available from the Buninu shell:
+
+```sh
+hello
+```
+
+The multicall loader looks for an implementation in this order:
+
+```text
+bin/hello.sh
+apps/hello/hello.sh
+apps/hello/hello.js
+apps/hello/hello.mjs
+apps/hello/hello.ts
+apps/hello/hello.mts
+```
 
-## Startup command
+Running only an information option such as `--help` or `--version` does not
+rebuild links; start Buninu normally at least once after changing the list.
+Windows does not use these POSIX symbolic links. To expose the same command
+on Windows, also provide `bin/hello.bat`, for example:
+
+```bat
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\hello\hello.js" %*
+exit /b %ERRORLEVEL%
+```
+
+## Startup command (optional)
 
 Set `buninu.command.default` or a platform-specific value (`android`, `linux`,
 or `windows`) in `package.json` to run a complete shell command from
@@ -104,7 +207,7 @@ Override it for one run with:
 bun ./bin/init.js --command "echo temporary command"
 ```
 
-## Shell selection
+## Shell selection (optional)
 
 Set `buninu.shell.default` or a platform-specific value (`android`, `linux`,
 or `windows`) in `package.json`. A relative shell path is resolved
@@ -122,3 +225,12 @@ from the directory containing `package.json`.
 ```
 
 Use `--shell <path-or-name>` for a one-time override.
+
+## Process-list helpers
+
+The bundled `.bashrc` provides `pspa` (`ps -eo pid,args`) and `pspac`, which
+writes that process list to `$HOME/.pspidargs.sh` and displays it with `glow`.
+Buninu preserves an existing `HOME` rather than replacing or modifying the
+user's home; shells that honor `ENV` load the bundled file, while interactive
+Bash may load only `$HOME/.bashrc`, so add `. "$BUNINU_HOME/.bashrc"` to a
+custom Bash configuration when these aliases are not available.

package/apps/cmdlist

@@ -0,0 +1,16 @@
+# syntax: markdown
+
+### glow — Render files with jsmdcui syntax highlighting
+glow
+
+### jmi — Open files in the js micro editor
+jmi
+
+### jsgotty — Run a browser-accessible terminal
+jsgotty
+
+### jsmdcui — Edit and run interactive Markdown applications
+jsmdcui
+
+### musl-la — Launch AArch64 ELF programs with the bundled musl loader
+musl-la

package/apps/jsmdcui/runtime/syntax/markdown.yaml

@@ -2,6 +2,7 @@ filetype: markdown
 
 detect:
     filename: "\\.(livemd|md|mkd|mkdn|markdown)$"
+    header: "^# syntax: markdown$"
 
 rules:
     # Tables (Github extension)

package/apps/musl-la/musl-la.sh

@@ -2,4 +2,35 @@
 
 sd=$(dirname "$(realpath "$0")")
 
-exec "$sd"/ldmusl --library-path "$sd" "$@"
+muslbin=$sd/../../bin/androidNativeLibs/libld-musl.so
+
+if [ ! -f "$muslbin" ] ; then
+  muslbin=$sd/ld-musl-aarch64.so.1
+fi
+
+use_env=
+if [ "$1" = -e ] ; then
+  shift
+  use_env=1
+fi
+
+elfdir=
+for arg do
+  if [ -f "$arg" ] ; then
+    elf_magic=$(od -A n -t x1 -N 4 "$arg" 2>/dev/null | tr -d '[:space:]')
+    if [ "$elf_magic" = 7f454c46 ] ; then
+      elfdir=$(dirname "$(realpath "$arg")")
+      break
+    fi
+  fi
+done
+
+library_path=$sd${elfdir:+:$elfdir}${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
+
+if [ "$use_env" = 1 ] ; then
+  LD_LIBRARY_PATH=$library_path
+  export LD_LIBRARY_PATH
+  exec "$muslbin" "$@"
+fi
+
+exec "$muslbin" --library-path "$library_path" "$@"

package/bin/init.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import pkg from "../package.json" with { type: "json" };
-import { existsSync, lstatSync, mkdirSync, symlinkSync, unlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, unlinkSync } from "node:fs";
 import { tmpdir as systemTmpDir } from "node:os";
 import { basename, delimiter, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,6 +26,7 @@ Init options:
   -V, --version          Show version and runtime information, then exit
   --readme               Render README.md in the terminal and exit
   --changelog            Render CHANGELOG.md in the terminal and exit
+  --export [output.tgz]  Export this Buninu installation (default: ./buninu.tgz)
   --shell <path|name>    Override buninu.shell for this run
   --command <command>    Override buninu.command for this run
 
@@ -54,6 +55,12 @@ async function handleInformationArguments(arguments_) {
     return true;
   }
 
+  const exportOption = readExportArgument(arguments_);
+  if (exportOption) {
+    await exportInstallation(exportOption.output);
+    return true;
+  }
+
   if (arguments_.includes("--readme")) {
     const readmePath = resolve(REPO_ROOT, "README.md");
     if (!await pathExists(readmePath)) fail(`README not found: ${readmePath}`);
@@ -75,6 +82,61 @@ async function handleInformationArguments(arguments_) {
   return false;
 }
 
+function readExportArgument(arguments_) {
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === "--export") {
+      const next = arguments_[index + 1];
+      return { output: next || "buninu.tgz" };
+    }
+    if (argument.startsWith("--export=")) {
+      const output = argument.slice("--export=".length);
+      if (!output) fail("--export= requires an output path");
+      return { output };
+    }
+  }
+  return null;
+}
+
+async function exportInstallation(output) {
+  const outputPath = resolve(process.cwd(), output);
+  const tar = Bun.which(process.platform === "win32" ? "tar.exe" : "tar") || Bun.which("tar");
+  if (!tar) fail("tar was not found in PATH");
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+  const temporaryDir = mkdtempSync(resolve(systemTmpDir(), "buninu-export-"));
+  const temporaryArchive = resolve(temporaryDir, "buninu.tgz");
+  const temporaryBackup = resolve(temporaryDir, "previous-output.tgz");
+  const hadExistingOutput = existsSync(outputPath);
+  let exportError = null;
+  try {
+    // Keep the previous output recoverable, but remove it from its original
+    // path while tar walks REPO_ROOT so an in-tree export cannot include itself.
+    if (hadExistingOutput) {
+      if (!lstatSync(outputPath).isFile()) throw new Error(`export path is not a file: ${outputPath}`);
+      await Bun.write(temporaryBackup, Bun.file(outputPath));
+      unlinkSync(outputPath);
+    }
+    const process_ = Bun.spawn(
+      [tar, "-czf", temporaryArchive, "-C", dirname(REPO_ROOT), basename(REPO_ROOT)],
+      { env: { ...process.env }, stdin: "inherit", stdout: "inherit", stderr: "inherit" },
+    );
+    const status = await process_.exited;
+    if (status !== 0) throw new Error(`tar failed with exit ${status}`);
+    await Bun.write(outputPath, Bun.file(temporaryArchive));
+  } catch (error) {
+    exportError = error;
+    if (hadExistingOutput && await pathExists(temporaryBackup)) {
+      await Bun.write(outputPath, Bun.file(temporaryBackup));
+    }
+  } finally {
+    rmSync(temporaryDir, { recursive: true, force: true });
+  }
+
+  if (exportError) fail(exportError?.message || String(exportError));
+  console.log(outputPath);
+}
+
 function splitCommand(command) {
   const words = [];
   let word = "";
@@ -222,7 +284,7 @@ async function runPlatformSwitch(environment) {
   }
 }
 
-function rebuildNativeSymlinks(environment) {
+async function rebuildNativeSymlinks(environment) {
   if (environment.name === "windows") return;
 
   const platformLinks = environment.name === "android"
@@ -234,14 +296,27 @@ function rebuildNativeSymlinks(environment) {
         bun: "bun.sh",
         shloader: "multicall.sh",
       };
-  const links = {
-    ...platformLinks,
-    glow: "shloader",
-    jmi: "shloader",
-    jsgotty: "shloader",
-    jsmdcui: "shloader",
-    "musl-la": "shloader",
-  };
+  const cmdlistPath = resolve(rootDir, "apps", "cmdlist");
+  if (!await pathExists(cmdlistPath)) {
+    fail(`command list does not exist: ${cmdlistPath}`);
+  }
+
+  const commandNames = [...new Set(
+    (await Bun.file(cmdlistPath).text())
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#")),
+  )];
+  for (const name of commandNames) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+      fail(`invalid command name in ${cmdlistPath}: ${name}`);
+    }
+  }
+
+  const links = Object.fromEntries([
+    ...Object.entries(platformLinks),
+    ...commandNames.map((name) => [name, "shloader"]),
+  ]);
 
   for (const [name, target] of Object.entries(links)) {
     const linkPath = resolve(binDir, name);
@@ -369,16 +444,14 @@ function shellCommandArguments(shell, command) {
   }
 
   const wrapped =
-    `(\n${command}\n)\n` +
-    `status=$?\n` +
-    `if [ "$status" -ne 0 ]; then\n` +
-    `  echo "buninu: startup command failed with exit $status" >&2\n` +
-    `fi\n` +
-    `exec "$0"`;
-  // The argument after the command string becomes $0. Passing the shell path
-  // as argv avoids interpolating or quoting an executable path inside the
-  // user's shell command.
-  return [shell, "-c", wrapped, shell];
+    `buninu_command=$1; shift; ( eval "$buninu_command" ); status=$?; ` +
+    `if [ "$status" -ne 0 ]; then ` +
+    `echo "buninu: startup command failed with exit $status" >&2; ` +
+    `fi; exec "$0"`;
+  // Pass both the shell and startup command as argv instead of interpolating
+  // them into the wrapper. This keeps the wrapper single-line and avoids LF
+  // (Ctrl+J) characters in its process-list representation.
+  return [shell, "-c", wrapped, shell, command];
 }
 
 const startScript = pkg.scripts?.start;
@@ -396,7 +469,7 @@ if (command[0] === "bun") command[0] = process.execPath;
 
 const environment = await detectEnvironment();
 await runPlatformSwitch(environment);
-rebuildNativeSymlinks(environment);
+await rebuildNativeSymlinks(environment);
 const initArguments = readInitArguments(process.argv.slice(2));
 const configuredShell =
   pkg.buninu?.shell?.[environment.name] ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun that runs across operating systems",
   "type": "module",
   "main": "./bin/init.js",
@@ -17,8 +17,8 @@
       "windows": null
     },
     "command": {
-      "default": null,
-      "android": "echo Welcome to Buninu Android",
+      "default": "echo Welcome to Buninu, Try: glow apps/cmdlist",
+      "android": "if command -v libmain.so >/dev/null 2>&1; then libmain.so; else printf '%s\\n' '# Welcome to Buninu Android' '- Try: glow apps/cmdlist'; fi",
       "linux": null,
       "macos": null,
       "windows": null