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.

6.6 KB
Raw Blame

Handover — MSO state as of 2026-10-31

For whoever picks this up next, human or agent. Read this first, then docs/MSO-MIGRATION.md's header for the phase table.

Where the repo is

main = 3bf32e81   (PR #194 merged)
working tree clean

Everything described here is merged and pushed. Nothing is mid-flight.

What was asked, and what came out of it

The request was "migrate MSO from Next.js to Svelte, Bun and Rust, then keep going". The honest outcome after ~45 hours of work across two sessions is that the migration was measured and mostly argued away, while the parts that did ship are worth more than the migration would have been.

Phase State Why
0 Instrumentation shipped five perf scripts, gate running in CI
1 Bun tooling shipped bun install builds node-pty via a committed patch
2 Portable core shipped 117/117 route handlers ≤ 15 LOC, lib/ free of static next/*
3 Svelte island cancelled a hello-world island costs 15.75 KiB gzip; React is already resident
4 Slice-by-slice cancelled a hybrid adds a ~17.7 KiB second runtime beside React, net +11.7 KiB
5 Shell swap not started the only remaining work, and the only place the byte win can arrive
6 Rust sidecar no-go proxy costs 15 µs/request; a sidecar adds 200–500 µs of loopback hop

Numbers that decide things

Measured, on an idle host, reproducible with the commands in docs/BENCH-BEFORE.md.

bundle initial          270.8 KiB gzip, of which framework floor 129.6 KiB (47.9%)
first-load JS           910.2 KiB browser-measured
LCP (Slow 4G, 4x CPU)   3.15 s desktop / 2.96 s mobile
TBT                     173 ms desktop / 101 ms mobile  (target was 150 ms)
hydration chain         last JS 2.80 s -> mount 2.52 s -> icons 3.08 s -> LCP 3.13 s

LCP is hydration-bound, not paint-bound: the shell mounts only after ~910 KiB of JS arrives. That is why Phase 5 is the only lever left.

The SvelteKit floor was measured independently at 33.07 KiB gzip (real build, browser- verified), so a full swap is 132.7 out, 33.07 in = −99.6 KiB. That number is the entire case for Phase 5, and it only applies to a full swap, never to a hybrid.

Code facts worth knowing before you touch anything

  • 117 route handlers, all ≤ 15 LOC, all tested. Coverage went 59/117 → 117/117 this session.
  • lib/ has zero static next/* imports. One documented dynamic import("next/headers") remains in lib/auth/require-session.ts — cookies() is request-scoped and has no web-standard equivalent in place. Moving it out is 54 mechanical edits, deliberately not done.
  • Auth is not uniform, and that is deliberate: verifyAuth returning 401 vs requireSession/requireOwner returning 403 with a different key. app/api/status-contract.test.ts pins the twenty routes where getting this wrong is an RCE, a write, a secret read or a role escalation.
  • app/api/skills returns 409 ambiguous when a bare skill name matches several projects. Do not "fix" it to 404 — returning one project's instructions under another's name is the bug that branch exists to prevent.
  • .well-known/* routes are public by design. Their tests assert they stay public. Adding a session gate there breaks every MCP client.

The gate, and how to run it

bash scripts/gates-12.sh          # fast, ~2 min, deterministic checks
bash scripts/gates-12.sh full     # ~20 min, what CI runs: coverage + build + perf

fast prints why each skipped step was skipped; full reports 17 passed / 0 failed / 0 skipped. CI runs the same set on GitHub. A Turbopack build warning fails the release gate — if you add an fs.* call whose path is a variable or env var, it needs /* turbopackIgnore: true */ or the whole project gets traced.

The perf gate compares TBT only on the same core count and at low load. It has been wrong once: it compared a 16-core workstation baseline against a 4-core GitHub runner and blocked a PR for a property of the runner.

Traps that cost real time this session

  1. scripts/verify-build.sh archives HEAD, not the working tree. A fix must be committed before the gate can see it. Two build cycles were lost to this.
  2. docs/CHANGELOG.md is generated and always conflicts. .gitattributes now marks it merge=ours, but that is inert until git config merge.ours.driver true.
  3. main moves often (TUI work is active on another track). Three rebases were needed on one PR.
  4. gh CLI is not authenticated on this box and SSH id_ed25519_rahmanef63 is rejected by GitHub. Pushing works over HTTPS with the PAT stored in ~/.mso/private/infra-providers.json under users/rahman/connections/github/gh-rahmanef63. Do not paste that token into chat.
  5. /tmp is a 9.8 GB tmpfs shared by parallel agents; it filled mid-build once and failed a verification with No space left on device, which looks like a code failure and is not.

If you are picking this up

Do not start Phase 5 without deciding it is worth 8–12 months. The measured upside is −99.6 KiB gzip and LCP 3.15 → ~2.5 s. The measured downside is re-expressing 20,028 LOC of appshell and 54,181 LOC of slices, with two confirmed hard spots: the window store's synchronous useSyncExternalStore open path, and the per-surface chunk split that Vite can silently undo by hoisting shared dependencies into the entry chunk.

Cheaper work that still has real value, in order:

  1. LCP. It is 3.15 s and set by first paint of the mounted shell. Cheapest untried lever: take the wallpaper artwork off the critical path — it is already an IMG LCP element on mobile.
  2. Coverage of lib/ is 42.6 % functions. Route coverage is now complete; lib/host and lib/managed-apps are where the untested logic lives, and both touch the filesystem and process control.
  3. bun test parity. scripts/* run under Bun, the vitest suite does not (it fails on vi.mock, jsdom, localStorage assumptions). Bun's runner has no coverage thresholds, so this would be a second way to run tests, not a replacement — decide whether that is worth it.

Documents, in reading order

  1. docs/MSO-MIGRATION.md — the plan, its phase table, and every retraction this work produced. §4.0 is the corrected Phase 4 reasoning. It is authoritative over BENCH-AFTER.md.
  2. docs/BENCH-BEFORE.md / docs/BENCH-AFTER.md — the measured comparison, including the deltas that are zero and the ones inside the noise band.
  3. docs/PROGRESS.md — dated entries, newest first, with the evidence for each.
  4. docs/DEVELOPMENT.md — the gate commands and what each one enforces.