buninu 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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

package/README.md

@@ -109,10 +109,33 @@ outside the machine.
 --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. Once you
-are inside a running Buninu shell, run `buninu-help` instead: it 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.
+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
 

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

@@ -17,3 +17,6 @@ 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/bunx.bat

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu",
-  "version": "0.2.0",
+  "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",