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(cli): add `mso` CLI + agent skills so the web UI is one frontend, not the product
Rahman4e4b0a48d121
diff --git a/CLAUDE.md b/CLAUDE.mdindex 1d364182..f5888f59 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -204,6 +204,23 @@ to `resources/` (rr) and drive any project from one manifest:- Solo-dev: push direct to `main` once `pnpm typecheck` + `pnpm build` are green.Conventional commits + Claude co-author.+## CLI (`bin/mso`) — the web UI is only one frontend+`bin/mso` reaches the same `/api` surface from a shell; `scripts/install.sh` symlinks+it to `~/.local/bin/mso` and symlinks `claude-skills/*` into `~/.claude/skills/`+(`/mso`, `/mso-camoufox`, `/mso-apps`, `/mso-list`, `/mso-image-editor`,+`/mso-browser-list`). `mso -h` lists every verb; `mso api <METHOD> <path> [json]` is+the escape hatch for anything without a named verb.+- **Every CLI caller must send `Origin: <base>`.** `proxy.ts` blocks mutating `/api`+ that cannot prove same-origin; a browser proves it with `Sec-Fetch-Site`, and the+ documented fallback is an `Origin` whose host matches `Host`. Without it login+ itself 403s `cross_origin_blocked` — before any device check, so the error looks+ like an approval problem and is not.+- One shared CLI device id lives in `~/.mso/cli.device.id` (auto-created, approve+ once with `mso approve $(cat ~/.mso/cli.device.id)`). `audit.js` and+ `image-editor.sh` read the same file — do not reintroduce per-script hardcoded ids.+- Local verbs (`-h`, `approve`, `devices`, `service`, `build`) never log in, so they+ still work while the service is down.+## Local dev```bashpnpm installdiff --git a/README.md b/README.mdindex f1c256cd..1b601dc4 100644--- a/README.md+++ b/README.md@@ -110,6 +110,29 @@ curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/installFull production setup, TLS/VPN notes, filesystem roots, updates, and rollback steps live in [docs/INSTALL.md](./docs/INSTALL.md).+## CLI++The browser UI is one frontend, not the product. The installer also puts `mso` on your+`PATH`, and it drives the same API:++```bash+mso -h # every verb+mso devices # who can log in+mso approve <deviceId> "my phone"+mso ls ~/projects # files+mso exec "df -h" # host shell+mso stats # cpu / mem / disk+mso camoufox start # power the anti-detection browser+mso mapp list # managed apps (hermes, openclaw…)+mso service restart # systemd+mso api GET /api/v1/sys/stats # escape hatch — any endpoint+```++Local verbs (`-h`, `approve`, `devices`, `service`) work even while the service is+down. If you use [Claude Code](https://claude.com/claude-code), the installer also+links the agent skills in `claude-skills/` into `~/.claude/skills/` — `/mso`,+`/mso-camoufox`, `/mso-apps`, `/mso-list`, `/mso-image-editor`, `/mso-browser-list`.+## Security warningAn authenticated MSO session can read allowed files and run commands as the user that owns the process. Treat it like SSH in a browser.diff --git a/bin/mso b/bin/msonew file mode 100755index 00000000..d8d7de8d--- /dev/null+++ b/bin/mso@@ -0,0 +1,213 @@+#!/usr/bin/env bash+# mso — drive the whole Manef Shell OS from the shell.+#+# mso.rahmanef.com is only ONE frontend. Everything it can do is a call to the+# same /api/v1 surface, so this CLI reaches every feature without a browser.+# Auth = signed session cookie (password + approved device), cached in a jar.+#+# FILES ls [path] · cat <p> · write <p> <text> · mkdir <p> · rm <p>+# mv <a> <b> · cp <a> <b> · usage [path] · search <q> [root]+# HOST exec <cmd…> · stats · ps · cleanup [--run] · health+# BROWSER camoufox status|start|stop|session+# APPS apps · mapp list|show <id>|logs <id>|install <id>|update <id>+# mapp backups <id>|jobs <id>+# TERMINAL term open [cwd] · term input <id> <text> · term close <id>+# AI ai <prompt…> · threads [id] · memory+# CONFIG config · prefs · models · skills+# DEVICES devices · approve <id> [label] · revoke <id> (local, no login)+# whoami · login (this CLI's own device id + session)+# SERVICE service status|start|stop|restart|logs [n] · build · deploy+# EDITOR crud list|get|set|del|cmds (see `mso crud`)+# ESCAPE api <METHOD> <path> [json] — any endpoint, e.g.+# mso api GET /api/v1/sys/stats+#+# READ = OS_FS_READ_ROOTS; WRITE = home + ~/projects; exec = full host power.+set -euo pipefail++ROOT="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)"+B="${MSO_BASE:-${OS_BASE:-http://127.0.0.1:4005}}"+ENVF="${MSO_ENV:-${OS_ENV:-$ROOT/.env.local}}"+# shellcheck disable=SC1090+set -a; . "$ENVF" 2>/dev/null || true; set +a++die() { echo "mso: $*" >&2; exit 1; }+need() { command -v "$1" >/dev/null || die "missing dependency: $1"; }+need curl; need jq++# ── local ops (no HTTP, no login) ───────────────────────────────────────────+dev_script() { node "$ROOT/scripts/approve-device.js" "$@"; }++# ── auth ────────────────────────────────────────────────────────────────────+PASS="${MSO_PASSWORD:-${OS_PASSWORD:-${OS_LOGIN_PASSWORD:-}}}"+DEV="${MSO_DEVICE:-${OS_DEVICE:-}}"+# A stable per-host CLI device id, so `mso approve` only ever has to run once.+DEVF="${MSO_DEVICE_FILE:-$HOME/.mso/cli.device.id}"+cli_device() {+ [ -n "$DEV" ] && { printf '%s' "$DEV"; return; }+ [ -s "$DEVF" ] || { mkdir -p "$(dirname "$DEVF")"; head -c16 /dev/urandom | od -An -tx1 | tr -d ' \n' > "$DEVF"; chmod 600 "$DEVF"; }+ cat "$DEVF"+}++JAR="${MSO_JAR:-${TMPDIR:-/tmp}/mso-$(id -u).jar}"++# proxy.ts blocks mutating /api requests that can't prove same-origin. A browser+# proves it with Sec-Fetch-Site; the documented fallback for non-browser clients+# is an Origin whose host matches the Host header — which is exactly what $B is.+# Sent on every call so `login` works before any session cookie exists.+ORIGIN=(-H "origin: $B")++login() {+ local d code; d=$(cli_device)+ [ -n "$PASS" ] || die "no OS_LOGIN_PASSWORD in $ENVF (or export MSO_PASSWORD)"+ code=$(curl -sS -o /dev/null -w '%{http_code}' -c "$JAR" -X POST "$B/api/auth/login" \+ "${ORIGIN[@]}" -H 'content-type: application/json' \+ -d "$(jq -n --arg p "$PASS" --arg d "$d" '{password:$p,deviceId:$d,deviceLabel:"mso cli"}')" || true)+ [ "$code" = "200" ] || die "login failed ($code) — approve this CLI device:+ mso approve $d \"mso cli\""+}+# Request with the cached cookie; on 401/403 (expired) log in once and retry.+# Login is lazy on purpose: `mso -h`, `mso approve` and `mso service …` are+# local-only and must keep working while the service is down or unapproved.+req() {+ local out code body+ [ -f "$JAR" ] || login+ out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)+ code="${out##*$'\n'}"; body="${out%$'\n'*}"+ if [ "$code" = "401" ] || [ "$code" = "403" ]; then+ login+ out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)+ code="${out##*$'\n'}"; body="${out%$'\n'*}"+ fi+ case "$code" in 2*) printf '%s' "$body" ;; *) die "request failed ($code): $body" ;; esac+}+enc() { jq -rn --arg v "$1" '$v|@uri'; }+jget() { req "$B$1"; }+jpost() { req -H 'content-type: application/json' -d "${2:-{\}}" "$B$1"; }+jdel() { req -X DELETE -H 'content-type: application/json' -d "${2:-{\}}" "$B$1"; }+# Build a JSON object from k=v pairs (numbers + booleans coerced).+kv_args() { local j='{}' kv k v; for kv in "$@"; do k="${kv%%=*}"; v="${kv#*=}"+ if [[ "$v" =~ ^-?[0-9]+([.][0-9]+)?$ || "$v" == "true" || "$v" == "false" ]]; then+ j=$(jq -c --arg k "$k" --argjson v "$v" '.+{($k):$v}' <<<"$j")+ else j=$(jq -c --arg k "$k" --arg v "$v" '.+{($k):$v}' <<<"$j"); fi; done; printf '%s' "$j"; }++# Print the header block verbatim — stops at the first non-comment line, so the+# help can never drift out of sync with the comment above.+usage() { awk 'NR>1 { if ($0 !~ /^#/) exit; sub(/^# ?/, ""); print }' "$0"; }++cmd="${1:-help}"; shift || true+case "$cmd" in+ # ── files ────────────────────────────────────────────────────────────────+ ls) jget "/api/v1/fs/list?path=$(enc "${1:-~}")" ;;+ cat) jget "/api/v1/fs/read?path=$(enc "${1:?path}")" | jq -r . ;;+ usage) jget "/api/v1/fs/usage?path=$(enc "${1:-~}")" ;;+ search) jget "/api/v1/fs/search?q=$(enc "${1:?query}")${2:+&root=$(enc "$2")}" ;;+ write) jpost "/api/v1/fs/write" "$(jq -n --arg p "${1:?path}" --arg c "${2-}" '{path:$p,content:$c}')" ;;+ mkdir) jpost "/api/v1/fs/mkdir" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;+ rm) jdel "/api/v1/fs/delete" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;+ mv) jpost "/api/v1/fs/move" "$(jq -n --arg f "${1:?from}" --arg t "${2:?to}" '{from:$f,to:$t}')" ;;+ cp) jpost "/api/v1/fs/copy" "$(jq -n --arg f "${1:?from}" --arg t "${2:?to}" '{from:$f,to:$t}')" ;;++ # ── host ─────────────────────────────────────────────────────────────────+ exec) jpost "/api/v1/exec/run" "$(jq -n --arg c "$*" '{cmd:$c}')" ;;+ stats) jget "/api/v1/sys/stats" ;;+ ps) jget "/api/v1/sys/processes" ;;+ cleanup) if [ "${1-}" = "--run" ]; then jpost "/api/v1/sys/cleanup"; else jget "/api/v1/sys/cleanup"; fi ;;+ health) jget "/api/auth/me" ;;++ # ── camoufox (the real browser the Browser app drives) ────────────────────+ camoufox)+ case "${1:-status}" in+ status) jget "/api/v1/camoufox/service" ;;+ start) jpost "/api/v1/camoufox/service" '{"action":"start"}' ;;+ stop) jpost "/api/v1/camoufox/service" '{"action":"stop"}' ;;+ session) jget "/api/v1/camoufox/session" ;;+ *) die "camoufox: status|start|stop|session" ;;+ esac ;;++ # ── managed apps (hermes, openclaw…) ─────────────────────────────────────+ apps) jget "/api/v1/apps" ;;+ mapp)+ sub="${1:-list}"; shift || true+ case "$sub" in+ list) jget "/api/v1/managed-apps" ;;+ show) jget "/api/v1/managed-apps/$(enc "${1:?id}")" ;;+ logs) jget "/api/v1/managed-apps/$(enc "${1:?id}")/logs" ;;+ backups) jget "/api/v1/managed-apps/$(enc "${1:?id}")/backups" ;;+ jobs) jget "/api/v1/managed-apps/$(enc "${1:?id}")/jobs" ;;+ install) jpost "/api/v1/managed-apps/$(enc "${1:?id}")/install" "$(kv_args "${@:2}")" ;;+ update) jpost "/api/v1/managed-apps/$(enc "${1:?id}")/update" "$(kv_args "${@:2}")" ;;+ *) die "mapp: list|show <id>|logs <id>|backups <id>|jobs <id>|install <id>|update <id>" ;;+ esac ;;++ # ── terminal ─────────────────────────────────────────────────────────────+ term)+ sub="${1:-open}"; shift || true+ case "$sub" in+ open) jpost "/api/v1/term/open" "$(jq -n --arg c "${1-}" '{cwd:$c}')" ;;+ input) jpost "/api/v1/term/input" "$(jq -n --arg i "${1:?id}" --arg d "${2:?text}" '{id:$i,data:$d}')" ;;+ close) jpost "/api/v1/term/close" "$(jq -n --arg i "${1:?id}" '{id:$i}')" ;;+ *) die "term: open [cwd]|input <id> <text>|close <id>" ;;+ esac ;;++ # ── assistant / state ────────────────────────────────────────────────────+ ai) jpost "/api/assistant" "$(jq -n --arg m "$*" '{messages:[{role:"user",content:$m}]}')" ;;+ threads) if [ -n "${1-}" ]; then jget "/api/threads?id=$(enc "$1")"; else jget "/api/threads"; fi ;;+ memory) jget "/api/memory" ;;+ config) jget "/api/config" ;;+ prefs) jget "/api/prefs" ;;+ models) jget "/api/models" ;;+ skills) jget "/api/skills" ;;++ # ── devices (local file, works even when the service is down) ────────────+ devices) dev_script --list ;;+ approve) dev_script "${1:?deviceId}" "${@:2}" ;;+ revoke) dev_script --revoke "${1:?deviceId}" ;;+ whoami) echo "cli device: $(cli_device)"; jget "/api/auth/me" ;;+ login) rm -f "$JAR"; login; echo "logged in as device $(cli_device)" ;;++ # ── service (local systemd) ──────────────────────────────────────────────+ service)+ case "${1:-status}" in+ status) systemctl status --no-pager mso.service ;;+ start) sudo systemctl start mso.service ;;+ stop) sudo systemctl stop mso.service ;;+ restart) sudo systemctl restart mso.service ;;+ logs) journalctl -u mso.service -n "${2:-50}" --no-pager ;;+ *) die "service: status|start|stop|restart|logs [n]" ;;+ esac ;;+ build) (cd "$ROOT" && npm run build) ;;+ deploy) (cd "$ROOT" && npm run build) && sudo systemctl restart mso.service && echo "deployed → $B" ;;++ # ── editor-document CRUD (one pattern, all editor features) ──────────────+ crud)+ sub="${1:-help}"; shift || true+ case "$sub" in+ list) jget "/api/v1/fs/list?path=$(enc "${1:?path}")" ;;+ get) jget "/api/v1/fs/read?path=$(enc "${1:?path}")" | jq -r . ;;+ del) jdel "/api/v1/fs/delete" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;+ cmds) jget "/api/v1/editor/exec" | jq -r '.tools[] | " \(.name)\t\(.description)"' ;;+ set)+ path="${1:?path}"; shift; op="${1:?command-or-content}"; shift || true+ if [[ "$op" =~ ^[a-z]+\.[a-zA-Z]+$ ]]; then+ # Editor-doc command → ONE atomic server op: the route reads the doc+ # (or seeds it), applies the command, and writes it back in place.+ a=$(kv_args "$@")+ resp=$(jpost "/api/v1/editor/exec" "$(jq -n --arg p "$path" --arg n "$op" --argjson a "$a" '{path:$p,commands:[{name:$n,args:$a}]}')")+ jq -e '.dimsFallback' >/dev/null 2>&1 <<<"$resp" && echo " ! image dims unknown → defaulted (AVIF/HEIC/TIFF not probed)" >&2+ jq -r '.results[]? | " \(.name) \(if .ok then "ok" else "ERR" end) — \(.result)"' <<<"$resp"+ else+ jpost "/api/v1/fs/write" "$(jq -n --arg p "$path" --arg c "$op${*:+ $*}" '{path:$p,content:$c}')"+ fi ;;+ *) die "crud: list <dir> | get <path> | set <path> <cmd k=v…|text> | del <path> | cmds" ;;+ esac ;;++ # ── escape hatch: any endpoint at all ────────────────────────────────────+ api)+ m="${1:?METHOD}"; p="${2:?/api/...}"; body="${3-}"+ if [ -n "$body" ]; then req -X "$m" -H 'content-type: application/json' -d "$body" "$B$p"+ else req -X "$m" "$B$p"; fi ;;++ help|-h|--help) usage; exit 0 ;;+ *) usage; exit 1 ;;+esac+echodiff --git a/bin/mso.test.ts b/bin/mso.test.tsnew file mode 100644index 00000000..4b9845af--- /dev/null+++ b/bin/mso.test.ts@@ -0,0 +1,36 @@+import { execFileSync } from "node:child_process";+import path from "node:path";+import { describe, expect, it } from "vitest";++// The CLI's dispatch table and its help are the same comment block, so a verb+// that exists in one and not the other is a real bug. These run WITHOUT a server:+// help and unknown-command are the two paths that must never need auth, because+// they are what you reach for when the service is down.+const CLI = path.join(__dirname, "mso");+const run = (...args: string[]) =>+ execFileSync(CLI, args, { encoding: "utf8", env: { ...process.env, MSO_ENV: "/dev/null" } });++describe("bin/mso", () => {+ it("prints help without logging in", () => {+ const out = run("-h");+ expect(out).toContain("drive the whole Manef Shell OS");+ for (const verb of ["camoufox", "approve", "service", "api", "exec"]) {+ expect(out).toContain(verb);+ }+ });++ it("documents every verb the dispatch table implements", () => {+ const src = require("node:fs").readFileSync(CLI, "utf8") as string;+ const body = src.slice(src.indexOf('cmd="${1:-help}"'));+ // Case arms look like ` ls)` / ` camoufox)` / ` help|-h|--help)`.+ const verbs = [...body.matchAll(/^ {2}([a-z][a-z-]*)\)/gm)].map((m) => m[1]);+ expect(verbs.length).toBeGreaterThan(20);+ const help = run("-h");+ const undocumented = verbs.filter((v) => v !== "help" && !help.includes(v));+ expect(undocumented).toEqual([]);+ });++ it("exits non-zero on an unknown command", () => {+ expect(() => run("definitely-not-a-verb")).toThrow();+ });+});diff --git a/claude-skills/mso-apps/SKILL.md b/claude-skills/mso-apps/SKILL.mdnew file mode 100644index 00000000..32c4a5f5--- /dev/null+++ b/claude-skills/mso-apps/SKILL.md@@ -0,0 +1,59 @@+---+name: mso-apps+description: Drive ANY mso app from the CLI — one app→function→command matrix for Files, Code Editor, Terminal, System Monitor, Browser, Media Viewer, Media Studio, Reel Editor, Settings, Assistant, App Store. Trigger on /mso-apps, "drive an os app", "os files / terminal / code editor / system monitor / settings from cli", "what os app does X", "operate mso feature".+---++# /mso-apps — every mso app from the CLI++One reference for operating each app. Everything routes through three transports+([/mso] owns them): `mso` (host fs/exec/sys + generic `crud`), `browser.sh`+(real Chromium), `image-editor.sh` (editor-document CRUD). Deep dives:+[/mso] (control + crud), [/mso-image-editor] (editor docs), [/mso-list] (LIVE audit+of every function), [/mso-browser-list] (browser internals).++```bash+OS=mso+BR=/home/rahman/.claude/skills/mso/browser.sh+IE=/home/rahman/.claude/skills/mso-image-editor/image-editor.sh+```++## App → function → CLI++| App | Functions | Drive it with |+|---|---|---|+| **Files** | list/open/new/rename/move/copy/delete, usage | `$OS ls\|cat\|write\|mkdir\|mv\|cp\|rm\|usage` · `$OS crud {list,get,set,del}` |+| **Code Editor** | tree, open, edit, save, new file | `$OS cat <f>` / `$OS write <f> <content>` (or edit directly — this box IS the VPS) |+| **Terminal** | fs builtins + host shell passthrough | `$OS exec "<cmd>"` · `$OS ps` |+| **System Monitor** | CPU/mem/disk gauges, process table | `$OS stats` · `$OS ps` (read-only) |+| **Browser** | navigate, back/fwd/reload, click/type/scroll, read | `$BR go\|back\|reload\|click\|type\|key\|scroll\|content\|shot` |+| **Media Viewer** | view image/video/audio, download | `$OS cat`/copy → **Read** the image here; `$OS exec "ffprobe <f>"` for AV |+| **Media Studio** | layers/text/shapes/adjust/style canvas | `$IE …` (it's the image editor) — see [/mso-image-editor] |+| **Image Editor** | full editor-document CRUD + render | `$IE open\|new\|run\|inspect\|save\|view` · `$OS crud set <doc.json> <cmd>` |+| **Reel Editor** | timeline/clips/keyframes, render→.webm | asset prep `$OS exec "ffmpeg …"`; timeline + render = browser ([/os-browser]) |+| **Settings** | devices, AI key (BYOK), server mock/live, theme | `node ~/projects/mso/scripts/approve-device.js <id>`; key → `~/.mso/config.json`; theme/server = UI |+| **Assistant (Alfa)** | streaming chat + editor tool-calling | `POST /api/assistant` (needs BYOK key); for editing prefer deterministic `$IE`/`crud` |+| **App Store / Create-App** | install/uninstall, runtime apps | built-ins = `shell.manifest.ts` (+redeploy); runtime cmd app == `$OS exec`; install = UI |++## Notes++- **Generic CRUD** is the spine: `mso crud {list|get|set|del}` works on any host+ resource; `set <x.doc.json> <editor-cmd>` edits an editor document atomically+ (one server op). Files/code/terminal/monitor are fully CLI-driven; Studio/Reel+ **render** in the real app (open in the browser) — there is no headless renderer.+- **What CRUD reaches (honest scope):** host files + editor docs + `~/.mso/*.json`+ (config/devices). It does NOT reach browser-local state — theme, server mock/live+ toggle, window layout, the installed-app registry all live in localStorage+ (per-browser); set those in the UI. System stats are read-only.+- **Raster ops are browser-only by design:** brush/paint pixels, layer masks, and+ background removal need the live editor (no headless canvas). The CLI works at+ the document level (layers/text/shape/adjust/style/transform); paint there, save,+ and it round-trips back to the file.+- **Stateless edits:** each `crud set` is independent — no persistent undo/redo or+ tool/brush state across calls; selection defaults to the last layer (target any+ other with `layerName=`/`layerId=`). Keep file backups for "undo".+- **"Working" = the live probe passes.** Run `node ~/.claude/skills/mso-list/audit.js`+ for the authoritative per-function pass/fail (this matrix is the map; the audit+ is the truth). AI features (Alfa, Inspector) need a BYOK Anthropic key.+- Direct action is often best: this box IS the VPS, so Bash + the native file+ tools beat round-tripping through `mso` for heavy/local work. Use `mso` to+ reproduce exactly what an app does or to honour its bounded fs semantics.diff --git a/claude-skills/mso-browser-list/SKILL.md b/claude-skills/mso-browser-list/SKILL.mdnew file mode 100644index 00000000..5bfe8ecd--- /dev/null+++ b/claude-skills/mso-browser-list/SKILL.md@@ -0,0 +1,67 @@+---+name: mso-browser-list+description: Status of the mso Browser — a REAL headless Chromium (Playwright) on the VPS. List its functions, check the service renders real sites, and how to drive it from CLI. Trigger on /mso-browser-list, "browser functions", "why doesn't the browser work", "check the os browser", "browser status", "test the browser", "screenshot the browser".+---++# /mso-browser-list — Browser app deep check++The Browser is a **real headless Chromium** (Playwright) running on the host as+systemd `os-browser` (loopback :4002, persistent context = cookies/cache/session+on disk). The mso app shows live screenshots + sends clicks/keys; the CLI drives+the SAME session. Renders ANY site — no X-Frame-Options/CSP problem. Companion to+[/mso] and [/mso-list].++## 1. Live check (run first)++```bash+node ~/.claude/skills/mso-browser-list/browser-check.js+```+Navigates several sites via the service and reports title + screenshot bytes ++text length. If the service is DOWN: `sudo systemctl status os-browser`.++## 2. Drive it from CLI (you can SEE the page)++```bash+SH=/home/rahman/.claude/skills/mso/browser.sh+$SH go <url> ; $SH shot /tmp/b.png # then Read /tmp/b.png to view+$SH content ; $SH click X Y ; $SH type "…" ; $SH key Enter ; $SH scroll 600+```++## 3. Browser functions++| Function | How | Status |+|---|---|---|+| Navigate (omnibar) | POST `/api/v1/browser/navigate` → service `goto` | works (any site) |+| Render | live screenshot `<img>` from `/api/v1/browser/screenshot` | works |+| Click / type / key / scroll | mouse/keyboard mapped to 1280×800 viewport | works |+| Back / Forward / Reload | service history | works |+| Bookmarks / history | localStorage | works |+| Persistent session/cache | Playwright `launchPersistentContext(~/.mso/chrome-profile)` | works — logins stick |+| AI Inspector (browser) | url/title + actions + scoped chat | works (chat needs key) |+| CLI access (screenshot/content/drive) | `browser.sh` + the service API | works |++## 4. Architecture++```+mso Browser app ──Bearer──▶ /api/v1/browser/* ──secret──▶ 172.18.0.1:4002+CLI (browser.sh) ──secret──▶ 127.0.0.1:4002 (systemd os-browser)+ └ Playwright Chromium, 1 persistent context (shared session)+```+Env (Dokploy mso): `OS_BROWSER_URL=http://172.18.0.1:4002`, `OS_BROWSER_SECRET`.+Service secret: `/home/rahman/projects/os-browser/.env`. Code: `…/os-browser/server.mjs`.++## 5. Known limits++- **One shared page** (single context) — the web app + CLI share ONE browser tab.+ Multi-tab would need multiple pages/contexts (future).+- Screenshot view is interactive via click-mapping, not native scrolling — use the+ scroll action. Video/canvas update only on screenshot refresh.+- Heavy/slow pages: increase the refresh poll if a load is still settling.++## 6. If blank / not working++1. `node ~/.claude/skills/mso-browser-list/browser-check.js` — is the service up + rendering?+2. Service down → `sudo systemctl restart os-browser` (check chromium/deps).+3. Web app blank but service OK → `OS_BROWSER_URL`/`OS_BROWSER_SECRET` not set in the+ Dokploy env, or container can't reach `172.18.0.1:4002` (ufw on docker_gwbridge).+4. "Establishing session…" → not signed in / token expired.diff --git a/claude-skills/mso-browser-list/browser-check.js b/claude-skills/mso-browser-list/browser-check.jsnew file mode 100644index 00000000..523da44d--- /dev/null+++ b/claude-skills/mso-browser-list/browser-check.js@@ -0,0 +1,39 @@+// os-browser-list — checks the REAL browser service (Playwright Chromium, systemd+// os-browser). Navigates several sites and reports title + screenshot bytes ++// content length, proving any site renders (no X-Frame-Options problem). Runs on+// the host (loopback). Usage: node ~/.claude/skills/mso-browser-list/browser-check.js+const fs = require("fs");++const ENVF = process.env.OS_BROWSER_ENV || "/home/rahman/projects/os-browser/.env";+const BASE = process.env.OS_BROWSER_BASE || "http://127.0.0.1:4002";+let SECRET = process.env.OS_BROWSER_SECRET || "";+try {+ if (!SECRET) {+ const m = fs.readFileSync(ENVF, "utf8").match(/^OS_BROWSER_SECRET=(.+)$/m);+ if (m) SECRET = m[1].trim();+ }+} catch {}+const H = { "x-os-browser-secret": SECRET, "content-type": "application/json" };++const SITES = ["https://example.com", "https://news.ycombinator.com", "https://www.google.com", "https://github.com"];++(async () => {+ try {+ const h = await fetch(`${BASE}/health`).then((r) => r.json());+ console.log(`os-browser service: ${h.ok ? "UP" : "DOWN"} @ ${BASE}\n`);+ } catch (e) {+ console.log(`os-browser DOWN @ ${BASE}: ${e.message}\n(sudo systemctl status os-browser)`);+ process.exit(1);+ }+ for (const url of SITES) {+ try {+ const nav = await fetch(`${BASE}/navigate`, { method: "POST", headers: H, body: JSON.stringify({ url }) }).then((r) => r.json());+ const png = await fetch(`${BASE}/screenshot`, { headers: H }).then((r) => r.arrayBuffer());+ const c = await fetch(`${BASE}/content`, { headers: H }).then((r) => r.json());+ console.log(`OK "${(nav.title || "").slice(0, 30)}" shot=${png.byteLength}b text=${(c.text || "").length} ${url}`);+ } catch (e) {+ console.log(`ERR ${url} ${e.message}`);+ }+ }+ console.log("\nWeb path: /api/v1/browser/* (Convex-auth) → 172.18.0.1:4002. CLI: ~/.claude/skills/mso/browser.sh");+})();diff --git a/claude-skills/mso-camoufox/SKILL.md b/claude-skills/mso-camoufox/SKILL.mdnew file mode 100644index 00000000..0eebb936--- /dev/null+++ b/claude-skills/mso-camoufox/SKILL.md@@ -0,0 +1,113 @@+---+name: mso-camoufox+description: Drive the Camoufox anti-detection browser that MSO hosts — power the VNC session on/off, get the noVNC URL and one-time password, restore/snapshot the logged-in profile, and reach sites that block headless automation. Trigger on /mso-camoufox, "camoufox", "anti-detection browser", "real firefox on the vps", "the browser that beats cloudflare", "vnc browser", "novnc session".+---++# /mso-camoufox — the real-Firefox browser MSO hosts++Camoufox is a hardened Firefox build with anti-fingerprinting patches. MSO runs it+on a headless X display and exposes the live screen over noVNC, so it is a browser+you *watch and click*, not a headless scraper. Use it when a site blocks the plain+headless browser (Cloudflare, DataDome, LinkedIn, anything that fingerprints).++**Camoufox IS the Browser app.** It replaced both the Playwright sidecar+(`os-browser`, `:4002` — retired, kept only as dev tooling for `scripts/e2e`) and the+sandboxed-iframe browser that briefly followed it, because X-Frame-Options makes an+iframe unable to render most of the real web.++## Power it from the CLI++```bash+mso camoufox status # {installed, running, enabled}+mso camoufox start # systemctl --user start camoufox-vnc.service+mso camoufox stop+mso camoufox session # {password: "…"} — the one-time noVNC password+```++`start`/`stop` go through `/api/v1/camoufox/service`, which shells+`systemctl --user` — no sudo, no polkit rule. `installed:false` means the unit+file is missing, not that the browser is off.++## Watch / drive the screen++Once running, the live screen is proxied by MSO itself:++```+https://mso.rahmanef.com/camoufox-vnc/#password=<from `mso camoufox session`>+```++`proxy.ts` rewrites `/camoufox-vnc/*` to the local websockify on `127.0.0.1:6080`+(loopback-checked) behind the SAME verified-session check that guards+`/api/v1/exec`. Nothing about camoufox is exposed on a public port.++**The password goes in the URL fragment, never the query string** — a fragment is+not sent to the server and does not land in access logs or `Referer`.++Inside MSO the same thing is the **Browser** app's Camoufox tab.++## What the unit actually starts++`scripts/camoufox-vnc-service` (a *user* unit, `~/.config/systemd/user/camoufox-vnc.service`):++| piece | default | env override |+|---|---|---|+| X display | `:92` @ `1440x920x24` | `CAMOUFOX_DISPLAY_NUM`, `CAMOUFOX_GEOMETRY` |+| VNC / noVNC ports | `5902` / `6080` | `CAMOUFOX_VNC_PORT`, `CAMOUFOX_NOVNC_PORT` |+| profile | `~/.local/share/camoufox/profiles/linkedin` (chmod 700) | `CAMOUFOX_PROFILE` |+| browser binary | `~/.cache/camoufox/browsers/official/…/camoufox` | `CAMOUFOX_BROWSER` |+| start URL | none (restores last session) | `CAMOUFOX_START_URL` |+| VNC password file | `~/.vnc/passwd` | `CAMOUFOX_VNC_PASSWD` |++Also runs `matchbox-window-manager` so windows have no titlebar and fill the display.++## The profile is the valuable part — and the crown jewels++The profile holds a **live Google session** (`SID`, `__Secure-1PSID`, `SAPISID`) and+LinkedIn's `li_at`. Stealing those cookies is account takeover with no password and no+2FA prompt. So the unit re-`chmod 700`s the profile on every start (Firefox writes+`cookies.sqlite` 0644) and snapshots `cookies.sqlite*`, `key4.db`, `cert9.db` into+`~/.local/state/camoufox/session-backup/` — 3 generations, 0700.++Never `mso cat` or paste the profile contents anywhere.++To restore a broken session:++```bash+mso camoufox stop+mso exec 'cp -p ~/.local/state/camoufox/session-backup/1/* ~/.local/share/camoufox/profiles/linkedin/'+mso camoufox start+```++Use a separate profile per identity (`CAMOUFOX_PROFILE=…`) rather than logging one+profile in and out — the anti-detection value comes from a profile that looks aged.++## Gotchas++- **`enabled:false` is REQUIRED, not an accident.** The unit ships `disabled` with+ `Restart=no` + `RuntimeMaxSec=2h`. Power is plain `start`/`stop` — never+ `enable --now`, or every click re-arms boot autostart (that is how it once ran 26h+ with zero viewers). And a 2h lease under `Restart=always` is a 2-hourly reboot loop:+ ship `Restart=no` and the lease together or neither.+- **`CAMOUFOX_PROFILE` must point at `~/.local/share/…`, not `~/.cache/…`.** A wrong+ path makes `mkdir -p` create an empty profile with no error — you get a+ logged-out browser and no clue why.+- **The unit exists only on the host.** There is no copy or installer for it in the+ repo beyond `scripts/camoufox-vnc-service`; `loginctl enable-linger rahman` and the+ `user-bus.conf` drop-in have to be set up by hand.+- **Needs a user bus.** MSO reaches `systemctl --user` only because+ `mso.service.d/user-bus.conf` sets `XDG_RUNTIME_DIR=/run/user/1001` and rahman has+ `loginctl enable-linger`. If start fails with "Failed to connect to bus", that+ drop-in or the linger is gone — not a camoufox problem.+- **It is heavy.** Xvfb + Firefox + websockify. Check `mso stats` before starting it+ on a loaded box, and stop it when you are done.+- **Authorized use only.** Anti-detection browsing is for sites you have a right to+ access — your own accounts, your own tenants. Do not use it to evade a block that+ is telling you no.++## Related++- `/mso` — the CLI and everything else on the host+- `/mso-browser-list` — the retired Playwright sidecar (`:4002`), still used by+ `scripts/e2e` for screenshots+- `skills/camoufox-browse` (bundled in MSO's own catalog) — the scripting-level+ Camoufox skill for the in-app assistant, from ClawHubdiff --git a/claude-skills/mso-image-editor/SKILL.md b/claude-skills/mso-image-editor/SKILL.mdnew file mode 100644index 00000000..dda18252--- /dev/null+++ b/claude-skills/mso-image-editor/SKILL.md@@ -0,0 +1,83 @@+---+name: mso-image-editor+description: Edit images from the CLI by CRUD-ing an mso editor DOCUMENT (JSON) — open an image, run any editor op (layers, text, shapes, adjustments, blend/shadow/glow/stroke, transform, crop, resize), save it, then render by opening in the REAL mso editor. No bespoke renderer. Trigger on /mso-image-editor, "edit this image", "add text to image", "make a thumbnail/story", "resize/crop image", "adjust brightness/contrast", "drive the image editor from cli".+---++# /mso-image-editor — edit images via document CRUD++Edit images from here using the SAME command registry the in-browser editor's AI+panel uses. The CLI is **data-level**: it builds/updates an editor **document**+(JSON) via `POST /api/v1/editor/exec` (a React-free reducer — pure data, no+browser). To SEE the result, **open the doc in the real mso editor** ("render+= the actual editor"). This is just editor-document CRUD — see the generic+`mso crud` in [/mso]; this skill is the editor-doc-specialized front end.++```bash+SH=/home/rahman/.claude/skills/mso-image-editor/image-editor.sh+$SH open ~/pic.jpg # → 1:1 doc (image layer; dims via header probe)+$SH run adjust.set brightness=0.15 contrast=20+$SH run layer.add kind=text text="SALE 50%" fontSize=160 fill=#ff3366+$SH run transform.set x=120 y=200+$SH run style.shadow enabled=true distance=12 size=20 opacity=0.6+$SH inspect # layer stack + canvas state+$SH save ~/pic.doc.json # persist the doc to a host file+$SH view ~/pic.doc.json # → URL; open it to RENDER in the real editor+```++Other verbs: `new [WxH]` (blank doc), `tools` (every command + schema), `doc`+(raw session JSON). `k=v` values coerce: `12`/`1.5` → number, `true/false` →+bool, else string. Hex (`#ff3366`) is fine unquoted.++## Model (no parallel renderer)++- **Session** = a working Doc JSON (`$TMPDIR/mso-image-editor.session.json`). Each+ verb sends it + one command and saves the returned doc. `open`/`new` reset it;+ `save <path>` writes it to a real host file (what the editor opens).+- **CRUD mapping**: `new`/`open` = Create · `inspect`/`doc` = Read · `run` =+ Update · (delete the file via `mso crud del`). The generic equivalent:+ `mso crud set <path.json> <cmd k=v…>`.+- **Render = the REAL editor.** `save` to a `.doc.json`, then open+ `https://mso.rahmanef.com/studio/<abs-path>` (what `view` prints) — media-studio+ loads it into the actual Konva editor (`ImageEditor projectSrc`). Pixel-exact,+ zero duplicate engine. (There is no server-side PNG render anymore.)+- **Auth**: persistent cookie jar (`$TMPDIR/mso-image-editor.jar`), login only on+ 401 — same device-approval model as [/mso].++## Commands (32) — `$SH tools` for the full schema++| Domain | Commands |+|---|---|+| document | `doc.inspect` `doc.resize w h` `doc.aspect preset` `doc.crop x y w h` |+| layer | `layer.add kind=…` `layer.remove` `layer.duplicate` `layer.select` `layer.order move=raise\|lower\|front\|back` `layer.visibility visible=` `layer.lock locked=` `layer.rename name=` `layer.opacity opacity=` |+| transform | `transform.set x= y= width= height= rotation= scaleX= scaleY=` `transform.flip horizontal= vertical=` `text.edit text= fontSize= fill= …` `shape.edit shape= fillColor=` |+| adjust | `adjust.set brightness= contrast= saturation= hue= blur= grayscale= invert= sepia=` `adjust.reset` `adjust.addLayer` |+| style | `style.blend blend= clipBelow=` `style.shadow enabled= …` `style.glow enabled= …` `style.stroke enabled= color= width=` |+| tool | `tool.select tool=` `brush.set` `color.set fg= bg=` `color.swap` `mask.add` `mask.remove` `edit.undo` `edit.redo` |++Target a layer with `layerId=`/`layerName=`; omit → the selected layer (the last+added). `doc.aspect` presets: `Square 1:1`, `Portrait 4:5`, `Story 9:16`,+`Landscape 16:9`, `Wide 1.91:1`.++## Recipe++```bash+# Instagram story from a photo + title, rendered in the real editor+$SH open ~/photo.jpg+$SH run doc.aspect preset="Story 9:16"+$SH run layer.add kind=text text="NEW DROP" fontSize=140 fill=#ffffff fontStyle=bold+$SH run transform.set x=90 y=1500+$SH save ~/story.doc.json+$SH view ~/story.doc.json # open the printed URL → Konva renders it exactly+```++## Notes++- `set`/`run` only edit DATA; brush pixels are painted in the real editor (the+ doc carries layers/styles, not brush strokes). `image.removeBackground` is a+ browser-only op (run it in the editor's AI panel, not headless).+- Code: route `app/api/v1/editor/exec/route.ts`; engine+ `frontend/slices/image-editor/lib/headless/{editor-core,run,image-size}.ts`;+ server barrel `…/image-editor/server.ts`; render bridge `media-studio/app.tsx`+ + `image-editor.tsx` (`projectSrc`/`ProjectLoader`).+- Adding a command (a `commands/*.commands.ts` entry) exposes it to this CLI, the+ generic `mso crud`, AND the in-browser AI panel at once.diff --git a/claude-skills/mso-image-editor/image-editor.sh b/claude-skills/mso-image-editor/image-editor.shnew file mode 100755index 00000000..fdeedab1--- /dev/null+++ b/claude-skills/mso-image-editor/image-editor.sh@@ -0,0 +1,128 @@+#!/usr/bin/env bash+# image-editor.sh — drive the mso image editor HEADLESS from the CLI. Hits+# POST/GET /api/v1/editor/exec (the same command registry the in-browser AI uses)+# against a React-free Doc reducer + a skia renderer. No browser. The "session"+# (current Doc) lives in a temp JSON file; each verb sends it and saves the result.+#+# image-editor.sh new [WxH] fresh blank doc (default 1080x1080)+# image-editor.sh open <img> load an image file → 1:1 doc (image layer)+# image-editor.sh run <cmd> [k=v...] run one command (e.g. adjust.set brightness=0.2)+# image-editor.sh inspect print the layer stack / canvas state+# image-editor.sh tools list every command + description+# image-editor.sh doc print the raw session Doc JSON+# image-editor.sh save <path.json> write the doc to a host file (CRUD persist)+# image-editor.sh view <path.json> [--shot [out.png]]+# URL to open in the REAL editor (+ auto-screenshot)+#+# k=v values coerce: 12 / 1.5 → number, true/false → bool, else string.+# Session file: $OS_EDITOR_SESSION (default $TMPDIR/mso-image-editor.session.json).+set -euo pipefail++B="${OS_BASE:-http://127.0.0.1:4005}"+ENVF="${OS_ENV:-/home/rahman/projects/mso/.env.local}"+# shellcheck disable=SC1090+set -a; . "$ENVF" 2>/dev/null || true; set +a+PASS="${OS_PASSWORD:-${OS_LOGIN_PASSWORD:-}}"+# Share the one CLI device `mso` created + you approved, so this script never+# needs its own approval round.+DEV="${OS_DEVICE:-$(cat "$HOME/.mso/cli.device.id" 2>/dev/null || echo 46e72d1e9b22372eb6bdd6b76b11192b)}"+# proxy.ts blocks mutating /api without same-origin proof; Origin==Host is the+# documented non-browser path.+ORIGIN=(-H "origin: $B")+SESS="${OS_EDITOR_SESSION:-${TMPDIR:-/tmp}/mso-image-editor.session.json}"+[ -n "$PASS" ] || { echo "no OS_LOGIN_PASSWORD in $ENVF (set OS_PASSWORD)" >&2; exit 1; }++# Persistent cookie jar reused across invocations — log in only when the session+# is missing/expired (avoids the login rate-limiter on multi-command sequences).+JAR="${OS_EDITOR_JAR:-${TMPDIR:-/tmp}/mso-image-editor.jar}"+EXEC="$B/api/v1/editor/exec"++login() {+ local code+ code=$(curl -sS -o /dev/null -w '%{http_code}' -c "$JAR" "${ORIGIN[@]}" -X POST "$B/api/auth/login" \+ -H 'content-type: application/json' \+ -d "$(jq -n --arg p "$PASS" --arg d "$DEV" '{password:$p,deviceId:$d,deviceLabel:"os-image-editor cli"}')" || true)+ [ "$code" = "200" ] || { echo "login failed ($code). approve device? → node ~/projects/mso/scripts/approve-device.js $DEV" >&2; exit 1; }+}+[ -f "$JAR" ] || login++# Run a request with the cached cookie; on 401 (expired) log in once + retry.+req() {+ local out code body+ out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)+ code="${out##*$'\n'}"; body="${out%$'\n'*}"+ if [ "$code" = "401" ] || [ "$code" = "403" ]; then+ login; out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)+ code="${out##*$'\n'}"; body="${out%$'\n'*}"+ fi+ [ "$code" = "200" ] || { echo "request failed ($code): $body" >&2; exit 1; }+ printf '%s' "$body"+}+post() { local p; p=$(cat); req -H 'content-type: application/json' -d "$p" "$EXEC"; }+have_session() { [ -f "$SESS" ] || { echo "no session — run 'open <img>' or 'new' first" >&2; exit 1; }; }+save_doc() { jq -e '.doc' >/dev/null <<<"$1" && jq '.doc' <<<"$1" >"$SESS"; }+show_results() { jq -r '.results[]? | " \(.name) \(if .ok then "ok" else "ERR" end) — \(.result)"' <<<"$1"; }++# Build a JSON args object from k=v pairs, coercing numbers + booleans.+build_args() {+ local j='{}' kv k v+ for kv in "$@"; do+ k="${kv%%=*}"; v="${kv#*=}"+ if [[ "$v" =~ ^-?[0-9]+([.][0-9]+)?$ || "$v" == "true" || "$v" == "false" ]]; then+ j=$(jq -c --arg k "$k" --argjson v "$v" '. + {($k):$v}' <<<"$j")+ else+ j=$(jq -c --arg k "$k" --arg v "$v" '. + {($k):$v}' <<<"$j")+ fi+ done+ printf '%s' "$j"+}++cmd="${1:-help}"; shift || true+case "$cmd" in+ new)+ resp=$(echo '{"commands":[]}' | post); save_doc "$resp"+ if [ -n "${1:-}" ] && [[ "$1" =~ ^([0-9]+)x([0-9]+)$ ]]; then+ a=$(build_args "width=${BASH_REMATCH[1]}" "height=${BASH_REMATCH[2]}")+ resp=$(jq -n --slurpfile d "$SESS" --argjson a "$a" '{doc:$d[0],commands:[{name:"doc.resize",args:$a}]}' | post)+ save_doc "$resp"+ fi+ echo "new session → $SESS"; jq -r '" \(.width)x\(.height), \(.layers|length) layer(s)"' "$SESS" ;;+ open)+ f="${1:?image path}"; [ -f "$f" ] || { echo "no such file: $f" >&2; exit 1; }+ f=$(realpath "$f"); name=$(basename "$f")+ # Send the host PATH (not bytes) — the route probes dims from the file header+ # and stores a light same-origin path-URL src, so the doc carries no base64.+ resp=$(jq -n --arg p "$f" --arg n "$name" '{imagePath:$p,open:true,name:$n}' | post)+ save_doc "$resp"; echo "opened $f → $SESS"; jq -r '" \(.width)x\(.height), \(.layers|length) layer(s)"' "$SESS" ;;+ run)+ have_session; name="${1:?command name}"; shift || true+ a=$(build_args "$@")+ resp=$(jq -n --slurpfile d "$SESS" --arg n "$name" --argjson a "$a" '{doc:$d[0],commands:[{name:$n,args:$a}]}' | post)+ save_doc "$resp"; show_results "$resp" ;;+ inspect)+ have_session+ resp=$(jq -n --slurpfile d "$SESS" '{doc:$d[0],commands:[{name:"doc.inspect"}]}' | post)+ jq -r '.results[0].result' <<<"$resp" ;;+ tools)+ req "$EXEC" | jq -r '.tools[] | " \(.name)\t\(.description)"' ;;+ doc) have_session; cat "$SESS"; echo ;;+ save)+ have_session; out="${1:?dest path, e.g. ~/x.doc.json}"+ req -H 'content-type: application/json' \+ -d "$(jq -n --arg p "$out" --arg c "$(jq -c . "$SESS")" '{path:$p,content:$c}')" \+ "$B/api/v1/fs/write" >/dev/null+ echo "saved doc → $out (render: $0 view $out)" ;;+ view)+ p="${1:?path}"; shift || true+ base="${OS_PUBLIC_BASE:-https://mso.rahmanef.com}"+ case "$p" in /*) ;; *) p="/$p" ;; esac+ url="$base/studio$p"; echo "$url"+ if [ "${1:-}" = "--shot" ]; then+ out="${2:-/tmp/studio-view.png}"+ BR="${OS_BROWSER_SH:-/home/rahman/.claude/skills/mso/browser.sh}"+ "$BR" go "$url" >/dev/null 2>&1; sleep 7; "$BR" shot "$out" # needs a logged-in browser+ else+ echo "# open that URL (logged-in browser) — Konva renders the doc; add --shot [out.png] to auto-screenshot"+ fi ;;+ *) sed -n '2,20p' "$0" ;;+esacdiff --git a/claude-skills/mso-list/SKILL.md b/claude-skills/mso-list/SKILL.mdnew file mode 100644index 00000000..e8cba72b--- /dev/null+++ b/claude-skills/mso-list/SKILL.md@@ -0,0 +1,51 @@+---+name: mso-list+description: List every mso app + its functions and check they actually work end-to-end (live probe of all /api/v1 calls). Trigger on /mso-list, "list os features", "check all os functions", "audit os apps", "what works in the os", "are the os functions working".+---++# /mso-list — audit all OS apps + functions++Enumerate every mso app, its user-facing functions / AI-Inspector actions, and+verify the backing calls work against the live host. Pairs with [/mso] (control)+and [/mso-browser-list] (browser deep-dive).++## 1. Live probe (run this first)++```bash+cd /home/rahman/projects/mso && node ~/.claude/skills/mso-list/audit.js+```+Signs in (device-password, password + approved device from env or defaults) and+hits every `/api/v1` endpoint, printing a pass/fail table. Override with env+`OS_BASE`, `OS_CONVEX`, `OS_PASSWORD`, `OS_DEVICE`. Needs the `convex` dep (run+from the repo). A function is "working" only if its endpoint returns 2xx here.++## 2. App → function matrix++| App | Functions | Backing call | Notes |+|---|---|---|---|+| **shell** | open/close/min/max/snap, dock, launchpad, Spotlight ⌘K, AI Inspector ⌘I, menu File/Edit/View | local store | no host call |+| **files-manager** | navigate, breadcrumb/back/fwd, favorites (real roots), live tree, new folder/file, rename, move (drag), copy/cut/paste, trash*, upload, details | `fs.list/mkdir/write/move/copy/remove/usage` | trash to /.Trash fails on live (outside write root) |+| **code-editor** | live tree, open (fs.read), edit, save (fs.write), new file, tabs | `fs.read/write/list` | |+| **terminal** | ls/cat/cd (+13 builtins), mkdir/rm/mv/cp/touch (live fs), unknown cmd → host shell | `fs.*`, `exec.run` | live passthrough |+| **browser** | omnibar nav, back/fwd/reload, bookmarks, history, in-page link/form click-through | `/api/v1/proxy` | see [/mso-browser-list] |+| **system-monitor** | gauges, sparklines, process table, refresh | `sys.stats/processes` | |+| **reel-editor** | timeline, clips, keyframes, render→.webm, Inspector "Render" | client canvas | render is client-side |+| **media-studio** | layers, tools, filters, export, Inspector add/export/undo | client | |+| **media-viewer** | image/video/audio view, download, open-in-editor | `fs.read` | |+| **app-store / create-app** | install/uninstall, create runtime app | Convex `features/apps` | |+| **runtime-app** | html→iframe, command runtime→Run console | `exec.run` | |+| **os-settings** | theme/accent/device, server mock/live, AI key, devices approve | Convex + local | |+| **assistant (Alfa)** | streaming chat, agents/skills/automations | `/api/assistant` | needs ANTHROPIC_API_KEY |+| **AI Inspector** (every app) | Properties (live state) + scoped AI chat | `usePublishInspector` + `/api/assistant` | AI tab needs ANTHROPIC_API_KEY |++## 3. Caveats that make a function "look broken"++- **AI tab / Alfa**: blank/"no key" until `ANTHROPIC_API_KEY` is set in the Dokploy+ mso env (or Settings → AI). Backend route is fine; it just has no key.+- **Live mode**: file/exec/sys functions only hit the VPS when Settings → Server →+ **Live**. In Mock they use the in-browser sim. Token must be present.+- **Trash on live**: `/.Trash` is outside the write root → move fails. Known gap.+- **Browser in-page nav**: works via the injected click-through; heavy SPAs / login+ flows still constrained — see [/mso-browser-list].++Report = the probe table + which apps are fully green vs gated (AI key / live mode).diff --git a/claude-skills/mso-list/audit.js b/claude-skills/mso-list/audit.jsnew file mode 100644index 00000000..c975fcfb--- /dev/null+++ b/claude-skills/mso-list/audit.js@@ -0,0 +1,90 @@+// os-list audit — logs in (password + approved device → signed cookie) and+// probes every mso /api/v1 function end-to-end, printing a pass/fail table.+// No Convex (removed 2026-05-30) — auth is the session cookie.+// node ~/.claude/skills/mso-list/audit.js+const fs = require("fs");+// Read a key from mso/.env.local — so the password is sourced, never hardcoded.+function fromEnvFile(key) {+ try {+ const t = fs.readFileSync(process.env.OS_ENV || "/home/rahman/projects/mso/.env.local", "utf8");+ const m = t.match(new RegExp("^" + key + "=(.*)$", "m"));+ return m ? m[1].trim().replace(/^['"]|['"]$/g, "") : "";+ } catch {+ return "";+ }+}+const BASE = process.env.OS_BASE || "https://mso.rahmanef.com";+const PASS = process.env.OS_PASSWORD || fromEnvFile("OS_LOGIN_PASSWORD");+const DEV =+ process.env.OS_DEVICE ||+ (() => { try { return require("fs").readFileSync(require("os").homedir() + "/.mso/cli.device.id", "utf8").trim(); } catch { return "46e72d1e9b22372eb6bdd6b76b11192b"; } })();+// proxy.ts blocks mutating /api without same-origin proof; Origin==Host is the+// documented non-browser path.+const ORIGIN = { origin: BASE };+if (!PASS) {+ console.error("no password — set OS_PASSWORD or OS_LOGIN_PASSWORD in mso/.env.local");+ process.exit(1);+}++(async () => {+ // 1) login → capture the session cookie.+ let cookie;+ try {+ const r = await fetch(BASE + "/api/auth/login", {+ method: "POST",+ headers: { "content-type": "application/json", ...ORIGIN },+ body: JSON.stringify({ password: PASS, deviceId: DEV, deviceLabel: "os-list audit" }),+ });+ if (r.status === 403) {+ console.error("device_pending — approve it: node ~/projects/mso/scripts/approve-device.js " + DEV);+ process.exit(1);+ }+ if (!r.ok) {+ console.error("login failed:", r.status, (await r.json().catch(() => ({}))).error);+ process.exit(1);+ }+ const sc = r.headers.get("set-cookie") || "";+ cookie = (sc.match(/session=[^;]+/) || [])[0];+ } catch (e) {+ console.error("login error:", e.message);+ process.exit(1);+ }+ if (!cookie) {+ console.error("no session cookie returned");+ process.exit(1);+ }+ const H = { cookie, "content-type": "application/json" };++ const probes = [+ ["GET", "/api/v1/sys/stats", null, "system-monitor: live CPU/mem/disk"],+ ["GET", "/api/v1/sys/processes", null, "system-monitor: process table"],+ ["GET", "/api/v1/fs/list?path=~", null, "files/code/tree: list dir"],+ ["GET", "/api/v1/fs/usage?path=~", null, "files: storage gauge"],+ ["GET", "/api/v1/apps", null, "app-store: runtime apps"],+ ["POST", "/api/v1/exec/run", { cmd: "echo ok" }, "terminal/runtime-app: exec"],+ ["POST", "/api/v1/fs/mkdir", { path: "~/.os-audit" }, "files/tree: new folder"],+ ["POST", "/api/v1/fs/write", { path: "~/.os-audit/a", content: "x" }, "files/tree/editor: write/save"],+ // Reads back what the write probe just made: any path under $HOME is inside+ // OS_FS_READ_ROOTS on every install, unlike the /etc/hostname this used to+ // probe (that only passed while the roots were the wide-open "/").+ ["GET", "/api/v1/fs/read?path=~/.os-audit/a", null, "code/viewer: read file"],+ ["POST", "/api/v1/fs/move", { from: "~/.os-audit/a", to: "~/.os-audit/b" }, "files: move/rename"],+ ["POST", "/api/v1/fs/copy", { from: "~/.os-audit/b", to: "~/.os-audit/c" }, "files: copy"],+ ["DELETE", "/api/v1/fs/delete", { path: "~/.os-audit" }, "files: delete/trash"],+ // The Browser app is Camoufox now; /api/v1/browser was retired with the+ // Playwright sidecar and 404s.+ ["GET", "/api/v1/camoufox/service", null, "browser: camoufox VNC service state"],+ ];+ console.log(`OS function audit @ ${BASE} (cookie auth)\n`);+ let ok = 0;+ for (const [m, p, b, label] of probes) {+ try {+ const r = await fetch(BASE + p, { method: m, headers: { ...H, ...ORIGIN }, body: b ? JSON.stringify(b) : undefined });+ console.log(`${r.ok ? "OK " : "FAIL"} ${r.status} ${m.padEnd(6)} ${p.split("?")[0].padEnd(24)} ${label}`);+ if (r.ok) ok++;+ } catch (e) {+ console.log(`ERR ${m.padEnd(6)} ${p.split("?")[0].padEnd(24)} ${e.message}`);+ }+ }+ console.log(`\n${ok}/${probes.length} endpoints OK`);+})();diff --git a/claude-skills/mso/SKILL.md b/claude-skills/mso/SKILL.mdnew file mode 100644index 00000000..b20123df--- /dev/null+++ b/claude-skills/mso/SKILL.md@@ -0,0 +1,124 @@+---+name: mso+description: Control the mso web OS + its VPS host from here. Drive the live OS at mso.rahmanef.com — browse/read/write files anywhere on the VPS, run shell commands, manage apps, check system status, deploy. Trigger on /mso, "control the os", "control my vps", "drive mso", "open the OS", "run on the vps", "browse the vps files".+---++# /mso — control the VPS OS++Operate **mso** (live web OS at https://mso.rahmanef.com) and its VPS host.+mso is **self-contained**: it runs AS a host process (systemd, :4005) and does+fs/exec/sys itself — NO Control Room agent, NO Convex. This box (`srv614914`) IS+the VPS, so you can also act directly via Bash.++## Two ways to act++1. **Direct (you run AS rahman on this box)** — just use Bash. Fastest for local work.+2. **Through mso** (`mso`) — drives the host the SAME `/api/v1` the web OS+ uses, so behaviour matches what the user sees. Use to reproduce/debug the OS or+ get its bounded fs semantics.++```bash+SH=mso+$SH health # session ok?+$SH ls ~/projects # list (READ = whole filesystem)+$SH cat ~/projects/mso/README.md+$SH exec "df -h && uptime" # run anything (full shell)+$SH write ~/scratch/note.txt "hi" # WRITE bounded to home + ~/projects+$SH mkdir ~/scratch/new ; $SH mv ~/a.txt ~/projects/a.txt+$SH stats ; $SH ps # telemetry + processes+```++### Generic resource CRUD (`crud`)++One pattern for every host resource (`mso crud`):++```bash+$SH crud list ~/projects # → fs.list+$SH crud get ~/notes/a.md # → fs.read+$SH crud set ~/notes/a.md "plain text" # write a file+$SH crud set ~/x.doc.json layer.add kind=text text=Hi # edit an editor DOC (atomic, 1 call)+$SH crud del ~/notes/a.md ; $SH crud cmds # delete ; list editor commands+```++`crud set <path.json> <editor-cmd k=v…>` is a SINGLE atomic server op (route reads+the doc file → applies the command → writes it back in place; missing file is+seeded, an existing non-doc file is REFUSED, not clobbered). Truly CRUD-able =+host files + editor docs + the `~/.mso/*.json` config/device files. NOT+crud-able (live in the browser): theme/server toggle, window layout, the app+registry (localStorage); sys stats are read-only. To VIEW an edited doc, open it+in the real editor (see [/mso-image-editor] `view`). Raster ops (brush pixels,+masks, background removal) are browser-only by design — there is no headless+renderer.++`mso` needs `jq`. It logs in (POST `/api/auth/login`) with `OS_LOGIN_PASSWORD`+from `/home/rahman/projects/mso/.env.local` + an approved device id (default+`46e72…`), keeps the session cookie in a temp jar. Override base with `OS_BASE`.+If login 403s → device pending → `node ~/projects/mso/scripts/approve-device.js <id>`.++## mso endpoints (cookie-auth, what the OS calls)++All under `/api/v1`, gated by the signed session cookie (sent automatically).++| Method | Path | Body / query | Notes |+|---|---|---|---|+| GET | `/fs/list?path=` | — | `{path,parent,roots,entries[]}`; READ = whole fs; hidden incl |+| GET | `/fs/read?path=` | — | raw utf8 string (≤5 MiB) |+| GET | `/fs/usage?path=` | — | `{used,total}` |+| POST | `/fs/write` | `{path,content}` | atomic; **home+~/projects only** |+| POST | `/fs/mkdir` | `{path}` | bounded |+| DELETE | `/fs/delete` | `{path}` | recursive; bounded |+| POST | `/fs/move` / `/fs/copy` | `{from,to}` | bounded |+| POST | `/exec/run` | `{cmd,cwd?}` | one-shot `/bin/bash`, 30s, 1 MiB out, cwd bounded |+| GET | `/sys/stats` / `/sys/processes` | — | telemetry / `ps` |+| GET | `/api/auth/me` | — | session check |++**Bounds env** (in `mso/.env.local`): `OS_FS_READ_ROOTS` (default `/` here →+browse anywhere), `OS_FS_WRITE_ROOTS` (default home+projects). Logic in+`mso/lib/host/`. Change → `sudo systemctl restart mso`.++## Real browser (Playwright, you can drive + see it)++Real headless Chromium runs as systemd `os-browser` (Playwright, loopback :4002,+secret in `/home/rahman/projects/mso/os-browser/.env`). ONE persistent context+(`~/.mso/chrome-profile`) → cookies/cache/session on disk, SHARED between the+Browser app and the CLI. Renders any site (no X-Frame-Options).++```bash+SH=/home/rahman/.claude/skills/mso/browser.sh+$SH go github.com # navigate (bare words → google search)+$SH shot /tmp/b.png # screenshot → Read it to SEE the page+$SH content # innerText+$SH click 640 380 ; $SH type "hello" ; $SH key Enter ; $SH scroll 600+$SH state ; $SH back ; $SH reload+```+Web OS reaches it via `/api/v1/browser/*` (cookie-auth → 127.0.0.1:4002).+Restart: `sudo systemctl restart os-browser`. Code: `mso/os-browser/server.mjs`.++## The web OS (mso)++- Repo `/home/rahman/projects/mso` (`[email protected]:rahmanef63/mso.git`).+- Live `mso.rahmanef.com`. **Auth = password + device approval** (signed cookie, no+ Convex). New device → "pending" → approve in Settings → Devices, or CLI.+- **Settings → Server → Live** routes file/exec/sys through `/api/v1` (host ops are+ internal now). Mock is the default (demo with no host access).+- **AI Inspector** (⌘I): per-app props + scoped Alfa chat. Alfa needs a key —+ Settings → AI (BYOK, `~/.mso/config.json`) or `ANTHROPIC_API_KEY` env.+- Persistence is local: window layout + installed apps in localStorage; devices ++ config in `~/.mso/*.json`.++## Operate / deploy++- **Off Dokploy.** Prod = the local working dir served by systemd `mso.service`+ (`next start` :4005). Editing + rebuilding the repo IS deploying.+- **Deploy a change**: edit → `cd ~/projects/mso && pnpm typecheck && pnpm build`+ → `sudo systemctl restart mso` → verify. `git push` is version-control only.+- **Status**: `mso exec "systemctl is-active mso os-browser"`; site 200 check.+- Audit everything: `node ~/.claude/skills/mso-list/audit.js` (13 endpoints).++## Safety++- Restarting `mso` / `os-browser` is fine (task targets). Do NOT restart+ `vps-control-room-*` without warning the user — separate live product.+- `exec` is full shell as `rahman`. Confirm destructive commands (rm -rf, service+ changes) with the user first.+- Never echo `.env.local`, the session secret, the login password, or device store.diff --git a/claude-skills/mso/browser.sh b/claude-skills/mso/browser.shnew file mode 100755index 00000000..6864a801--- /dev/null+++ b/claude-skills/mso/browser.sh@@ -0,0 +1,40 @@+#!/usr/bin/env bash+# browser.sh — drive the REAL headless browser (Playwright Chromium) the mso+# Browser app uses. Same persistent session/cache, so logged-in state is shared.+# Screenshots land in /tmp so they can be Read (viewed) directly.+#+# browser.sh go <url> navigate (bare words → google search)+# browser.sh shot [file] screenshot → /tmp/os-browser.png (or file); prints path+# browser.sh content page innerText (read what's on screen)+# browser.sh state current url + title+# browser.sh click <x> <y> click viewport px (1280x800)+# browser.sh type <text> type text+# browser.sh key <Key> press a key (Enter, Backspace, Tab, ArrowDown…)+# browser.sh scroll <dy> wheel by dy px+# browser.sh back|forward|reload+# browser.sh health+set -euo pipefail++ENVF="${OS_BROWSER_ENV:-/home/rahman/projects/mso/os-browser/.env}"+# shellcheck disable=SC1090+set -a; . "$ENVF" 2>/dev/null || true; set +a+SEC="${OS_BROWSER_SECRET:-}"+B="${OS_BROWSER_BASE:-http://127.0.0.1:4002}"+[ -n "$SEC" ] || { echo "no OS_BROWSER_SECRET in $ENVF" >&2; exit 1; }+H=(-H "x-os-browser-secret: $SEC")+J=(-H 'content-type: application/json')++cmd="${1:-help}"; shift || true+case "$cmd" in+ go|navigate) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --arg u "${1:?url}" '{url:$u}')" "$B/navigate"; echo ;;+ shot|screenshot) f="${1:-/tmp/os-browser.png}"; curl -fsS "${H[@]}" "$B/screenshot" -o "$f"; echo "saved $f ($(stat -c%s "$f") bytes) — Read it to view" ;;+ content) curl -fsS "${H[@]}" "$B/content" ;;+ state) curl -fsS "${H[@]}" "$B/state"; echo ;;+ click) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --argjson x "${1:?x}" --argjson y "${2:?y}" '{x:$x,y:$y}')" "$B/click"; echo ;;+ type) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --arg t "${*:?text}" '{text:$t}')" "$B/type"; echo ;;+ key) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --arg k "${1:?key}" '{key:$k}')" "$B/key"; echo ;;+ scroll) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --argjson d "${1:?dy}" '{dy:$d}')" "$B/scroll"; echo ;;+ back|forward|reload) curl -fsS "${H[@]}" "${J[@]}" -d '{}' "$B/$cmd"; echo ;;+ health) curl -fsS "$B/health"; echo ;;+ *) sed -n '2,20p' "$0" ;;+esacdiff --git a/scripts/install.sh b/scripts/install.shindex bf3f7a0f..75d5e4a3 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -243,6 +243,33 @@ else[ "$DO_SERVICE" -eq 1 ] && warn "no systemctl here — skipping service. Run manually: PORT=$PORT pnpm start"fi+# ---- CLI on PATH ----+# 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"+ln -sfn "$DIR/bin/mso" "$BIN_DIR/mso"+ok "cli → $BIN_DIR/mso"+case ":$PATH:" in+ *":$BIN_DIR:"*) ;;+ *) warn "$BIN_DIR is not on PATH — add: export PATH=\"\$PATH:$BIN_DIR\"" ;;+esac++# ---- agent skills (symlinked, so a git pull updates them too) ----+# Skipped silently when Claude Code isn't installed — mso does not depend on it.+SKILL_DIR="${MSO_SKILL_DIR:-$HOME/.claude/skills}"+if [ -d "$DIR/claude-skills" ] && [ -d "$(dirname "$SKILL_DIR")" ]; then+ mkdir -p "$SKILL_DIR"+ for s in "$DIR"/claude-skills/*/; do+ name="$(basename "$s")"+ if [ -e "$SKILL_DIR/$name" ] && [ ! -L "$SKILL_DIR/$name" ]; then+ warn "skill $name exists and is not a symlink — left alone"+ continue+ fi+ ln -sfn "${s%/}" "$SKILL_DIR/$name"+ done+ ok "skills → $SKILL_DIR (/mso, /mso-camoufox, /mso-apps, /mso-list, …)"+fi+# ---- next steps ----ok "mso installed at $DIR"cat <<EOFdiff --git a/vitest.config.mts b/vitest.config.mtsindex c6599e7b..12af9814 100644--- a/vitest.config.mts+++ b/vitest.config.mts@@ -22,6 +22,7 @@ export default defineConfig({"app/**/*.test.{ts,tsx}","frontend/slices/**/*.test.{ts,tsx}","lib/**/*.test.{ts,tsx}",+ "bin/**/*.test.{ts,tsx}","scripts/e2e/**/*.test.{ts,tsx}","instrumentation.test.ts",// Root-level modules Next requires by name (middleware is `proxy.ts` in 16),