buninu 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.4.1 - 2026-08-30
+
+### Fixed
+
+- A freshly installed tree no longer reports files as locally changed when
+  only their file mode differs. Publishing normalises modes, so a file can come
+  back from the registry with a different executable bit and byte-identical
+  contents, which `bun pm diff` counts as a modification; an update was
+  listing those and asking about files nobody had touched. They are now
+  recognised by the mode having changed while the contents did not, and left
+  out of the list, with a line saying how many were ignored so the count still
+  adds up against the command below.
+
+### Changed
+
+- An update prints the `bun pm diff` command it is about to run, on a line of
+  its own before the result. Run it by hand without `--json` to read the list
+  directly, or without `--name-only` to see the changes themselves rather than
+  which files hold them. It goes to stdout rather than stderr with the rest of
+  the output, so `2>/dev/null` leaves just the command.
+
+## 0.4.0 - 2026-08-30
+
+### Added
+
+- `--install [dir]` (`-i`) and `--strip-install [dir]` (`-si`) copy the running
+  installation into a directory that outlives the `npx` cache. `--install`
+  creates `<dir>/buninu` as the new `BUNINU_HOME`, `--strip-install` makes
+  `<dir>` itself that root, and both default to the current directory. The
+  implementation is `bin/install.js`, which runs on its own as well as being
+  imported by `bin/init.js`; run directly with no arguments it installs.
+  Relative symbolic links are recreated exactly as stored rather than followed,
+  so `bin/androidNativeLibs -> ../..` stays a link instead of dragging the
+  parent tree into the copy. `cp -a` is used when `cp` is on `PATH`, and an
+  equivalent `node:fs` walk otherwise; the two were verified to agree on
+  content, link targets, permissions and whole-second timestamps across every
+  entry of the tree.
+- Installing over an existing Buninu updates it in place. The copy only ever
+  adds and overwrites, so `apps/<name>/` commands, `bin/*.sh` overrides and the
+  Bun binaries `bin/bun.sh` extracted are left alone, and the three files that
+  belong to the package and to the user at once are merged: the local `buninu`
+  section of `package.json` is kept, command names added to `apps/cmdlist` are
+  kept, and `.bashrc` is kept whenever it only adds lines to the shipped one,
+  including lines inserted in the middle. A `.bashrc` that cannot be merged
+  that way is left exactly as it is, with the shipped version written beside it
+  as `.bashrc.dist`.
+- Before replacing the package's own files, an update runs `bun pm diff`
+  against the version the installation reports and lists the files that no
+  longer match it, then asks before continuing. Nothing is recorded inside the
+  installation to make this work — the published package is the reference — so
+  the check needs the network, and when it cannot run, or does not finish
+  within 60 seconds, it asks rather than assuming there was nothing to lose.
+  `--yes` answers ahead of time, which a run without a terminal needs;
+  `--force` replaces everything without merging or checking. An existing
+  installation is always named by absolute path before anything is written.
+
+- `buninu.xdgDataHome` points `XDG_DATA_HOME` at a directory of your choosing:
+  `true` puts it inside the installation at `$BUNINU_HOME/.local/share`, and a
+  string names one outright, resolved from the `package.json` directory when it
+  is relative. The directory is created at startup. What this moves in practice
+  is bunmsh's command history, which lives at `$XDG_DATA_HOME/bunmsh/history`,
+  so `true` is what makes a shell's history travel with a copied installation
+  instead of staying on the machine it was typed on. `HOME` is deliberately not
+  touched by it, so SSH keys and Git configuration in the user's own home keep
+  working and bunmsh can still import an existing `~/.bash_history`.
+
+- Refusing to install into an occupied directory now says which check the
+  directory failed — no readable `package.json`, or one naming a different
+  package — instead of reporting every case as "is not a buninu installation".
+  Whether a directory is an installation to update is decided by that name
+  alone: a Buninu missing `bin/init.js` is a damaged installation rather than
+  somebody else's directory, so an update repairs it, merging the local
+  configuration back in, where before `--force` was the only way through and
+  took that configuration with it. Every refusal names the directory by
+  absolute path.
+
+### Fixed
+
+- `HOME` no longer falls back to the package directory when the environment
+  does not set it. Windows does not set `HOME`, so a Windows session had its
+  home pointed at the disposable `npx` cache, taking anything written there —
+  bunmsh's command history included — with it when the cache was cleared. It
+  now falls back to the operating system's own home directory for the user.
+
+## 0.3.2 - 2026-08-29
+
+- Added bunmsh to bin and cmdlist
+
+## 0.3.1 - 2026-08-29
+
+- Added bunmsh to buninu
+
 ## 0.3.0 - 2026-08-21
 
 ### Added

package/README.md

@@ -25,20 +25,6 @@
 See [ARCHITECTURE.md](ARCHITECTURE.md) for the complete architecture, portability model,
 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.
-
 ## Install Bun
 
 Buninu requires [Bun](https://bun.com). On Android, install Bun in Termux:
@@ -54,12 +40,26 @@ On Linux and Windows, follow the
 
 ### Start a remote shell in a Browser
 
-Run the npm package:
+To try it, run the npm package. This runs Buninu from the `npx` cache, which
+is a fine place to look around in and a bad place to keep anything:
 
 ```sh
 npx buninu
 ```
 
+To keep it, install it somewhere of your own first, and start it from there
+from then on. That directory becomes `BUNINU_HOME`: the installation's own
+root, yours to edit and to carry to another machine. See
+[Install and update](#install-and-update):
+
+```sh
+# Creates ~/somewhere/buninu, which is now BUNINU_HOME
+npx buninu --install ~/somewhere
+
+# Start it from there from now on
+bun ~/somewhere/buninu/bin/init.js
+```
+
 Or run it from a source checkout:
 
 ```sh
@@ -70,19 +70,23 @@ The launcher automatically chooses a free TCP port and detects an available
 shell for the current platform. Other arguments are forwarded to jsgotty:
 
 ```sh
-npx buninu --credential user:pass
+# Serve on port 9000 instead of picking a free one
 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
+# Ask for a username and password before handing over the terminal
+npx buninu --credential user:pass
+
+# Accept connections from other machines, not just this one. By default the
+# terminal is reachable only from the computer it runs on; this opens it to
+# anything that can reach this machine over the network, and the terminal is
+# a working shell, so give it a password at the same time.
+npx buninu -a 0.0.0.0 --credential user:pass
 ```
 
-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.
+Read [Security](#security) before using that last one.
+
+Buninu's own options are listed under
+[Command-line usage](#command-line-usage).
 
 ### Start a local shell in a Terminal (experimental)
 
@@ -90,10 +94,29 @@ Drops you straight into [bunmsh](apps/bunmsh/README.md) (Bun Modern Shell), a
 dependency-free, mksh-inspired command shell that runs on Bun, without going
 through the browser/jsgotty flow.
 
+To try it:
+
 ```sh
 npx buninu --local
 ```
 
+To keep it, install it the same way as above and pass `--local` to the
+installed copy from then on. See [Install and update](#install-and-update):
+
+```sh
+# Creates ~/somewhere/buninu, which is now BUNINU_HOME
+npx buninu --install ~/somewhere
+
+# Start bunmsh from there from now on
+bun ~/somewhere/buninu/bin/init.js --local
+```
+
+Command history is kept in your own home directory either way, so it survives
+`npx`. What does not is anything you add to the installation itself — aliases
+in its `.bashrc`, commands of your own under `apps/` — since that lives in the
+package, and under `npx` the package is a cache directory.
+See [Data & Persistence](#data--persistence).
+
 Or run it from a source checkout:
 
 ```sh
@@ -103,6 +126,139 @@ bun ./bin/init.js --local
 Buninu's own tools (`rz`, `sz`, `showimg`, `tts`, `xdg-open`, `native-bridge`,
 etc.) stay available inside this shell too, same as in the browser session.
 
+## Data & Persistence
+
+Running Buninu via `npx` works like a container: `npx` fetches the package into
+a cache directory and runs it from there, which is fine as a temporary working
+directory but isn't guaranteed to survive between runs — version bumps,
+`npx clear-npx-cache`, or normal cache eviction can all wipe it. That directory
+is where the shell starts, so nothing left sitting in it is safe.
+
+The answer is to stop running it from there: [install it](#install-and-update)
+into a directory of your own, and `BUNINU_HOME` becomes somewhere you can keep
+things, edit files in, and carry to another machine.
+
+Once it is installed, files you leave in `BUNINU_HOME` are safe, updates
+included — an update only adds and overwrites the package's own files and
+never deletes anything else. Your own home directory is untouched and still
+reachable as `~`, so work you would rather keep separate from Buninu, or that
+is too large to carry around with it, can just as well live there.
+
+Two things live outside `BUNINU_HOME` either way, because they belong to the
+machine rather than to Buninu:
+
+- `HOME` stays your own home directory. Buninu never replaces it, so a shell
+  started here still finds your SSH keys, your Git configuration, and anything
+  else you keep there.
+- bunmsh writes its command history to `$XDG_DATA_HOME/bunmsh/history`, or
+  `$HOME/.local/share/bunmsh/history` when that is unset. It persists between
+  sessions, and by default it stays on the machine it was typed on rather than
+  travelling with an installation.
+
+Set [`buninu.xdgDataHome`](#data-directory-optional) to move that history, and
+anything else written to the XDG data directory, into the installation so it
+travels with it. Keep in mind that a history file records the commands it was
+given, so one carried on removable media carries whatever was typed into it.
+
+## Install and update
+
+Copy this installation into a directory that is yours to keep, and run it
+from there instead of from the `npx` cache:
+
+```sh
+# Creates ~/somewhere/buninu as BUNINU_HOME
+npx buninu --install ~/somewhere
+
+# Makes ~/buninu itself BUNINU_HOME, with no directory of its own
+npx buninu --strip-install ~/buninu
+```
+
+Both default to the current directory. The two differ only in where
+`BUNINU_HOME` — the installation's own root, see
+[Environment](#environment) — ends up: below the directory you named, or at
+it. `npx buninu --install --help` lists every install option in full.
+
+An installation is started the same two ways `npx buninu` is, by running its
+own `bin/init.js` instead of the package name:
+
+```sh
+# Terminal in a browser, as usual
+bun $BUNINU_HOME/bin/init.js
+
+# bunmsh in this terminal (experimental)
+bun $BUNINU_HOME/bin/init.js --local
+```
+
+Every option described under [Start](#start) works the same way here, `--local`
+included; nothing about an installed copy behaves differently from the one
+`npx` runs.
+
+Installing over an existing Buninu updates it in place. Files are only added
+and overwritten, never deleted, so anything you added of your own is left
+alone: your `apps/<name>/` commands, your `bin/*.sh` overrides, the Bun
+binaries `bin/bun.sh` extracted, and any working file you left in the tree.
+
+Three files belong to you and to the package at the same time, and are merged
+rather than replaced:
+
+| File | What is kept |
+|---|---|
+| `package.json` | Your `buninu` section. Every other field, `version` included, comes from the new package. |
+| `apps/cmdlist` | Command names you added. They are appended below the shipped list. |
+| `.bashrc` | Your version, whenever it only adds lines to the shipped one — including lines inserted in the middle. |
+
+When `.bashrc` cannot be merged that way, because a line the package ships was
+changed or removed rather than added to, your file is left exactly as it is
+and the package's version is written beside it as `.bashrc.dist` for you to
+reconcile by hand. Nothing is overwritten silently.
+
+Every other file belongs to the package and is replaced. Before doing that, an
+update asks the registry what the installation originally shipped with and
+lists the files that no longer match, so editing one of the package's own files
+is not quietly undone:
+
+```
+buninu: found buninu@0.3.1 at /home/you/buninu
+buninu: comparing it against the published 0.3.1 for local changes...
+buninu: 1 file(s) differ from buninu@0.3.1 and will be replaced:
+  apps/xclip/xclip.js
+Update anyway? (y/N)
+```
+
+An existing installation is always named, by absolute path, before anything is
+written to it — `--force` included, since that one replaces it without asking.
+
+Only `y` continues; anything else cancels and leaves the installation
+untouched. The three merged files above are left out of that list, since they
+are already kept. `--yes` answers for you, which is also what a script or any
+other run without a terminal needs. Nothing about this is recorded inside the
+installation: the published package is the reference, so the check needs the
+network, and when it cannot run the update says so and goes ahead.
+
+Three more things are worth knowing about:
+
+- Installing from a checkout that already carries changes made since its
+  version was published — that is, while working on Buninu itself — compares
+  the installation against a reference its own files no longer match, so the
+  list names those unreleased changes rather than anything you did. Cloning it
+  and adding your own files on top does not.
+- A file the package **stopped** shipping is not removed from an existing
+  installation, because an update never deletes. Stale files accumulate
+  across updates.
+- `--force` skips both the merge and the check, and installs the shipped
+  versions over yours. It is also what installs into a non-empty directory that
+  is not a Buninu installation, which is otherwise refused — by absolute path,
+  saying which check the directory failed.
+
+Whether a directory counts as an installation to update is decided by the name
+in its `package.json`. An installation that has lost files, `bin/init.js`
+included, is a damaged one rather than somebody else's directory, so installing
+over it repairs it and still merges your configuration back in.
+
+A source checkout's own `.git` is never copied into an installation, so
+installing into a directory that is itself a repository leaves that repository
+alone.
+
 ## Security
 
 `scripts.start` binds jsgotty to `127.0.0.1` by default, so the terminal
@@ -118,19 +274,48 @@ arguments override the flags baked into `scripts.start`. Also pass
 are not a substitute for authentication once the server is reachable from
 outside the machine.
 
-## Command-line information
+## Command-line usage
+
+These are flags to `bin/init.js` itself, resolved before Buninu starts.
+Everything else on the command line is forwarded to jsgotty.
 
 ```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
+--readme         Render README.md in the terminal
+--changelog      Render CHANGELOG.md in the terminal
+--local          Start bunmsh in this terminal instead of a browser terminal
+
+-i,  --install [dir]        Install into <dir>/buninu (default: .)
+-si, --strip-install [dir]  Install into <dir> itself
+--export [output.tgz]       Export this installation as a tarball
+--export-config [out.json]  Export this package.json
+
+--shell <path|name>   Override buninu.shell for this run
+--command <command>   Override buninu.command for this run
+```
+
+`--install --help` lists the install options in full, including `--force` and
+`--yes`; see [Install and update](#install-and-update) for what an update does
+with files you changed. The other groups are covered by
+[Start](#start), [Export](#export), [Shell selection](#shell-selection-optional)
+and [Startup command](#startup-command-optional).
+
+### Launching a bundled app directly
+
+As the **first** argument, `--jsgotty`, `--jsmdcui`, or `--musl-la` bypasses the
+shell and startup-command flow entirely: it spawns that app with every
+remaining argument forwarded to it, and exits with its exit code.
+
+```text
 --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.
+Use it to reach an app's own options, which Buninu would otherwise interpret
+as its own — `npx buninu --jsgotty --help` shows jsgotty's flag reference
+rather than this one.
 
 ## Commands inside the shell
 
@@ -204,8 +389,12 @@ host accepts either and lists both in its `_discover` response, so either name
 works from the CLI, from `rpcraw`, and as an `import`.
 
 ```sh
-native-bridge openwv 1 https://example.com   # load it, screen unchanged
-native-bridge showwv 1                       # now bring it to the front
+# Load it, screen unchanged
+native-bridge openwv 1 https://example.com
+
+# Now bring it to the front
+native-bridge showwv 1
+
 native-bridge evalwv 1 document.title
 native-bridge currwv
 ```
@@ -239,8 +428,11 @@ and a URL is loaded into that WebView and brought to the front (`openWebView`
 then `showWebView`) instead of being handed to the system's default handler.
 
 ```sh
-MINAPK_WEBVIEW=1 xdg-open https://example.com   # in the app WebView, on screen
-export MINAPK_WEBVIEW=1                         # ...or for the whole session
+# In the app WebView, on screen
+MINAPK_WEBVIEW=1 xdg-open https://example.com
+
+# ...or for the whole session
+export MINAPK_WEBVIEW=1
 ```
 
 `0` is the console, so it navigates the terminal page away -- the back key
@@ -253,13 +445,43 @@ is not a plain integer is reported on stderr and ignored rather than guessed
 at, an unset or empty value keeps the default behavior, and a WebView the host
 does not have falls back to the default handler after saying so.
 
+## Differences from upstream
+
+The versions of jsmdcui and jsgotty bundled here differ from the ones their
+own projects ship.
+
+### 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.
+
 ## Export
 
-Export the current Buninu installation as a gzip-compressed tar archive:
+Export a Buninu installation as a gzip-compressed tar archive. What gets
+exported is the installation the command runs from, so run it from your own
+installation to capture your configuration, added commands and edited
+`.bashrc` along with it:
+
+```sh
+# Everything in this installation, as ./buninu.tgz
+bun $BUNINU_HOME/bin/init.js --export
+
+# ...to a path of your choosing
+bun $BUNINU_HOME/bin/init.js --export /path/to/buninu.tgz
+```
+
+Run it through `npx` instead and you get an archive of the freshly downloaded
+package, with none of that — useful for a clean copy, not for a backup:
 
 ```sh
 npx buninu@latest --export
-npx buninu@latest --export /path/to/buninu.tgz
 ```
 
 The default output is `./buninu.tgz`. The archive contains exactly one
@@ -267,17 +489,29 @@ 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:
+Export this `package.json` on its own, instead of the whole installation. The
+same distinction applies — run it from your installation to get your settings,
+through `npx` to get the defaults:
 
 ```sh
+# The buninu section as you have configured it, as ./buninu.json
+bun $BUNINU_HOME/bin/init.js --export-config
+
+# ...to a path of your choosing
+bun $BUNINU_HOME/bin/init.js --export-config /path/to/buninu.json
+
+# The package's own defaults instead
 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.
 
+A tarball made this way is also the simplest backup to take before an update
+that is going to replace files you edited; see
+[Install and update](#install-and-update).
+
 ## Environment
 
 `BUNINU_HOME` is the absolute path to the installed Buninu package root.
@@ -287,11 +521,15 @@ directory as their working directory. Buninu also appends
 
 Buninu preserves inherited environment variables and supplies these fallbacks:
 
-- `HOME`: inherited value, or `BUNINU_HOME` when unset.
+- `HOME`: inherited value; when unset, the operating system's own home
+  directory for the current user (`USERPROFILE` on Windows), falling back to
+  `BUNINU_HOME` only if that is unavailable too.
 - `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.
+- `XDG_DATA_HOME`: inherited value, unless `buninu.xdgDataHome` names one; see
+  [Data directory](#data-directory-optional).
 - `TERM`: `xterm-256color` when unset.
 - `COLORTERM`: `truecolor` when unset.
 
@@ -424,6 +662,44 @@ from the directory containing `package.json`.
 
 Use `--shell <path-or-name>` for a one-time override.
 
+## Data directory (optional)
+
+Set `buninu.xdgDataHome` in `package.json` to point `XDG_DATA_HOME` somewhere
+of your choosing. `true` puts it inside the installation, at
+`$BUNINU_HOME/.local/share`:
+
+```json
+{
+  "buninu": {
+    "xdgDataHome": true
+  }
+}
+```
+
+A string names a directory instead, resolved from the directory containing
+`package.json` when it is relative:
+
+```json
+{
+  "buninu": {
+    "xdgDataHome": "/mnt/usb/shared-data"
+  }
+}
+```
+
+The directory is created at startup if it does not exist. Leave the setting
+`null` and `XDG_DATA_HOME` is passed through from the environment untouched.
+
+What this actually moves is where XDG-aware programs keep their data, and
+**bunmsh's command history is the one that matters here**: it lives at
+`$XDG_DATA_HOME/bunmsh/history`, so `true` is what makes a shell's history
+travel with a copied installation instead of staying on the machine.
+
+`HOME` is deliberately left alone by this setting. A shell started under
+Buninu keeps pointing at your own home directory, so SSH keys, Git
+configuration and anything else kept there still work, and bunmsh can still
+import the `~/.bash_history` or fish history you already had.
+
 ## Back key (Android, optional)
 
 Set `buninu.backToConsole` in `package.json` to decide what the Android host

package/apps/cmdlist

@@ -39,5 +39,10 @@ rz
 ### sz — Download a file over ZMODEM (bun apps/jsgotty/sz.js)
 sz
 
-### xdg-open — Open a file or URL with the platform's default handler (native bridge on Android, open/start/xdg-open elsewhere)
+### xdg-open — Open a file or URL with the platform's default handler (native bridge on Android, open/start/xdg-open elsewhere) '
 xdg-open
+
+
+### bunmsh – Bun Modern Shell
+
+bunmsh