buninu 0.1.9 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.2.2 - 2026-08-17
+
+### Added
+
+- Add a "Commands inside the shell" section to README.md, split out of
+  Command-line information (which is only `bin/init.js`'s own flags, resolved
+  before Buninu starts). Lists everything in `apps/cmdlist` and moves the
+  `buninu-help`/`bunx` write-ups there, including a note that `bunx` can't
+  install anything on Android until
+  [oven-sh/bun#39084](https://github.com/oven-sh/bun/pull/39084) merges
+  upstream (Android's seccomp policy kills `bun i -g` with SIGSYS during bin
+  linking until then).
+
+## 0.2.1 - 2026-08-17
+
+### Added
+
+- Add `bunx`, a POSIX and Windows multicall command that ensures a package is
+  installed via `bun i -g` and then runs its matching binary, forwarding the
+  remaining arguments. Reinstall timing is adapted from real bunx's own rules
+  (an explicit dist-tag like `@latest` always reinstalls; otherwise a cached
+  binary is reused until it's older than 24h, or stat fails, or bun's own
+  `install/global/package.json` shows a different pinned version than the one
+  requested — this script has one shared install location instead of bunx's
+  per-version cache, so this last check substitutes for that). The global bin
+  directory is resolved via `bun pm bin -g`, falling back to
+  `$BUN_INSTALL`/`$HOME/.bun` on the very first install before that project
+  exists (which `bun pm bin -g` requires).
+  - Runs the target through `bun <target>` instead of exec'ing it directly:
+    on Android the resolved binary typically sits under storage mounted
+    noexec, so a direct exec is refused even though the file is readable and
+    executable-bit set. Trade-off: a package whose bin is a real native
+    executable rather than a JS/bun script won't run this way.
+  - On Android (detected the same way as `bin/init.js`, via
+    `/system/bin/linker64`), installs with `--backend=copyfile` since
+    hardlinks/symlinks frequently fail across Android's storage, and sets
+    `$PREFIX=/data/data/com.termux/files/usr` for the target process (not the
+    install step) so CLIs that check for a Termux environment still find one,
+    unless `$PREFIX` is already set.
+
+## 0.2.0 - 2026-08-17
+
+### Added
+
+- Add `--jsgotty`, `--jsmdcui`, and `--musl-la` as the first argument to
+  `bin/init.js` to spawn that app directly, forwarding every remaining
+  argument to it and exiting with its exit code. This bypasses the shell and
+  startup-command flow entirely, and lets `--jsgotty --help` (and the same for
+  the other two) show the app's own option reference instead of Buninu's.
+- Add `buninu-help`, a POSIX and Windows multicall command that renders
+  README.md with jsmdcui's `--cat` mode and then displays `icon.png` with
+  jsgotty's `--viu`. The default startup greeting now points to it instead of
+  separately mentioning `glow`/`README.md`.
+
+### Security
+
+- Bind jsgotty to `127.0.0.1` by default instead of `0.0.0.0` in
+  `scripts.start`. Previously the terminal server accepted connections from
+  any device able to reach the host on its network, relying only on the
+  random port and `--random-url` path segment for protection. Pass
+  `--address <value>` through to `bin/init.js` (forwarded arguments override
+  the flags baked into `scripts.start`) to opt back into listening on other
+  interfaces.
+
+## 0.1.9 - 2026-08-17
+
+### Fixed
+
+- Correct `apps/musl-la/NOTICE`: it listed 11 third-party components
+  (llama.cpp, nghttp2/nghttp3, OpenSSL, libssh2, curl, zlib, libidn2,
+  libunistring, brotli, c-ares, libpsl) with no corresponding files anywhere
+  in the package — leftover from an unrelated bundle. The only files actually
+  shipped in that directory are `ld-musl-aarch64.so.1`, `libgcc_s.so.1`, and
+  `libstdc++.so.6`; the notice now covers only those, identifying the exact
+  build (GCC 14.2.0, packaged as Alpine Linux 3.22's `libgcc`/`libstdc++`
+  14.2.0-r6, aarch64) with matching SHA-256 hashes and a link to Alpine's
+  build recipe pinned to the commit for that package revision, satisfying the
+  GCC Runtime Library Exception's corresponding-source requirement.
+
 ## 0.1.8 - 2026-08-17
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # Buninu
 
-![icon](icon.png)
+![icon](https://raw.githubusercontent.com/jjtseng93/buninu/main/icon.png)
 
 > **Early development:** Buninu is still at an early stage of development.
 > Features, configuration, and command-line behavior may change between releases.
@@ -70,8 +70,33 @@ shell for the current platform. Other arguments are forwarded to jsgotty:
 ```sh
 npx buninu --credential user:pass
 npx buninu --port 9000
+npx buninu --jsgotty --help
+
+# public: listen on every interface, reachable from other devices on the network, be cautious!
+npx buninu -a 0.0.0.0
 ```
 
+As the first argument, `--jsgotty`, `--jsmdcui`, or `--musl-la` bypasses the
+shell/command startup flow entirely: it spawns that app directly with every
+remaining argument forwarded to it, and exits with its exit code. Use this to
+reach an app's own options directly, for example `npx buninu --jsgotty --help`
+to see jsgotty's actual flag reference instead of Buninu's.
+
+## Security
+
+`scripts.start` binds jsgotty to `127.0.0.1` by default, so the terminal
+server only accepts connections from the same machine. It is not reachable
+from other devices on the network unless you explicitly opt in.
+
+The terminal itself is writable (`-w`) and unauthenticated by default; only
+the loopback binding and jsgotty's random URL path (`-r`) stand between a
+local process and a shell with Buninu's permissions. To listen on another
+interface, forward `--address <value>` (see [Start](#start)); forwarded
+arguments override the flags baked into `scripts.start`. Also pass
+`--credential user:pass` when doing so, since the random port and URL path
+are not a substitute for authentication once the server is reachable from
+outside the machine.
+
 ## Command-line information
 
 ```text
@@ -79,8 +104,39 @@ npx buninu --port 9000
 -V, --version    Show the Buninu, Bun, platform, and architecture versions
 --readme          Render README.md in the terminal
 --changelog       Render CHANGELOG.md in the terminal
+--jsgotty [args...]  Spawn jsgotty directly and exit with its exit code
+--jsmdcui [args...]  Spawn jsmdcui directly and exit with its exit code
+--musl-la [args...]  Spawn musl-la directly and exit with its exit code
 ```
 
+These are flags to `bin/init.js` itself, resolved before Buninu starts.
+
+## Commands inside the shell
+
+Once you are inside a running Buninu shell, these are available (the
+validated source list is `apps/cmdlist`; see [Add a command](#add-a-command)
+for how it works):
+
+```text
+glow        Render files with jsmdcui syntax highlighting
+jmi         Open files in the js micro editor
+jsgotty     Run a browser-accessible terminal
+jsmdcui     Edit and run interactive Markdown applications
+musl-la     Launch AArch64 ELF programs with the bundled musl loader
+buninu-help Render README.md with glow, then show icon.png with jsgotty --viu
+bunx        Globally install a package with bun, then exec its matching binary
+```
+
+`buninu-help` renders README.md with jsmdcui's `--cat` mode and then shows
+`icon.png` with jsgotty's `--viu`. It is the command the default startup
+greeting points to.
+
+`bunx <package>[@version] [args...]` installs with `bun i -g` and runs the
+matching binary. On Android, the underlying `bun i -g` currently needs
+[oven-sh/bun#39084](https://github.com/oven-sh/bun/pull/39084) merged
+upstream — without it, install is killed by SIGSYS (Android's seccomp policy
+rejects a syscall bin-linking uses), so `bunx` can't install anything there yet.
+
 ## Export
 
 Export the current Buninu installation as a gzip-compressed tar archive:

package/apps/bunx/bunx.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env bun
+
+// bunx <package>[@version] [args...]
+//
+// Buninu's own bunx: ensures <package> is globally installed via `bun i -g`,
+// then execs the matching ~/.bun/bin/<binary> directly, forwarding the
+// remaining arguments. Registered in apps/cmdlist like any other Buninu
+// command; whether it actually shadows the real `bunx` (Bun's own
+// ephemeral-run subcommand) depends on whether Buninu's bin/ comes before it
+// in PATH -- Buninu appends its bin/ to the inherited PATH rather than
+// prepending it, so an already-installed bun's own bunx will normally still
+// win unless this one is invoked some other way.
+//
+// The "when do we reinstall" rules below are ported from real bunx's own
+// decision tree (src/runtime/cli/bunx_command.rs in the Bun source tree),
+// adapted from its private per-version cache to this script's single shared
+// `bun i -g` install:
+//   - an explicit dist-tag (e.g. "latest", "next") never reuses a cached
+//     binary -- real bunx sets look_for_existing_bin = false for that case
+//     and always resolves fresh.
+//   - a missing binary always installs.
+//   - an explicit pinned/ranged version reinstalls if bun's own global
+//     install record (install/global/package.json) doesn't already list
+//     that same version string for this package -- there is no equivalent
+//     check in real bunx because its cache is already keyed by version; this
+//     is this script's substitute, since `bun i -g` overwrites one shared
+//     path regardless of version.
+//   - otherwise, reinstall once the binary is older than 24h
+//     (SECONDS_CACHE_VALID in bunx_command.rs), or if it can't be stat'd at
+//     all -- real bunx also treats a stat failure as stale.
+
+const fs = require("fs");
+const path = require("path");
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // matches real bunx's SECONDS_CACHE_VALID
+
+function fail(message) {
+  console.error(`bunx: ${message}`);
+  process.exit(1);
+}
+
+// Split "@scope/name@version" (or unscoped variants) into name/version/pkgName.
+// version is "" when the spec didn't include one.
+function parseSpec(spec) {
+  let rest = spec;
+  let scope = "";
+  if (rest.startsWith("@")) {
+    const slash = rest.indexOf("/");
+    if (slash === -1) fail(`invalid package spec: ${spec}`);
+    scope = rest.slice(0, slash);
+    rest = rest.slice(slash + 1);
+  }
+  const at = rest.lastIndexOf("@");
+  const name = at === -1 ? rest : rest.slice(0, at);
+  const version = at === -1 ? "" : rest.slice(at + 1);
+  return { name, version, pkgName: scope ? `${scope}/${name}` : name };
+}
+
+// A bare word like "latest"/"next"/"beta"/"canary" is an npm dist-tag.
+// Anything starting with a digit, "v", or a range operator is treated as a
+// real pinned version/range instead.
+function isDistTag(version) {
+  return !/^[vV]?\d|^[\^~<>=]/.test(version);
+}
+
+// Ask bun itself where its global bin dir is, rather than re-deriving
+// $BUN_INSTALL/$HOME ourselves -- this is the same resolution bun's own
+// installer used, so it can't disagree with where `bun i -g` actually put
+// things (config file settings included, not just env vars).
+//
+// `bun pm bin -g` only works once something has been globally installed at
+// least once (it errors with "no package.json" for install/global before
+// that project exists). On a fresh $BUN_INSTALL/$HOME this script hasn't
+// installed anything yet either, so fall back to the plain env-var
+// computation for that first call -- needsInstall() below will see nothing
+// at that path and install, which creates the project bun pm needs, so every
+// call after the first one resolves through bun pm bin -g instead.
+function globalBinDir() {
+  const result = Bun.spawnSync(["bun", "pm", "bin", "-g"], {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.exitCode === 0) return result.stdout.toString().trim();
+  return path.join(process.env.BUN_INSTALL || path.join(process.env.HOME, ".bun"), "bin");
+}
+
+// `bun i -g` produces bin/<name> on POSIX (a relative symlink resolved via
+// shebang) but bin/<name>.exe on Windows (a compiled shim + a companion
+// .bunx metadata file -- Windows has neither reliable symlinks nor shebang
+// support). Missing this suffix means every Windows lookup below finds
+// nothing, which is harmless: needsInstall() just treats it as "not
+// installed on this platform yet" and installs it here.
+const EXE_SUFFIX = process.platform === "win32" ? ".exe" : "";
+
+// Buninu on Android isn't actually running inside Termux, so nothing sets
+// $PREFIX -- but some installed CLIs check it at runtime to find themselves
+// relative to a Termux/Android system. Fake it only for the actual target
+// execution below (not the `bun i -g` install step); an existing $PREFIX
+// (e.g. genuinely running under Termux) is left alone.
+function childEnv() {
+  if (process.platform !== "android" || process.env.PREFIX) return process.env;
+  return { ...process.env, PREFIX: "/data/data/com.termux/files/usr" };
+}
+
+function recordedVersion(bunInstallRoot, pkgName) {
+  const manifestPath = path.join(bunInstallRoot, "install", "global", "package.json");
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return manifest.dependencies && manifest.dependencies[pkgName];
+  } catch {
+    return undefined;
+  }
+}
+
+function needsInstall(bunInstallRoot, target, version, pkgName) {
+  if (version && isDistTag(version)) return true;
+  if (!fs.existsSync(target)) return true;
+  if (version && recordedVersion(bunInstallRoot, pkgName) !== version) return true;
+  try {
+    const age = Date.now() - fs.statSync(target).mtimeMs;
+    return age > CACHE_TTL_MS;
+  } catch {
+    return true;
+  }
+}
+
+const args = process.argv.slice(2);
+if (args.length < 1) fail("usage: bunx <package>[@version] [args...]");
+
+const spec = args[0];
+const forwarded = args.slice(1);
+const { name: bin, version, pkgName } = parseSpec(spec);
+const binDir = globalBinDir();
+const bunInstallRoot = path.dirname(binDir);
+const target = path.join(binDir, bin + EXE_SUFFIX);
+
+if (needsInstall(bunInstallRoot, target, version, pkgName)) {
+  // Same Android check bin/init.js's detectEnvironment() uses. Android's
+  // storage (FUSE-backed app-private paths) frequently rejects hardlinks
+  // and symlinks across the directories bun links between, so fall back to
+  // plain file copies there; hardlink (bun's default) is fine elsewhere.
+  const installArgs = ["bun", "i", "-g", spec];
+  if (fs.existsSync("/system/bin/linker64")) installArgs.push("--backend=copyfile");
+
+  const install = Bun.spawnSync(installArgs, {
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+  if (install.exitCode !== 0) process.exit(install.exitCode ?? 1);
+}
+
+if (!fs.existsSync(target)) {
+  fail(`${spec} installed but ${target} not found (binary name may differ from package name)`);
+}
+
+// Run through `bun <target>` instead of exec'ing `target` directly. Real
+// bunx does the latter (relies on the OS reading the shebang), which is fine
+// on desktop but not reliable here: on Android the resolved bin usually
+// lives under a path mounted noexec, so the kernel refuses to exec it even
+// though it's readable and chmod +x. `bun` itself is the one binary Android
+// does let us execute (from nativeLibraryDir), so hand it the target as an
+// argument to read+run rather than exec directly. Trade-off: a package whose
+// "bin" is a real native executable (not a JS/bun script) won't run this
+// way -- accepted, since that's the rarer case and this is what makes the
+// common (JS-script bin) case work on Android at all.
+const run = Bun.spawnSync(["bun", target, ...forwarded], {
+  env: childEnv(),
+  stdio: ["inherit", "inherit", "inherit"],
+});
+process.exit(run.exitCode ?? 1);

package/apps/cmdlist

@@ -14,3 +14,9 @@ jsmdcui
 
 ### musl-la — Launch AArch64 ELF programs with the bundled musl loader
 musl-la
+
+### buninu-help — Render README.md with glow, then show icon.png with jsgotty --viu
+buninu-help
+
+### bunx — Globally install a package with bun, then exec its matching binary
+bunx

package/bin/buninu-help.bat

@@ -0,0 +1,4 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\jsmdcui\src\index.js" --cat "%~dp0..\README.md"
+call "%~dp0bun.bat" "%~dp0..\apps\jsgotty\gotty.js" --viu "%~dp0..\icon.png"
+exit /b %ERRORLEVEL%

package/bin/buninu-help.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+sd=$(dirname "$(realpath "$0")")
+root=$sd/..
+
+bun "$root"/apps/jsmdcui/src/index.js --cat "$root"/README.md
+exec bun "$root"/apps/jsgotty/gotty.js --viu "$root"/icon.png

package/bin/bunx.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\bunx\bunx.js" %*
+exit /b %ERRORLEVEL%

package/bin/init.js

@@ -30,6 +30,14 @@ Init options:
   --shell <path|name>    Override buninu.shell for this run
   --command <command>    Override buninu.command for this run
 
+Direct app launch (must be the first argument; skips the shell/command
+startup flow entirely):
+  --jsgotty [args...]    Spawn jsgotty directly, forwarding remaining
+                          arguments, and exit with its exit code
+                          (--jsgotty --help shows jsgotty's own options)
+  --jsmdcui [args...]    Spawn jsmdcui directly, same forwarding behavior
+  --musl-la [args...]    Spawn musl-la directly, same forwarding behavior
+
 Package configuration:
   package.json contains a buninu section for default and platform settings.
   buninu.shell          Select the shell to start
@@ -395,6 +403,34 @@ async function createChildEnvironment(environment) {
   };
 }
 
+const directAppTargets = {
+  "--jsgotty": "jsgotty",
+  "--jsmdcui": "jsmdcui",
+  "--musl-la": "musl-la",
+};
+
+async function runDirectApp(name, forwardedArgs, environment) {
+  const isWindows = environment.name === "windows";
+  const launcherPath = resolve(binDir, isWindows ? `${name}.bat` : name);
+  if (!await pathExists(launcherPath)) {
+    fail(`${name} is not available on ${environment.name}: ${launcherPath}`);
+  }
+
+  const childEnvironment = await createChildEnvironment(environment);
+  const argv = isWindows
+    ? [process.env.ComSpec || "cmd.exe", "/c", launcherPath, ...forwardedArgs]
+    : [launcherPath, ...forwardedArgs];
+
+  const child = Bun.spawn(argv, {
+    cwd: rootDir,
+    env: childEnvironment,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(await child.exited);
+}
+
 function readInitArguments(arguments_) {
   const forwarded = [];
   let shell = null;
@@ -459,6 +495,14 @@ if (typeof startScript !== "string" || !startScript.trim()) {
   fail("package.json does not define scripts.start");
 }
 
+const directAppTarget = directAppTargets[process.argv[2]];
+if (directAppTarget) {
+  const directEnvironment = await detectEnvironment();
+  await runPlatformSwitch(directEnvironment);
+  await rebuildNativeSymlinks(directEnvironment);
+  await runDirectApp(directAppTarget, process.argv.slice(3), directEnvironment);
+}
+
 if (await handleInformationArguments(process.argv.slice(2))) process.exit(0);
 
 const command = splitCommand(startScript);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu",
-  "version": "0.1.9",
+  "version": "0.2.2",
   "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,15 +17,15 @@
       "windows": null
     },
     "command": {
-      "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",
+      "default": "echo Welcome to Buninu, Try: glow apps/cmdlist, Help: buninu-help",
+      "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' '- Help: buninu-help'; fi",
       "linux": null,
       "macos": null,
       "windows": null
     }
   },
   "scripts": {
-    "start": "bun ./apps/jsgotty/gotty.js --reconnect -r -w --webgl",
+    "start": "bun ./apps/jsgotty/gotty.js --reconnect -r -w --webgl -a 127.0.0.1",
     "check": "node --check ./bin/init.js"
   }
 }