buninu 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.2.3 - 2026-08-18
+
+### Added
+
+- Add `buninu.exitAfterCmd` package.json setting (default `false`). When
+  `true`, the shell/PTY exits with `buninu.command`'s status instead of
+  falling back to an interactive shell once the command finishes; `false`
+  keeps the existing fall-back-to-shell behavior.
+- Add `--export-config [output.json]`, which writes this entire `package.json`
+  to `buninu.json` in the current directory by default (like `--export`, the
+  output path can be overridden), instead of exporting the whole installation
+  like `--export` does. If the output path already exists, it now asks for
+  confirmation (`[y/N]`) before overwriting.
+
+## 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,18 +109,41 @@ 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
 
 Export the current Buninu installation as a gzip-compressed tar archive:
 
 ```sh
-npx buninu --export
-npx buninu --export /path/to/buninu.tgz
+npx buninu@latest --export
+npx buninu@latest --export /path/to/buninu.tgz
 ```
 
 The default output is `./buninu.tgz`. The archive contains exactly one
@@ -128,6 +151,17 @@ 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.
 
+Export this `package.json` on its own, instead of the whole installation:
+
+```sh
+npx buninu@latest --export-config
+npx buninu@latest --export-config /path/to/buninu.json
+```
+
+The default output is `./buninu.json`. This is the full `package.json` (not
+just the `buninu` section), so the output is ready to use as-is anywhere a
+complete replacement `package.json` is expected.
+
 ## Environment
 
 `BUNINU_HOME` is the absolute path to the installed Buninu package root.
@@ -240,6 +274,19 @@ Override it for one run with:
 bun ./bin/init.js --command "echo temporary command"
 ```
 
+Set `buninu.exitAfterCmd` to `true` to exit once `buninu.command` finishes
+instead of falling back to an interactive shell. It defaults to `false`,
+which is the current fall-back-to-shell behavior described above.
+
+```json
+{
+  "buninu": {
+    "command": { "default": "echo Welcome to Buninu" },
+    "exitAfterCmd": true
+  }
+}
+```
+
 ## Shell selection (optional)
 
 Set `buninu.shell.default` or a platform-specific value (`android`, `linux`,

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/bin/init.js

@@ -4,6 +4,7 @@ import pkg from "../package.json" with { type: "json" };
 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 { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 const binDir = dirname(fileURLToPath(import.meta.url));
@@ -27,6 +28,7 @@ Init options:
   --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)
+  --export-config [output.json]  Export this package.json (default: ./buninu.json)
   --shell <path|name>    Override buninu.shell for this run
   --command <command>    Override buninu.command for this run
 
@@ -42,10 +44,13 @@ Package configuration:
   package.json contains a buninu section for default and platform settings.
   buninu.shell          Select the shell to start
   buninu.command        Run a startup command before entering the shell
+  buninu.exitAfterCmd   Exit after buninu.command instead of falling back to
+                         the shell (default: false)
 
 All other options are forwarded to jsgotty. Without buninu.command, the
 selected shell starts directly. With a command, it runs from the package.json
-directory and then returns to the interactive shell regardless of exit status.
+directory and then returns to the interactive shell regardless of exit status,
+unless buninu.exitAfterCmd is true, in which case it exits instead.
 `;
 }
 
@@ -69,6 +74,12 @@ async function handleInformationArguments(arguments_) {
     return true;
   }
 
+  const exportConfigOption = readExportConfigArgument(arguments_);
+  if (exportConfigOption) {
+    await exportConfig(exportConfigOption.output);
+    return true;
+  }
+
   if (arguments_.includes("--readme")) {
     const readmePath = resolve(REPO_ROOT, "README.md");
     if (!await pathExists(readmePath)) fail(`README not found: ${readmePath}`);
@@ -106,6 +117,22 @@ function readExportArgument(arguments_) {
   return null;
 }
 
+function readExportConfigArgument(arguments_) {
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === "--export-config") {
+      const next = arguments_[index + 1];
+      return { output: next || "buninu.json" };
+    }
+    if (argument.startsWith("--export-config=")) {
+      const output = argument.slice("--export-config=".length);
+      if (!output) fail("--export-config= 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");
@@ -145,6 +172,25 @@ async function exportInstallation(output) {
   console.log(outputPath);
 }
 
+async function exportConfig(output) {
+  const outputPath = resolve(process.cwd(), output);
+
+  if (existsSync(outputPath)) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let answer;
+    try {
+      answer = await rl.question(`${outputPath} already exists and may be overwritten. Continue? [y/N] `);
+    } finally {
+      rl.close();
+    }
+    if (!/^[yY]/.test(answer.trim())) fail("Cancelled: output file was not overwritten");
+  }
+
+  const packageJsonPath = resolve(REPO_ROOT, "package.json");
+  await Bun.write(outputPath, Bun.file(packageJsonPath));
+  console.log(outputPath);
+}
+
 function splitCommand(command) {
   const words = [];
   let word = "";
@@ -460,16 +506,25 @@ function readInitArguments(arguments_) {
   return { shell, command, forwarded };
 }
 
-function shellCommandArguments(shell, command) {
+function shellCommandArguments(shell, command, exitAfterCmd) {
   if (!command) return [shell];
 
   const shellName = basename(shell).toLowerCase();
   if (shellName === "cmd" || shellName === "cmd.exe") {
+    if (exitAfterCmd) return [shell, "/d", "/s", "/c", command];
     const quotedShell = `"${shell.replaceAll('"', '""')}"`;
     return [shell, "/d", "/s", "/c", `${command} & ${quotedShell}`];
   }
 
   if (["powershell", "powershell.exe", "pwsh", "pwsh.exe"].includes(shellName)) {
+    if (exitAfterCmd) {
+      return [
+        shell,
+        "-NoLogo",
+        "-Command",
+        `& { ${command}; if (-not $?) { Write-Error 'Startup command failed' } }`,
+      ];
+    }
     const escapedShell = shell.replaceAll("'", "''");
     return [
       shell,
@@ -483,7 +538,7 @@ function shellCommandArguments(shell, command) {
     `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"`;
+    (exitAfterCmd ? `fi; exit "$status"` : `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.
@@ -539,6 +594,7 @@ const configuredCommand =
       commandConfiguration?.default ??
       null;
 const startupCommand = initArguments.command ?? configuredCommand;
+const exitAfterCmd = Boolean(pkg.buninu?.exitAfterCmd);
 
 const forwardedArguments = initArguments.forwarded;
 const hasExplicitPort = forwardedArguments.some((argument) =>
@@ -559,7 +615,7 @@ const child = Bun.spawn(
     ...command,
     ...portArguments,
     ...forwardedArguments,
-    ...shellCommandArguments(environment.shell, startupCommand),
+    ...shellCommandArguments(environment.shell, startupCommand, exitAfterCmd),
   ],
   {
     cwd: rootDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun that runs across operating systems",
   "type": "module",
   "main": "./bin/init.js",
@@ -22,7 +22,8 @@
       "linux": null,
       "macos": null,
       "windows": null
-    }
+    },
+    "exitAfterCmd": false
   },
   "scripts": {
     "start": "bun ./apps/jsgotty/gotty.js --reconnect -r -w --webgl -a 127.0.0.1",