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
feat(ship): one command that changelogs, pushes, rebuilds and verifies
Rahman2d5e0fc3ea11
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 ishistory, 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 targetsibling repos that do not exist on this machine), `browser-agent-plan.md` (the retiredPlaywright sidecar), `SIXFIX-PLAN.md` (a finished dated fix list). Nothing linked to anydiff --git a/app/api/changelog/route.ts b/app/api/changelog/route.tsnew file mode 100644index 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.mdnew file mode 100644index 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 commitdiff --git a/frontend/slices/appshell/index.ts b/frontend/slices/appshell/index.tsindex 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.tsxindex 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"><SettingsActionRowlabel="Open onboarding"diff --git a/frontend/slices/os-settings/components/whats-new.tsx b/frontend/slices/os-settings/components/whats-new.tsxnew file mode 100644index 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.jsonindex 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.shindex 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.mjsnew file mode 100644index 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.shnew file mode 100755index 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)."