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.

feat(install): make upgrades agent-friendly

Rahman1f1df768beb6
diff --git a/AGENTS.md b/AGENTS.md
index fb403591..99d7d2e0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,36 @@ For debugging, integrations, refactors, deployments, and MCP work, use this loop
`CLAUDE.md`, or a trusted `SKILL.md`; implementation contracts belong in current docs;
volatile host facts stay in project/runbook notes.
+## Repository and worktree policy
+
+- `/home/rahman/projects/mso` on `main` is the **only canonical MSO checkout and release SSOT**.
+ Do not create task-specific `mso-*` sibling directories under `~/projects`.
+- Parallel coding/review tasks may use isolated Git worktrees only under
+ `~/.cache/mso-worktrees/mso-<task>`. Never let two sessions share one worktree, HEAD, or index.
+- Keep development worktrees out of `~/.mso`: that tree is private runtime/credential state and is
+ deliberately denied by MSO host-file guards. `~/.cache/mso-worktrees` is disposable developer isolation.
+- A worktree is disposable development isolation, **never an install or release source**.
+ Every user-deliverable change must be committed, reconciled into `main`, verified, and present
+ on `origin/main` before the task can be called shipped. The installer/updater consumes `main`.
+- Never delete or prune a dirty worktree. First preserve its tracked and untracked work in a
+ commit/branch or explicit archive, then verify that the deliverable commits are reachable from
+ `main` (or intentionally retained as non-release work).
+- Demo/review runtimes may have hidden internal checkouts, but they do not become a second source
+ of truth and must not be presented as another MSO project.
+
+## Install and update requests
+
+When a user asks an agent to "install MSO from this repo" or "update MSO", do not invent a parallel
+setup flow. Read `README.md` + `docs/INSTALL.md` and use the repository-owned entry points:
+
+- fresh install or legacy install without `mso update`: run the official `scripts/install.sh` bootstrap;
+- current install: prefer `mso update` or the equivalent Settings → About action;
+- never create a second checkout when `mso.service` already owns one; preserve `.env.local`, `~/.mso`,
+ and any dirty/diverged source rather than resetting it;
+- finish with `mso doctor` plus runtime health, and report only the remaining action the user must take;
+- when a provider credential is required, name the official place/endpoint to create it and where MSO
+ stores it, then use hidden/STDIN input. Never place a secret in argv, Git, documentation, or agent logs.
+
## MCP feature work
Use [`docs/MCP-FEATURE-IMPLEMENTATION.md`](./docs/MCP-FEATURE-IMPLEMENTATION.md) and the
diff --git a/CLAUDE.md b/CLAUDE.md
index c0876483..8182e053 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -194,7 +194,7 @@ to `resources/` (rr) and drive any project from one manifest:
## Deploy / ops (prod :4005 + demo :4006 are systemd, not Dokploy)
- `mso.service` (:4005, WorkingDir `/home/rahman/projects/mso`) serves
mso.rahmanef.com via `next start`.
-- `mso-demo.service` (:4006, WorkingDir `/home/rahman/projects/mso-demo`,
+- `mso-demo.service` (:4006, WorkingDir `/home/rahman/.mso/worktrees/mso-demo-runtime`,
`NEXT_PUBLIC_OS_DEMO=1` → no auth, mock data). It had been deleted at some point and
was **re-created 2026-08-03** to make UI/UX verification possible without logging in.
It binds **127.0.0.1 only, deliberately**: demo mode disables login, so a `0.0.0.0`
@@ -222,7 +222,7 @@ to `resources/` (rr) and drive any project from one manifest:
`git rm`, don't re-list the removed file in `git add`; prefer `git add -A` and
check `git status --short` before committing (a broken commit shipped once this way).
- **Deploy demo** (it IS running — `active`+`enabled`, 200 on 127.0.0.1:4006): from
- `/home/rahman/projects/mso-demo`: `git fetch origin -q && git reset --hard
+ `/home/rahman/.mso/worktrees/mso-demo-runtime`: `git fetch origin -q && git reset --hard
origin/main -q && bun run build && sudo systemctl restart mso-demo.service`.
Mind the cwd — running the sync from the prod dir is a classic slip.
- **Never `bun run build` in this checkout just to CHECK a change** — it is
@@ -284,13 +284,19 @@ to `resources/` (rr) and drive any project from one manifest:
static Content-Types correct.
## Rules in force
-- **Only ONE session edits mso at a time.** One checkout, one `HEAD`, one index.
- Two concurrent fix-loops collided three times on 2026-06-15: a `git reset --hard`
- wiped uncommitted work twice, and a shared-index sweep bundled one session's files
- into the other's commit. Before a long loop, `git log --oneline -10` — unexpected
- recent commits mean another session is live, so stop and run solo. (It happened
- again on 2026-07-28: `779f2ba` landed mid-session from elsewhere. Staging explicit
- paths instead of `git add -A` is what kept the commits clean.)
+- **One canonical checkout; parallel work only through isolated hidden worktrees.**
+ `/home/rahman/projects/mso` on `main` is the only canonical checkout and release SSOT.
+ Never create task-specific `mso-*` siblings under `~/projects` and never let two
+ sessions share one worktree, `HEAD`, or index. If parallel work is necessary, use one
+ Git worktree per task under `~/.cache/mso-worktrees/mso-<task>`. Never put a development
+ checkout under `~/.mso`: host-file security deliberately treats that entire tree as private state. The older one-checkout rule
+ existed because shared-index sessions repeatedly wiped/bundled each other's work;
+ isolated worktrees solve that collision without creating another source of truth.
+ A worktree is development-only: preserve its tracked/untracked WIP, reconcile every
+ user-deliverable commit into `main`, verify there, and ship through `bun run ship`.
+ Do not call a feature shipped while it exists only in a worktree/feature branch; the
+ installer and updater intentionally deliver only `origin/main`. Never prune a dirty
+ worktree until its intended work is committed/archived and accounted for.
- Max 200 lines/file, single responsibility, shadcn primitives only, theme tokens
not hex, mobile-first. Barrel-only cross-slice imports.
- `/api/v1` host ops go through `lib/host` (bounds + realpath checks) — never call
@@ -362,6 +368,15 @@ the real runtime and working analogue before changing a tool or skill contract.
reads it (session-gated); there is deliberately **no MCP tool** for it, or a
compromised token could check whether it had been noticed.
+## Install/update requests from an AI agent
+When a user points an agent at this repository and asks to install or update MSO, the agent must use
+`scripts/install.sh` / `mso update`, not hand-roll a competing setup. The installer is also the backward-
+compatible bridge for old installations that predate `mso update` and Settings → About: it detects the
+active service checkout, preserves `.env.local` + `~/.mso`, and updates in place. Never create a second
+install beside an owned service or reset dirty/diverged source. End with `mso doctor` and health proof.
+Credential prompts remain hidden/STDIN; tell the user where to create/store a required key, never put it
+on argv or in an agent transcript.
+
## CLI (`bin/mso`) — the web UI is only one frontend
`bin/mso` reaches the same `/api` surface from a shell — every route has a named verb
(enforced by a test in `bin/mso.test.ts`), plus `doctor`, `completion` and `--base`.
diff --git a/README.md b/README.md
index 68138bac..9e69eee7 100644
--- a/README.md
+++ b/README.md
@@ -103,6 +103,24 @@ Demo mode skips real login, forces mock data, blocks live host API access, and s
## Install
+### Install or update with an AI agent
+
+If your AI agent can open this repository and run commands on your server, your request can be as
+short as:
+
+```text
+Install or update MSO from this repo: https://github.com/rahmanef63/mso
+```
+
+The repository carries the rest of the contract. The agent should use MSO's official installer/update
+paths rather than reconstructing setup commands by hand, preserve an existing `.env.local` and
+`~/.mso`, update the checkout already owned by `mso.service` instead of creating a second clone, and
+finish with `mso doctor`. For a current install it may use `mso update` (the same lifecycle exposed by
+Settings → About). If the installed build is old enough that `mso update` or the About updater does not
+exist yet, the universal upgrade/recovery path is simply to re-run the current one-line installer below.
+Only credentials or choices that cannot be inferred should come back to the user; provider secrets must
+stay in hidden/STDIN onboarding prompts rather than command arguments or chat logs.
+
Run one command on the Linux server as your normal user, **not root**:
```bash
@@ -159,6 +177,16 @@ skills:
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- -y
```
+Already installed? Use the least surprising path:
+
+- **Current MSO:** `mso update`, or Settings → About → Update.
+- **Older/legacy MSO where that updater is missing or broken:** re-run the same one-line installer.
+ It discovers an existing `mso.service` WorkingDirectory before choosing a default directory, updates
+ that checkout in place, preserves `.env.local` + `~/.mso`, and does not repeat onboarding unless
+ `--onboard` is requested.
+- **Recovery:** re-running the installer is also the supported way to repair installer/runtime wiring;
+ it refuses dirty/diverged source instead of resetting user work.
+
After installation, the installer prints whether the current shell can already resolve `mso`.
On the normal Ubuntu/WSL PATH (which includes `/usr/local/bin`) these work immediately:
@@ -251,6 +279,22 @@ addresses drop it. Bind wider only when the network/firewall design explicitly r
Useful installer controls:
+| Control | What it is for |
+|---|---|
+| `--dir PATH` | Explicit install directory. Normally omit it so an existing service checkout is detected automatically. |
+| `--ref REF` | Development/testing ref. Normal installs and self-update use `main`. |
+| `--port N` | Local MSO port; default `4005`. |
+| `--bind ADDR` | Listen address; default `127.0.0.1`. Do not use `0.0.0.0` unless your firewall/TLS design explicitly requires it. |
+| `--no-service` | Build only; do not install the systemd service. |
+| `--onboard` | Run guided onboarding even while upgrading an existing install. |
+| `--no-onboard` | Install/update without starting onboarding. |
+| `-y`, `--yes` | Safe non-interactive defaults; does not connect accounts or install optional apps/skills. |
+| `--uninstall` | Remove the systemd unit and MSO CLI links while keeping code and `~/.mso`. |
+| `-h`, `--help` | Print the installer contract without changing the host. |
+
+Equivalent public environment overrides are `MSO_DIR`, `MSO_REF`, `MSO_PORT`, `MSO_BIND`, and
+`MSO_REPO`. Command-line flags are clearer for people; environment overrides are useful to automation.
+
```bash
# force onboarding even while updating an existing install
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --onboard
@@ -258,11 +302,8 @@ curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install
# update/build without onboarding
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --no-onboard
-# other existing controls
-curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --port 4005
-curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --bind 0.0.0.0
-curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --no-service
-curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --uninstall
+# explicit non-default location/port (only when you intentionally need them)
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --dir "$HOME/mso" --port 4005
```
There is also a no-login install guide at **<https://mso.rahmanef.com/install>**. **Browser
diff --git a/app/install/page.test.ts b/app/install/page.test.ts
index 439468a4..0de58273 100644
--- a/app/install/page.test.ts
+++ b/app/install/page.test.ts
@@ -18,4 +18,13 @@ describe("public install guide", () => {
expect(source).toContain("mso skills available");
expect(source).toContain("mso skills install ponytail caveman rtk -y");
});
+
+ it("gives AI agents one canonical install/update path including legacy upgrades", () => {
+ expect(source).toContain("Install or update MSO from this repo");
+ expect(source).toContain("mso update");
+ expect(source).toContain("Settings → About");
+ expect(source).toContain("older build");
+ expect(source).toContain("preserves existing configuration/state");
+ });
+
});
diff --git a/app/install/page.tsx b/app/install/page.tsx
index 6d20b975..e2026062 100644
--- a/app/install/page.tsx
+++ b/app/install/page.tsx
@@ -13,6 +13,7 @@ export const metadata: Metadata = {
};
const INSTALL = "curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash";
+const AGENT_PROMPT = "Install or update MSO from this repo: https://github.com/rahmanef63/mso";
const REQUIREMENTS = [
["A Linux server you own", "A $5 VPS is enough. Debian/Ubuntu, Fedora and Arch are covered by the installer."],
@@ -91,6 +92,19 @@ export default function InstallPage() {
</dl>
</section>
+ <section className="mb-12 rounded-lg border border-border p-4">
+ <h2 className="text-lg font-semibold">Using an AI agent?</h2>
+ <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+ Give it the repository and one sentence. The repo tells capable agents to use the official
+ installer/update path, preserve an existing install, and verify with <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">mso doctor</code>.
+ </p>
+ <Copy text={AGENT_PROMPT} />
+ <p className="mt-3 text-sm leading-relaxed text-muted-foreground">
+ Already installed? Current MSO uses <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">mso update</code> or Settings → About.
+ For an older build where those do not exist, re-run the installer above; it upgrades the service checkout in place and preserves existing configuration/state.
+ </p>
+ </section>
+
<section className="mb-12">
<h2 className="mb-5 text-lg font-semibold">Five steps</h2>
<ol className="space-y-8">
diff --git a/claude-skills/mso-repo-work/SKILL.md b/claude-skills/mso-repo-work/SKILL.md
index a73d8a09..669d867a 100644
--- a/claude-skills/mso-repo-work/SKILL.md
+++ b/claude-skills/mso-repo-work/SKILL.md
@@ -11,6 +11,19 @@ metadata:
For multi-step work, call `workflow_start` directly. It already searches skills and prior recipes, resolves aliases such as `os-vps` → `mso`, reports the current toolset, and returns repository context. Carry its exact `workflow_id` on every operational call in that run.
+## Canonical checkout and isolation
+
+- `/home/rahman/projects/mso` on `main` is the canonical MSO checkout and the only release SSOT.
+- Never create task-specific `mso-*` siblings in `~/projects`. When isolation is genuinely needed,
+ create/use one Git worktree per task under `~/.cache/mso-worktrees/mso-<task>`.
+ Do not use `~/.mso` for source worktrees; it is MSO private state and host-file guards deny it.
+- Never share one worktree, index, or HEAD between concurrent sessions.
+- Worktree completion is not release completion. Preserve the work, reconcile the deliverable commits
+ into `main`, verify there, and ship through the repository release path. A user installing MSO only
+ receives what is committed on `origin/main`.
+- Before pruning/removing a worktree, ensure it is clean or explicitly archived and that all intended
+ release commits are reachable from `main`.
+
## Route selection
- One or two direct file operations: bounded `fs_*` tools.
@@ -23,6 +36,7 @@ A useful first batch is:
set -euo pipefail
git status -sb
git log -1 --oneline --decorate
+git worktree list --porcelain
rg -n "<target>" app lib frontend scripts docs
```
@@ -30,4 +44,4 @@ Do not perform one tool call per folder. Read the exact files returned by search
## Finish
-Run the smallest relevant test first, then typecheck/lint or the project verification command. For MSO itself, a check build must use `scripts/verify-build.sh`; never run `next build` in the live checkout merely to test compilation. Review `git diff --check`, `git diff --stat`, and the final diff before `workflow_finish`.
+Run the smallest relevant test first, then typecheck/lint or the project verification command. For MSO itself, a check build must use `scripts/verify-build.sh`; never run `next build` in the live checkout merely to test compilation. Review `git diff --check`, `git diff --stat`, and the final diff before `workflow_finish`. If the task is user-deliverable, do not call it shipped while its commits exist only on a feature/worktree branch.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index fc8146da..5101e5b2 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”.
**Added**
+- `install` make upgrades agent-friendly
- `agent` add interactive slash palette
- `agent` add project-aware slash skills
- `agent` persist terminal and MCP sessions
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index f1e5804b..f7c98e5d 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -27,6 +27,13 @@ Run as the normal server user, not root:
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
```
+An AI agent with repository + shell access should treat that command as the public install/legacy-upgrade
+SSOT. A user only needs to say `Install or update MSO from https://github.com/rahmanef63/mso`.
+The agent must detect and preserve an existing install rather than creating another clone, use `mso update`
+for a current install when available, fall back to this installer for older builds that predate the updater,
+and finish with `mso doctor`. It should ask the user only for non-inferable choices/credentials; secrets
+belong in MSO's hidden/STDIN onboarding prompts, never CLI argv or chat transcripts.
+
`scripts/install.sh` is intentionally a tiny bootstrap. It downloads `scripts/install-core.sh`
completely into a private temporary file, retries transient transfers, checks a committed SHA-256,
requires the exact EOF marker, runs `bash -n`, and only then executes the payload. The large
@@ -66,6 +73,30 @@ Useful flags:
--no-onboard suppress automatic onboarding
-y, --yes non-interactive safe defaults; no external accounts/apps/skills
--uninstall remove the system unit; keep code + ~/.mso
+-h, --help print this contract without changing the host
+```
+
+Public environment equivalents are `MSO_DIR`, `MSO_REF`, `MSO_PORT`, `MSO_BIND`, and `MSO_REPO`.
+`MSO_BIN_DIR`, `MSO_SYSTEM_BIN_DIR`, `MSO_SKILL_DIR`, `MSO_UPDATE_STATE_DIR`, and
+`MSO_UPDATE_LOCK_TIMEOUT_SECONDS` are advanced operator/test overrides rather than normal install UX;
+avoid them unless you are deliberately changing those boundaries.
+
+### Upgrading an older MSO install
+
+Modern installations update through **Settings → About** or `mso update`. Releases from before those
+surfaces existed cannot invoke an updater they do not have. For those installations, re-run the current
+one-line installer exactly as if installing fresh. Before choosing `$HOME/mso`, it reads the active
+`mso.service` WorkingDirectory and upgrades that checkout in place. Existing `.env.local` credentials and
+`~/.mso` state are preserved; onboarding does not repeat unless `--onboard` is supplied.
+
+If the old install has no systemd service, pass its known checkout explicitly with `--dir PATH` (or
+`MSO_DIR`). The installer refuses an uncommitted checkout or unsafe concurrent update rather than
+resetting local work. After the bridge upgrade, normal future maintenance is simply:
+
+```bash
+mso update status
+mso update
+mso doctor
```
The public bootstrap is delivered through pipeline stdin, and the core deliberately does not
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 1dcc81c8..7e54e386 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -2,6 +2,26 @@
Running log of what shipped each phase. Newest at top.
+## 2026-09-01 — Install/update DX and legacy upgrade bridge — SHIPPED
+
+The public installation contract is now explicitly agent-friendly and backward-compatible. A user may
+hand a capable AI agent only the MSO repository URL and ask it to install or update; `AGENTS.md`,
+`CLAUDE.md`, README and the public `/install` page all route that request to the repository-owned
+installer/updater instead of a hand-built parallel setup. Current installs use `mso update` or Settings →
+About, while older installs that predate both surfaces bridge forward by re-running the same verified
+one-line installer. The installer discovers an existing `mso.service` WorkingDirectory before selecting a
+default checkout, preserves `.env.local` and `~/.mso`, refuses dirty/diverged source, and upgrades in
+place rather than creating a second clone.
+
+README's **Useful installer controls** now covers every public flag and environment override advertised by
+`install-core.sh`, with safe guidance for bind/ref overrides. A new contract test derives those controls
+from `--help` and fails when README or `docs/INSTALL.md` drifts. Upgrade completion is also state-aware:
+fresh installs receive first-device pairing guidance, while existing installs say `updated`, confirm
+preserved state, and point to `mso update`, Settings → About, `mso doctor`, onboarding and the legacy
+installer fallback without replaying first-run instructions. Repository worktree policy was consolidated
+at the same time: `~/projects/mso`/`origin/main` remains the release SSOT and parallel worktrees stay under
+`~/.cache/mso-worktrees` until verified and reconciled.
+
## 2026-08-31 — MSO terminal agent + provider-backed deployment setup — SHIPPED
**Shipped milestone.** The release passed the repository/security gates and the live health endpoint returned the release build SHA before this status was promoted. The standalone deployment-assistance pattern from `rahmanef63/si-coder-agent` is now absorbed into MSO's own architecture instead of spawning a second agent runtime. Installed Hermes and its public CLI were used as interaction references only; MSO has original terminal artwork, its own tool catalog, and its existing auth/audit model.
diff --git a/lib/install-docs-contract.test.ts b/lib/install-docs-contract.test.ts
new file mode 100644
index 00000000..15c0fa0c
--- /dev/null
+++ b/lib/install-docs-contract.test.ts
@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const CORE = path.join(__dirname, "../scripts/install-core.sh");
+const README = fs.readFileSync(path.join(__dirname, "../README.md"), "utf8");
+const INSTALL = fs.readFileSync(path.join(__dirname, "../docs/INSTALL.md"), "utf8");
+const AGENTS = fs.readFileSync(path.join(__dirname, "../AGENTS.md"), "utf8");
+const core = fs.readFileSync(CORE, "utf8");
+const help = execFileSync("bash", [CORE, "--help"], { encoding: "utf8" });
+
+function publicFlags() {
+ return help.split("\n")
+ .filter((line) => /^ -/.test(line))
+ .flatMap((line) => line.match(/--?[a-z][a-z-]*/g) ?? []);
+}
+
+function publicEnv() {
+ return help.match(/^Env:\s+(.+)$/m)?.[1].match(/MSO_[A-Z0-9_]+/g) ?? [];
+}
+
+describe("installer documentation contract", () => {
+ it("keeps every public installer flag and env override in README + INSTALL.md", () => {
+ expect(publicFlags().length).toBeGreaterThan(5);
+ expect(publicEnv().length).toBeGreaterThan(3);
+ for (const token of [...publicFlags(), ...publicEnv()]) {
+ expect(README, `README missing ${token}`).toContain(token);
+ expect(INSTALL, `INSTALL.md missing ${token}`).toContain(token);
+ }
+ expect(README).toContain("Useful installer controls");
+ });
+
+ it("documents one AI-agent path and the legacy-upgrade bridge", () => {
+ for (const doc of [README, INSTALL, AGENTS]) {
+ expect(doc).toContain("mso doctor");
+ expect(doc).toContain("mso update");
+ expect(doc).toContain("scripts/install.sh");
+ }
+ expect(README).toContain("Install or update MSO from this repo");
+ expect(INSTALL).toContain("Upgrading an older MSO install");
+ });
+
+ it("keeps the installer backward-compatible with an existing service checkout", () => {
+ const detect = core.indexOf('systemctl show -p WorkingDirectory --value "$SERVICE"');
+ const fresh = core.indexOf('[ -d "$DIR/.git" ] || FRESH_INSTALL=1');
+ const checkout = core.indexOf("INSTALL_PHASE=checkout");
+ expect(detect).toBeGreaterThan(0);
+ expect(detect).toBeLessThan(fresh);
+ expect(detect).toBeLessThan(checkout);
+ expect(core).toContain('info "found existing service → updating $DIR"');
+ expect(core).toContain('if [ ! -f .env.local ]; then');
+ expect(core).toContain('.env.local exists — left untouched (existing secrets preserved)');
+ });
+
+ it("prints modern update surfaces plus a legacy fallback after installation", () => {
+ expect(core).toContain("Update: mso update");
+ expect(core).toContain("Settings → About");
+ expect(core).toContain("Legacy: re-run the official one-line installer");
+ expect(core).toContain('ok "mso updated at $DIR"');
+ const pairing = core.indexOf("Pair your first device after the API is running");
+ const freshGuard = core.lastIndexOf('if [ "$FRESH_INSTALL" -eq 1 ]; then', pairing);
+ expect(freshGuard).toBeGreaterThan(0);
+ });
+});
diff --git a/scripts/install-core.sh b/scripts/install-core.sh
index 833087f9..fe66fabf 100755
--- a/scripts/install-core.sh
+++ b/scripts/install-core.sh
@@ -732,13 +732,19 @@ else
LOG_STATUS="no system service installed"
fi
-ok "mso installed at $DIR"
+if [ "$FRESH_INSTALL" -eq 1 ]; then
+ ok "mso installed at $DIR"
+else
+ ok "mso updated at $DIR"
+ info "existing .env.local and ~/.mso state preserved"
+fi
cat <<EOF
- Runtime: $OPEN_STATUS
- Env: $DIR/.env.local
+ Runtime: $OPEN_STATUS
+ Env: $DIR/.env.local
EOF
[ -n "$GEN_PW" ] && printf ' Password: %s (shown once — save it now; edit OS_LOGIN_PASSWORD in .env.local + service refresh to change)\n' "$GEN_PW"
+if [ "$FRESH_INSTALL" -eq 1 ]; then
cat <<EOF
Pair your first device after the API is running (device approval is a browser allowlist, not standards-based 2FA):
@@ -749,11 +755,17 @@ cat <<EOF
node $DIR/scripts/approve-device.js --list # see the pending id
node $DIR/scripts/approve-device.js <deviceId> "my phone" # approve it
4. In that SAME browser origin, click "Check again". Approve later devices from Settings → Devices.
+EOF
+fi
+cat <<EOF
- Logs: $LOG_STATUS
- Doctor: mso doctor (or: mso doctor --fix for safe local repairs)
- Update: re-run this installer (pull + verify + build + service refresh), or --uninstall to remove
- Listen: $BIND:$PORT (change with --bind / MSO_BIND)
+ Logs: $LOG_STATUS
+ Doctor: mso doctor (or: mso doctor --fix for safe local repairs)
+ Onboard: mso onboard
+ Update: mso update (or Settings → About in the web UI)
+ Legacy: re-run the official one-line installer to upgrade/recover an older install
+ Uninstall: re-run the installer with --uninstall
+ Listen: $BIND:$PORT (change with --bind / MSO_BIND)
Security: verify from OUTSIDE the box — \`curl -m5 http://<public-ip>:$PORT/api/health\`
run on your laptop is the only test that proves what is reachable.
Review ~/.mso/audit.log.
diff --git a/scripts/install.sh b/scripts/install.sh
index 9919893c..3cb9358b 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="6cb075743c17406dfde8d57a04ad2e48b6a792aab72284aeb93570f9103417a8"
+CORE_SHA256="104a7ebc51b3d5a3ff068697eb0d263e45959656125e1d580612ca64206126e7"
CORE_EOF='# MSO_INSTALLER_CORE_EOF'
TMP_INSTALLER=''