Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(install): survive Bun bin metadata corruption
Rahman19d9083297a3
diff --git a/README.md b/README.mdindex 492b5a15..097d1eaa 100644--- a/README.md+++ b/README.md@@ -126,12 +126,14 @@ The flow lets you choose:from Alfa's credentials);- reviewed **installable skills** such as Ponytail, Caveman and the MSO-safe RTK wrapper.-The installer generates the owner login credentials, builds production, and installs the CLI-**before** it touches systemd. It always creates `~/.local/bin/mso`; when the invoking shell-already has `/usr/local/bin` on `PATH`, it also installs a guarded `/usr/local/bin/mso`-launcher (using sudo when needed). That order matters on WSL: a distro may ship a `systemctl`-binary even when systemd is not PID 1, and a service setup problem must never prevent the CLI-from being installed.+Immediately after checkout, the installer installs and validates the CLI **before dependency+installation, the production build, or systemd setup**. It always creates `~/.local/bin/mso`;+when the invoking shell already has `/usr/local/bin` on `PATH`, it also installs a guarded+`/usr/local/bin/mso` launcher (using sudo when needed). That order matters on WSL: even if a+subsequent Bun/Next build fails, `mso -h` remains available for diagnosis and a safe rerun.+The production build invokes Next's installed Node entrypoint directly instead of resolving+`next` through Bun's `.bin` remapper, avoiding Bun 1.3.x's intermittent WSL `bin metadata file`+corruption path.A child `curl | bash` process cannot modify its parent shell's `PATH`. The installer thereforechecks the **original invoking PATH** after creating the launchers and explicitly reports whetherdiff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex a26a5cc4..6df32be8 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Fixed**+- `install` survive Bun bin metadata corruption- `install` keep bootstrap guard shellcheck-clean- `install` guard earliest bootstrap prefix- `install` make bootstrap handoff truncation-safediff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 1f9b648a..07b36d7f 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -34,13 +34,16 @@ installer is therefore never executed while bytes are still arriving over the neThe installer core:1. resolves/creates the checkout and records whether this is a fresh install;-2. installs Bun/dependencies as needed;-3. creates private owner auth configuration when missing;-4. runs the production build;-5. installs `~/.local/bin/mso` **before service setup**, then attempts a guarded launcher in- `/usr/local/bin` when that directory is already on the invoking shell's PATH;-6. verifies whether the invoking shell will actually resolve `mso` after the child installer+2. installs and validates `~/.local/bin/mso` **before dependency installation or build**, then+ attempts a guarded `/usr/local/bin` launcher when that directory is already on the invoking+ shell's PATH;+3. verifies whether the invoking shell will actually resolve `mso` after the child installerreturns, and persists an idempotent `~/.local/bin` PATH fallback for future shells;+4. installs Bun/dependencies as needed;+5. creates private owner auth configuration when missing;+6. runs the production build through `node node_modules/next/dist/bin/next build`, bypassing Bun's+ package-bin remapper; if the Next package payload itself is absent, it performs one bounded+ `bun install --force` repair before failing;7. installs the `mso.service` system unit only when systemd is really PID 1 (not merely when a`systemctl` executable exists);8. enables the owner's lingering user manager needed by self-update/managed-app user units;@@ -111,6 +114,14 @@ If the installer reports that the current shell did not already contain a reachadirectory, use the exact PATH command it prints for that shell; the profile change is alreadypersisted for future shells.+If Bun 1.3.x reports `could not open bin metadata file` / `Bun failed to remap this bin`, that+is a package-bin metadata failure rather than evidence that the installed Next package is absent.+The supported installer does not use `bun run build` for the production build anymore: it invokes+Next's Node entrypoint directly. The CLI has already been installed at that point, so even an+unrelated build failure leaves `mso -h` available and the installer still exits non-zero with the+failed phase. Re-running the same one-liner is the supported recovery path.++## 2. Network exposureThe installer binds `127.0.0.1` by default. This is intentional: an authenticated MSO Ownerdiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 15566172..7080cef8 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -2,6 +2,29 @@Running log of what shipped each phase. Newest at top.+## 2026-08-30 — WSL Bun bin-metadata build resilience (SHIPPED)++A second real Ubuntu/WSL install reached checkout and a complete Bun 1.3.14 dependency install,+then failed at `bun run build` with `could not open bin metadata file` / `Bun failed to remap this+bin`. The important distinction is that Bun's package-bin metadata can be damaged while the actual+`node_modules/next` package payload remains readable. The previous ordering also meant this build+failure still happened before the CLI launcher was created, so an operator again ended with no+`mso -h` despite a valid checkout.++The installer now treats the CLI as the earliest post-checkout recovery surface: it creates and+self-checks the launcher before dependency installation, configuration, build, or service setup.+Production build no longer asks Bun to remap the `next` package binary; it executes+`node node_modules/next/dist/bin/next build` directly. A force reinstall is reserved for the+stronger condition that the package entrypoint itself is missing after dependency installation.+This keeps real compile errors fail-closed while avoiding a WSL-specific package-bin indirection.++Regression coverage asserts the new phase order, forbids an executable `bun run build` in the+installer core, and proves the direct Next entrypoint still runs while `node_modules/.bin/next` is+absent. A WSL-like end-to-end run using Bun 1.3.14 deliberately replaced `.bin/next` with a failing+launcher immediately after dependency installation; the production build still completed through+the direct Node entrypoint, the broken launcher remained broken (proving it was not silently fixed),+and the parent shell resolved `mso -h` successfully.+## 2026-08-30 — WSL installer reliability and recognized property fuzzing (SHIPPED)A WSL install exposed two assumptions that were true on the production VPS but not on a freshdiff --git a/lib/install-contract.test.ts b/lib/install-contract.test.tsindex 74ff4020..712c30c4 100644--- a/lib/install-contract.test.ts+++ b/lib/install-contract.test.ts@@ -102,8 +102,10 @@ describe("one-line installer contract", () => {expect(src).toContain('FRESH_INSTALL=1');});- it("installs the CLI before service setup and proves it against the invoking PATH", () => {+ it("installs the CLI before dependencies, build, and service setup and proves it against the invoking PATH", () => {const src = fs.readFileSync(CORE, "utf8");+ expect(src.indexOf("# ---- CLI on PATH")).toBeLessThan(src.indexOf("INSTALL_PHASE=dependencies"));+ expect(src.indexOf("# ---- CLI on PATH")).toBeLessThan(src.indexOf("INSTALL_PHASE=build"));expect(src.indexOf("# ---- CLI on PATH")).toBeLessThan(src.indexOf("# ---- systemd unit ----"));expect(src).toContain('PARENT_PATH="${PATH:-}"');expect(src).toContain('PARENT_CWD="$PWD"');@@ -121,6 +123,16 @@ describe("one-line installer contract", () => {expect(src).toContain('CLI launcher self-check failed');});+ it("bypasses Bun bin remapping for production build and repairs only a missing package payload", () => {+ const src = fs.readFileSync(CORE, "utf8");+ expect(src).toContain('NEXT_BIN="$DIR/node_modules/next/dist/bin/next"');+ expect(src).toContain('node "$NEXT_BIN" build');+ expect(src).not.toMatch(/^\s*bun run build\s*$/m);+ expect(src).toContain('if [ ! -f "$NEXT_BIN" ]; then');+ expect(src).toContain("bun install --force --frozen-lockfile || bun install --force");+ expect(src.indexOf('if [ ! -f "$NEXT_BIN" ]; then')).toBeGreaterThan(src.indexOf("bun install --frozen-lockfile || bun install"));+ });+it("requires systemd as PID 1 before service setup and gates onboarding on verified health", () => {const src = fs.readFileSync(CORE, "utf8");expect(src).toContain("systemd_ready()");diff --git a/scripts/install-core.sh b/scripts/install-core.shindex d9444c2f..708b8338 100755--- a/scripts/install-core.sh+++ b/scripts/install-core.sh@@ -328,43 +328,8 @@ elseficd "$DIR"-INSTALL_PHASE=dependencies-# ---- deps (compiles node-pty) -----info "installing dependencies…"-bun install --frozen-lockfile || bun install--INSTALL_PHASE=configuration-# ---- data dir + secrets (write .env.local only if absent) -----mkdir -p "$HOME/.mso" && chmod 700 "$HOME/.mso"--GEN_PW=""-if [ ! -f .env.local ]; then- SECRET="$(rand_hex 32)"- GEN_PW="$(rand_password)"- ( umask 077- cat > .env.local <<EOF-# mso — generated by install.sh. Private; NEVER commit.-OS_LOGIN_PASSWORD=$GEN_PW-OS_SESSION_SECRET=$SECRET-# SESSION_EXPIRY_HOURS=24-# OS_FS_READ_ROOTS=~:~/projects-# OS_FS_WRITE_ROOTS=~:~/projects-# OS_AUDIT_LOG=~/.mso/audit.log-EOF- )- chmod 600 .env.local- ok "wrote .env.local (login password + session secret generated)"-else- info ".env.local exists — left untouched (existing secrets preserved)"-fi--INSTALL_PHASE=build-# ---- build -----info "building (next build)…"-bun run build-INSTALL_PHASE=cli-# ---- CLI on PATH (before service setup so WSL/no-systemd still gets a CLI) ----+# ---- CLI on PATH (before deps/build/service so a partial WSL install still gets a CLI) ----# The web UI is one frontend; bin/mso reaches the same /api surface from a shell.BIN_DIR="${MSO_BIN_DIR:-$HOME/.local/bin}"mkdir -p "$BIN_DIR"@@ -444,6 +409,53 @@ elsefifi++INSTALL_PHASE=dependencies+# ---- deps (compiles node-pty) ----+info "installing dependencies…"+bun install --frozen-lockfile || bun install++INSTALL_PHASE=configuration+# ---- data dir + secrets (write .env.local only if absent) ----+mkdir -p "$HOME/.mso" && chmod 700 "$HOME/.mso"++GEN_PW=""+if [ ! -f .env.local ]; then+ SECRET="$(rand_hex 32)"+ GEN_PW="$(rand_password)"+ ( umask 077+ cat > .env.local <<EOF+# mso — generated by install.sh. Private; NEVER commit.+OS_LOGIN_PASSWORD=$GEN_PW+OS_SESSION_SECRET=$SECRET+# SESSION_EXPIRY_HOURS=24+# OS_FS_READ_ROOTS=~:~/projects+# OS_FS_WRITE_ROOTS=~:~/projects+# OS_AUDIT_LOG=~/.mso/audit.log+EOF+ )+ chmod 600 .env.local+ ok "wrote .env.local (login password + session secret generated)"+else+ info ".env.local exists — left untouched (existing secrets preserved)"+fi++INSTALL_PHASE=build+# ---- build ----+# Do not invoke Next through `bun run build` here. Bun resolves package binaries+# through node_modules/.bin metadata, and Bun 1.3.x can occasionally leave that+# metadata unreadable on WSL even when node_modules/next itself is intact. The+# package entrypoint is ordinary Node.js, so invoke it directly and bypass the+# remapper entirely. Only force-reinstall when the package payload itself is absent.+NEXT_BIN="$DIR/node_modules/next/dist/bin/next"+if [ ! -f "$NEXT_BIN" ]; then+ warn "Next.js package entrypoint is missing after bun install — repairing dependencies once…"+ bun install --force --frozen-lockfile || bun install --force+fi+[ -f "$NEXT_BIN" ] || die "Next.js package entrypoint is still missing after dependency repair: $NEXT_BIN"+info "building (next build via Node entrypoint)…"+node "$NEXT_BIN" build+INSTALL_PHASE=service# ---- systemd unit ----if [ "$DO_SERVICE" -eq 1 ] && systemd_ready; thendiff --git a/scripts/install.sh b/scripts/install.shindex 2f2b1dc7..140c30a3 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -12,7 +12,7 @@ set -Eeuo pipefailumask 077CORE_URL="${MSO_INSTALL_CORE_URL:-https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-core.sh}"-CORE_SHA256="913350997e568a279c6582e752d38151f20798cb1f1e471b557aba06b71821ad"+CORE_SHA256="59da7270bc2a86ee319b8c7bab7314efd186e232538bc487ab320c81c8ef24b6"CORE_EOF='# MSO_INSTALLER_CORE_EOF'TMP_INSTALLER=''