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(ship): one command that changelogs, pushes, rebuilds and verifies

Rahman2d5e0fc3ea11
diff --git a/CLAUDE.md b/CLAUDE.md
index 3674f47b..4a4d651b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -37,8 +37,21 @@ agent — it runs AS a host process and controls its own machine.
**The doc set, and the one rule.** `docs/PROGRESS.md` is the SSOT; everything else is
history, a live plan, or reference. Append to PROGRESS when you ship — do not start a
-second log. (`docs/CHANGELOG.md` was exactly that and was merged back in; the root
-`progress.md` is gitignored local scratch and claims authority it does not have.)
+second HAND-WRITTEN log. (`docs/CHANGELOG.md` was exactly that once and was merged
+back in; the root `progress.md` is gitignored local scratch and claims authority it
+does not have.) `docs/CHANGELOG.md` exists again as of 2026-08-11 but is **generated
+from git subjects** by `scripts/gen-changelog.mjs` and gated stale-by-`gates.sh`, so
+there is nothing to keep in sync and no way for it to disagree with history. PROGRESS
+is the WHY; CHANGELOG is the WHAT, and it is what Settings → About renders as
+"What's new" so a shipped change is visible in the running app.
+
+**Shipping is `bun run ship "<conventional commit>"`, not `git push`.** Prod is
+systemd with NO webhook, so a pushed commit changes nothing the owner can see until
+someone rebuilds. The script does changelog → commit+push (gates run) → build →
+restart → and then verifies the served CSS chunk actually resolves, which is the
+mismatch CLAUDE.md warns about, checked rather than remembered. Order is
+load-bearing: the changelog is derived, so regenerating it AFTER the commit leaves it
+one commit behind forever; and build-then-restart, never the reverse.
Deleted 2026-07-28 as dead: `SHELL-INTEGRATION-PLAN.md` and `SYNC-PLAN.md` (both target
sibling repos that do not exist on this machine), `browser-agent-plan.md` (the retired
Playwright sidecar), `SIXFIX-PLAN.md` (a finished dated fix list). Nothing linked to any
diff --git a/app/api/changelog/route.ts b/app/api/changelog/route.ts
new file mode 100644
index 00000000..09898679
--- /dev/null
+++ b/app/api/changelog/route.ts
@@ -0,0 +1,28 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { requireSession } from "@/lib/auth/require-session";
+
+// Serves docs/CHANGELOG.md so Settings → About can show "What's new" in the running
+// app. The point of the whole thing: a shipped change should be visible where the
+// owner already is, not only in a terminal they would have to go and open.
+//
+// Session-gated like every other read here. The file is generated from git subjects,
+// so it carries nothing secret — but it does enumerate what this deployment is, and
+// that is not something an unauthenticated visitor needs.
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const LIMIT = 40_000; // ~60 days of subjects; the file is capped upstream anyway
+
+export async function GET() {
+ if (!(await requireSession())) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ // process.cwd() is the app dir — the same anchor app/api/skills uses.
+ const file = path.join(process.cwd(), "docs", "CHANGELOG.md");
+ const md = await fs.readFile(file, "utf8").catch(() => null);
+ if (md === null) {
+ // Not an error: a checkout that has never run the generator simply has none.
+ return NextResponse.json({ markdown: "", generated: false });
+ }
+ return NextResponse.json({ markdown: md.slice(0, LIMIT), generated: true });
+}
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
new file mode 100644
index 00000000..e551d2f7
--- /dev/null
+++ b/docs/CHANGELOG.md
@@ -0,0 +1,109 @@
+# Changelog
+
+**Generated — do not edit.** `node scripts/gen-changelog.mjs`, run by `bun run ship`.
+Newest first. `docs/PROGRESS.md` is the source of truth for *why* a change was made;
+this is the *what*, and it is what Settings → About shows as “What's new”.
+
+## 2026-08-11
+
+**Added**
+
+- `ship` one command that changelogs, pushes, rebuilds and verifies
+- `shells` Windows/iOS/Android to their 2026 specs, plus a backup for local state
+
+**Fixed**
+
+- `ai` Codex DOES do tool calling — implement it instead of announcing it cannot
+- `pwa,chat` notch clearance, a doubled iOS inset, and an assistant that was lying
+
+**Tests**
+
+- `e2e` a browser that actually loads the page — and the three bugs it found
+
+**Docs**
+
+- `progress` log the shell-spec pass, the springs, and the backup
+
+## 2026-08-10
+
+**Added**
+
+- give Alfa the reach MCP has, and a gate so they cannot drift apart again
+- `mcp` managed-app logs and lifecycle, tiered by blast radius not by layer
+- `mcp` an MCP server so ChatGPT, Claude.ai or Cursor can drive this VPS
+
+**Fixed**
+
+- `cli` four missing verbs, a prod-breaking build, and a silently-wrong --base
+- close the four cheap findings from the tool-surface parity audit
+- `mcp` the audit trail was recording refused commands as successes
+- `audit` stop a test run appending to the owner's forensic trail
+- `mcp` record what an MCP token did — the trail it was bypassing
+- `a11y,perf` name the dock icons, announce login errors, stop the resize storm
+- `perf,ux` halve the boot API calls, unstick the dead chunk spinner, cut 9 orphans
+
+**Faster**
+
+- get the shell chrome and the Alfa catalog out of first load
+
+**Changed**
+
+- delete five retired subsystems nothing could reach
+
+**Docs**
+
+- `progress` log the three-surface parity audit and what it fixed
+- `progress` log the MCP server and what was verified live
+- cut five finished plans, trim PROGRESS's tail, log the audit follow-up
+
+## 2026-08-04
+
+**Fixed**
+
+- `hydration` render the shell after mount — zero mismatches anywhere
+- `hydration` kill 3 of 4 React #418 sources; mobile contrast + back labels
+- `css` un-break every border-color utility, and make Android's Back visible
+
+## 2026-08-03
+
+**Added**
+
+- `ci` real dependency + build gates, and fix the sharp CVE they caught
+- migrate pnpm -> bun, and fix what the audit actually found
+- `shell` Docs app, a state-aware dock, and quicklinks back to the owner
+- `cli` print a paste-ready command under every device
+- `cli` complete API coverage, doctor, completion, global options
+- `cli` device pending + revoke all, per-command help, version
+- `cli` add `mso` CLI + agent skills so the web UI is one frontend, not the product
+
+**Fixed**
+
+- `a11y` raise 4 mobile touch targets to the WCAG 24x24 floor
+- `security` close 3 of 4 rm -rf bypasses, and stop a corrupt file wiping the device allowlist
+- `cli` name the near-miss flag, and report what's left after a revoke
+- `cli` make `device` a subcommand group and say what an unknown command was
+
+**Faster**
+
+- keep the OS shell out of every route, stop sleeping on every stats poll
+
+**Changed**
+
+- delete 836 net lines of metadata and dead exports nothing reads
+- `quicklinks` owner's links become owner's data, repo keeps a neutral fallback
+- rename os-vps -> mso across code, config and prod wiring
+
+**Docs**
+
+- reconcile every live doc against what the box actually does
+- `progress` record the 2026-08-03 bun migration, audit and gate work
+
+**Chores**
+
+- drop the one-shot contrast tuner nothing invokes
+
+## 2026-08-02
+
+**Other**
+
+- Initial commit
diff --git a/frontend/slices/appshell/index.ts b/frontend/slices/appshell/index.ts
index dd9066bf..2e3557e8 100644
--- a/frontend/slices/appshell/index.ts
+++ b/frontend/slices/appshell/index.ts
@@ -206,4 +206,5 @@ export type {
// Bundled default feature set (appshell/features/*) — re-exported LAST so the
// core bindings the features read (defineFeature etc.) are already live. A
// consumer drops `features: DEFAULT_FEATURES` into its manifest in one line.
+export { mdToHtml } from "./features/widgets/components/md";
export * from "./defaults";
diff --git a/frontend/slices/os-settings/components/about-section.tsx b/frontend/slices/os-settings/components/about-section.tsx
index 816d856a..10da668e 100644
--- a/frontend/slices/os-settings/components/about-section.tsx
+++ b/frontend/slices/os-settings/components/about-section.tsx
@@ -9,6 +9,7 @@ import { useAppearance, effectiveServerTarget } from "@/lib/appearance";
import { IS_DEMO } from "@/lib/demo";
import { SettingsSection, SettingsValueRow, SettingsActionRow } from "@/features/shell-settings";
import { MsoMark } from "@/components/shared/mso-mark";
+import { WhatsNew } from "./whats-new";
import pkg from "../../../../package.json";
import { openOnboarding } from "@/features/auth";
@@ -89,6 +90,8 @@ export function AboutSection() {
))}
</SettingsSection>
+ <WhatsNew />
+
<SettingsSection icon={<RotateCcw />} title="Reset">
<SettingsActionRow
label="Open onboarding"
diff --git a/frontend/slices/os-settings/components/whats-new.tsx b/frontend/slices/os-settings/components/whats-new.tsx
new file mode 100644
index 00000000..ec8e0db9
--- /dev/null
+++ b/frontend/slices/os-settings/components/whats-new.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Sparkles } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { SettingsSection } from "@/features/shell-settings";
+import { mdToHtml } from "@/features/os-shell";
+import { IS_DEMO } from "@/lib/demo";
+
+// "What's new", from docs/CHANGELOG.md — which is generated from git subjects, so
+// it cannot drift from what actually shipped.
+//
+// This exists because a change that only lands in a terminal is a change the owner
+// has to go looking for. The deploy already ships the file; this puts it where they
+// already are.
+
+const COLLAPSED_DAYS = 2;
+
+/** Split on the `## YYYY-MM-DD` day headings the generator emits. */
+function days(md: string): { date: string; body: string }[] {
+ return md
+ .split(/^## (?=\d{4}-\d{2}-\d{2})/m)
+ .slice(1)
+ .map((chunk) => {
+ const nl = chunk.indexOf("\n");
+ return { date: chunk.slice(0, nl).trim(), body: chunk.slice(nl + 1).trim() };
+ });
+}
+
+export function WhatsNew() {
+ const [md, setMd] = useState<string | null>(null);
+ const [all, setAll] = useState(false);
+
+ useEffect(() => {
+ if (IS_DEMO) return;
+ let alive = true;
+ fetch("/api/changelog", { cache: "no-store" })
+ .then((r) => (r.ok ? r.json() : null))
+ .then((d: { markdown?: string } | null) => alive && setMd(d?.markdown ?? ""))
+ .catch(() => alive && setMd(""));
+ return () => {
+ alive = false;
+ };
+ }, []);
+
+ // Nothing to show is not a failure state — a fresh checkout has no generated
+ // changelog, and an empty card would just be noise in Settings.
+ if (!md) return null;
+ const entries = days(md);
+ if (!entries.length) return null;
+ const shown = all ? entries : entries.slice(0, COLLAPSED_DAYS);
+
+ return (
+ <SettingsSection
+ icon={<Sparkles />}
+ title="What's new"
+ footnote="Generated from the commit history of this deployment — it cannot drift from what shipped."
+ >
+ <div className="space-y-3">
+ {shown.map((d) => (
+ <div key={d.date}>
+ <div className="pb-1 text-xs font-semibold text-muted-foreground">{d.date}</div>
+ <div
+ className="space-y-0.5 text-xs leading-relaxed [&_code]:rounded [&_code]:bg-secondary [&_code]:px-1 [&_code]:font-mono [&_strong]:font-semibold [&_strong]:text-foreground"
+ dangerouslySetInnerHTML={{ __html: mdToHtml(d.body) }}
+ />
+ </div>
+ ))}
+ {entries.length > COLLAPSED_DAYS && (
+ <Button
+ type="button"
+ variant="secondary"
+ size="sm"
+ className="w-full [@media(pointer:coarse)]:min-h-[44px]"
+ onClick={() => setAll((v) => !v)}
+ >
+ {all ? "Show less" : `Show all ${entries.length} days`}
+ </Button>
+ )}
+ </div>
+ </SettingsSection>
+ );
+}
diff --git a/package.json b/package.json
index e6823c90..af6988ec 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,8 @@
"audit": "node scripts/audit.mjs",
"verify": "bun run typecheck && bun run lint && bun run coverage && bun run check && bun run audit",
"e2e": "node scripts/e2e/shell.mjs",
+ "changelog": "node scripts/gen-changelog.mjs",
+ "ship": "bash scripts/ship.sh",
"smoke": "E2E_BASE_URL=http://localhost:4005 vitest run scripts/e2e/smoke.test.ts"
},
"dependencies": {
diff --git a/scripts/gates.sh b/scripts/gates.sh
index 3253bb27..4d3d98aa 100755
--- a/scripts/gates.sh
+++ b/scripts/gates.sh
@@ -49,6 +49,10 @@ fi
# NOTE: check-slices.mjs used to run here. It and all 20 slice.json were deleted on
# 2026-08-03 (commit 844eef3) — do NOT let a hook reinstall re-add that line.
node scripts/check-cycles.mjs || fail "check-cycles: new import cycle introduced."
+# docs/CHANGELOG.md is derived from git, so it can only be stale, never wrong —
+# and a stale one is what Settings → About would show. `bun run ship` regenerates
+# it before committing; this catches a plain `git push`.
+node scripts/gen-changelog.mjs --check || fail "changelog stale — run: node scripts/gen-changelog.mjs (or use \`bun run ship\`)."
node scripts/check-contrast.mjs || true
# ── Guard 1c — dependency audit, high/critical only.
diff --git a/scripts/gen-changelog.mjs b/scripts/gen-changelog.mjs
new file mode 100644
index 00000000..43e161e8
--- /dev/null
+++ b/scripts/gen-changelog.mjs
@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// docs/CHANGELOG.md, DERIVED from git. Never hand-edited.
+//
+// CLAUDE.md's rule is "do not start a second log" — docs/CHANGELOG.md once existed
+// as a hand-maintained twin of PROGRESS.md and was merged back in for exactly that
+// reason. This does not reopen that: nothing is written here by hand, so there is
+// no second thing to keep in sync and no way for it to disagree with history.
+// PROGRESS.md stays the SSOT for WHY; this is a reverse-chronological WHAT, and it
+// is what Settings → About renders as "What's new" so a change is visible in the
+// running app instead of only in a terminal.
+//
+// node scripts/gen-changelog.mjs # write docs/CHANGELOG.md
+// node scripts/gen-changelog.mjs --check # exit 1 if stale (used by the gates)
+//
+// Conventional-commit subjects are grouped by type; anything else lands under
+// "Other" rather than being dropped, because a silently-omitted commit is how a
+// changelog stops being trustworthy.
+//
+// NO COMMIT HASHES, deliberately. `ship` regenerates this AFTER committing and folds
+// it in with --amend — which rewrites the SHA. If the file named hashes it would
+// reference the pre-amend one, and the --check below would then disagree with itself
+// on the very next run. Content that depends only on (date, type, scope, subject) is
+// stable across the amend, so the check is meaningful.
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const OUT = path.join(ROOT, "docs", "CHANGELOG.md");
+const MAX_DAYS = 60; // keep it readable; git has the rest
+
+const TYPES = [
+ ["feat", "Added"],
+ ["fix", "Fixed"],
+ ["perf", "Faster"],
+ ["refactor", "Changed"],
+ ["test", "Tests"],
+ ["docs", "Docs"],
+ ["chore", "Chores"],
+ ["build", "Build"],
+ ["ci", "CI"],
+];
+const LABEL = new Map(TYPES);
+
+// `%x00` separators: a commit subject may contain anything, including the
+// characters a naive split would choke on.
+const RAW = execSync(
+ `git -C "${ROOT}" log --no-merges --date=short --pretty=format:"%h%x00%ad%x00%s"`,
+ { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+);
+
+/** @type {Map<string, {hash:string,type:string,scope:string,subject:string}[]>} */
+const byDay = new Map();
+for (const line of RAW.split("\n").filter(Boolean)) {
+ const [hash, date, subject] = line.split("\0");
+ const m = /^(\w+)(?:\(([^)]*)\))?!?:\s*(.+)$/.exec(subject ?? "");
+ const type = m && LABEL.has(m[1]) ? m[1] : "other";
+ if (!byDay.has(date)) byDay.set(date, []);
+ byDay.get(date).push({ hash, type, scope: m?.[2] ?? "", subject: m?.[3] ?? subject ?? "" });
+}
+
+const days = [...byDay.keys()].sort().reverse().slice(0, MAX_DAYS);
+const out = [
+ "# Changelog",
+ "",
+ "**Generated — do not edit.** `node scripts/gen-changelog.mjs`, run by `bun run ship`.",
+ "Newest first. `docs/PROGRESS.md` is the source of truth for *why* a change was made;",
+ "this is the *what*, and it is what Settings → About shows as “What's new”.",
+ "",
+];
+
+for (const day of days) {
+ out.push(`## ${day}`, "");
+ const commits = byDay.get(day);
+ for (const [type, label] of [...TYPES, ["other", "Other"]]) {
+ const rows = commits.filter((c) => c.type === type);
+ if (!rows.length) continue;
+ out.push(`**${label}**`, "");
+ for (const c of rows) {
+ out.push(`- ${c.scope ? `\`${c.scope}\` ` : ""}${c.subject}`);
+ }
+ out.push("");
+ }
+}
+
+const text = out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+
+if (process.argv.includes("--check")) {
+ const current = safeRead(OUT);
+ if (current !== text) {
+ console.error("docs/CHANGELOG.md is stale — run: node scripts/gen-changelog.mjs");
+ process.exit(1);
+ }
+ console.log("changelog: current.");
+} else {
+ writeFileSync(OUT, text);
+ console.log(`wrote ${path.relative(ROOT, OUT)} (${days.length} days)`);
+}
+
+function safeRead(p) {
+ try {
+ return readFileSync(p, "utf8");
+ } catch {
+ return "";
+ }
+}
diff --git a/scripts/ship.sh b/scripts/ship.sh
new file mode 100755
index 00000000..aac65d4e
--- /dev/null
+++ b/scripts/ship.sh
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# The whole ship, in the order that cannot be got wrong.
+#
+# bun run ship
+#
+# Exists because "push to main" is NOT a deploy here. Prod is systemd with no
+# webhook, so a pushed commit changes nothing the owner can see until someone
+# rebuilds — and the rebuild has a hazard of its own (`next build` wipes .next in
+# the LIVE working directory, so the site 404s every chunk until the restart lands).
+# Doing it by hand meant remembering four steps in one order; forgetting the last
+# one left main ahead of the running site with no signal that they had diverged.
+#
+# Order is load-bearing, and the changelog step is subtler than it looks:
+# 1. commit — the message must be IN history before the changelog can list it.
+# 2. changelog — regenerate, then fold into that same commit with --amend. The
+# amend rewrites the SHA, which is exactly why gen-changelog.mjs
+# emits no hashes: the content has to survive it, or the staleness
+# gate would disagree with itself on the next push.
+# 3. push — the pre-push hook runs the gates (scripts/gates.sh), including
+# the changelog staleness check that this ordering satisfies.
+# 4. build — in place, because the next line restarts immediately.
+# 5. restart — build THEN restart, always. Never the reverse.
+set -euo pipefail
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+MSG="${1:-}"
+[ -n "$MSG" ] || { echo "usage: bun run ship \"<conventional commit message>\"" >&2; exit 1; }
+
+echo "▶ 1/5 commit"
+git add -A
+if git diff --cached --quiet; then
+ echo " nothing staged — skipping commit"
+ COMMITTED=0
+else
+ git commit -q -m "$MSG"
+ COMMITTED=1
+fi
+
+echo "▶ 2/5 changelog"
+node scripts/gen-changelog.mjs
+if ! git diff --quiet -- docs/CHANGELOG.md; then
+ git add docs/CHANGELOG.md
+ if [ "$COMMITTED" = "1" ]; then
+ git commit -q --amend --no-edit # fold it into the commit it describes
+ else
+ git commit -q -m "docs(changelog): regenerate"
+ fi
+fi
+
+echo "▶ 3/5 push (gates run here, ~70s)"
+git push origin main
+
+echo "▶ 4/5 build"
+bun run build >/dev/null
+
+echo "▶ 5/5 restart"
+sudo -n systemctl restart mso.service
+sleep 4
+
+# The chunk-mismatch check from CLAUDE.md, run every time rather than remembered:
+# if the HTML references a chunk the restarted process does not serve, every asset
+# 404s and the UI is unstyled. Cheaper to check than to notice.
+CSS=$(curl -fsS http://127.0.0.1:4005/ | grep -o '/_next/static/[^"]*\.css' | head -1 || true)
+if [ -z "$CSS" ]; then
+ echo "❌ no CSS reference in the served HTML — the app is not rendering." >&2; exit 1
+fi
+TYPE=$(curl -fsSI "http://127.0.0.1:4005$CSS" | tr -d '\r' | awk -F': ' 'tolower($1)=="content-type"{print $2}')
+case "$TYPE" in
+ text/css*) ;;
+ *) echo "❌ chunk mismatch: $CSS served as '${TYPE:-nothing}'. Fix: rm -rf .next && bun run build && restart" >&2; exit 1 ;;
+esac
+
+echo
+echo "✅ shipped $(git rev-parse --short HEAD) → https://mso.rahmanef.com"
+echo " What's new is in Settings → About (docs/CHANGELOG.md, regenerated above)."