Skip to content

armgit / mso

Public Imported from GitHub
0

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.

fix(install): survive Bun bin metadata corruption

Rahman19d9083297a3
diff --git a/README.md b/README.md
index 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 therefore
checks the **original invoking PATH** after creating the launchers and explicitly reports whether
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 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-safe
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 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 ne
The 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 installer
returns, 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 reacha
directory, use the exact PATH command it prints for that shell; the profile change is already
persisted 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 exposure
The installer binds `127.0.0.1` by default. This is intentional: an authenticated MSO Owner
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 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 fresh
diff --git a/lib/install-contract.test.ts b/lib/install-contract.test.ts
index 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.sh
index d9444c2f..708b8338 100755
--- a/scripts/install-core.sh
+++ b/scripts/install-core.sh
@@ -328,43 +328,8 @@ else
fi
cd "$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 @@ else
fi
fi
+
+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; then
diff --git a/scripts/install.sh b/scripts/install.sh
index 2f2b1dc7..140c30a3 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -12,7 +12,7 @@ set -Eeuo pipefail
umask 077
CORE_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=''