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.

refactor: separate shared client server contracts

Rahmanfef822e61e08
diff --git a/app/os-root.tsx b/app/os-root.tsx
index 99d29fad..7358d750 100644
--- a/app/os-root.tsx
+++ b/app/os-root.tsx
@@ -9,11 +9,12 @@ import {
TOPSIDE_PERSIST_KEY,
BUILTIN_APPS,
topsideCapabilities,
+ OsApiProvider,
} from "@/features/os-shell";
import { AppearanceProvider } from "@/lib/appearance";
import { QuicklinksProvider } from "@/lib/quicklinks";
import "@/features/os-shell/integrations";
-import { OsApiProvider } from "@/lib/os-api";
+
import { AuthGate, SessionProvider, useSession, type DeviceRole, type SessionStatus } from "@/features/auth";
import { appAllowedForRole } from "@/lib/auth/app-access";
import { useInstalledApps, useDisabledIds } from "@/features/app-store";
diff --git a/architecture.boundaries.json b/architecture.boundaries.json
index c2010acb..d1ad3e1d 100644
--- a/architecture.boundaries.json
+++ b/architecture.boundaries.json
@@ -5,7 +5,7 @@
"crossDomainCycles": 0,
"filesOver220": 54,
"filesOver500": 1,
- "serverFrontendImports": 6,
+ "serverFrontendImports": 0,
"appshellSelfBarrelImports": 0,
"nonMcpMcpImports": 0,
"crossProtocolCycles": 0,
diff --git a/components/shared/file-tree/dir.tsx b/components/shared/file-tree/dir.tsx
index 634f468f..d2421e95 100644
--- a/components/shared/file-tree/dir.tsx
+++ b/components/shared/file-tree/dir.tsx
@@ -10,7 +10,7 @@ import {
Loader2,
} from "lucide-react";
import { Button } from "@/components/ui/button";
-import { useOsApi, type FsEntry } from "@/lib/os-api";
+import { useOsApi, type FsEntry } from "@/features/appshell";
import { cn } from "@/lib/utils";
export type TreeCtx = {
diff --git a/frontend/slices/appshell/lib/host-api.tsx b/frontend/slices/appshell/lib/host-api.tsx
index d5136932..35b19f0c 100644
--- a/frontend/slices/appshell/lib/host-api.tsx
+++ b/frontend/slices/appshell/lib/host-api.tsx
@@ -10,169 +10,13 @@
import { createContext, useContext, type ReactNode } from "react";
-export type Unsub = () => void;
-
-export type HostAccessRole = "viewer" | "operator" | "owner" | "demo";
-export type HostAccess = {
- role: HostAccessRole;
- canRead: boolean;
- canOperate: boolean;
- canOwn: boolean;
-};
-
-export type SysStats = {
- cpu: { pct: number; cores: number };
- mem: { used: number; total: number };
- disk: { used: number; total: number };
- net?: { rx: number; tx: number };
- /** Host uptime in MILLISECONDS. */
- uptime: number;
-};
-
-export type FsEntry = {
- name: string;
- kind: "dir" | "file";
- size: number;
- ext?: string;
- mime?: string;
-};
-export type FsRoot = { label: string; path: string };
-export type FsList = {
- /** Canonical absolute path the host resolved (e.g. "/" → "/home/user"). */
- path: string;
- entries: FsEntry[];
- /** Jump-point roots (Home, Projects, Filesystem…) for the sidebar. */
- roots?: FsRoot[];
- /** Parent dir within bounds, or null at a root. */
- parent?: string | null;
-};
-export type FsUsage = { used: number; total: number };
-
-/** A search hit — a folder (or file) matched by name under a search root. */
-export type FsHit = { name: string; path: string; kind: "dir" | "file" };
-
-/** One upload item. `relPath` keeps folder structure (e.g. "imgs/a.png"); for a
- * loose file it's just the name. `file` carries the raw bytes. */
-export type UploadFile = { relPath: string; file: File };
-/** Per-request upload outcome: how many landed, and which relPaths were skipped. */
-export type UploadResult = { written: number; failed?: string[] };
-/** Upload progress tick — bytes sent so far / total bytes across the whole batch. */
-export type UploadProgress = { loaded: number; total: number };
-
-/** One-shot command result: full stdout/stderr + exit code (no streaming/pty). */
-export type ExecResult = { stdout: string; stderr: string; code: number };
-
-export type Process = {
- pid: number;
- name: string;
- status: string;
- cpu: number;
- mem: number;
-};
-
-export type ServiceScope = "system" | "user";
-export type ServiceAction = "start" | "stop" | "restart";
-export type SystemService = {
- unit: string;
- scope: ServiceScope;
- load: string;
- active: string;
- sub: string;
- description: string;
- controllable: boolean;
-};
-export type ServiceInventory = {
- services: SystemService[];
- diagnostics: string[];
- truncated: boolean;
- controlAllowlistConfigured: boolean;
- generatedAt: string;
-};
-export type ServiceLogs = {
- unit: string;
- scope: ServiceScope;
- entries: string[];
- available: boolean;
- diagnostic?: string;
-};
-export type PackageUpdate = {
- name: string;
- current?: string;
- candidate: string;
- architecture?: string;
-};
-export type PackageUpdateSummary = {
- manager: "apt" | "dnf" | "yum" | "pacman" | "zypper" | null;
- available: boolean;
- updates: PackageUpdate[];
- truncated: boolean;
- checkedAt: string;
- source: "local-cache";
- diagnostic?: string;
-};
-
-export type AppManifest = { name: string; slug: string; runtime: string; entry: string };
-
-/** A managed application on the host (hermes, openclaw) — the thing that actually
- * has server state, unlike the UI app list, which lives in localStorage. */
-export type ManagedAppSummary = { id: string; name: string; installed: boolean; running: boolean };
-export type ManagedAppAction = "start" | "stop" | "restart" | "backup";
-export type BrowserState = { installed: boolean; running: boolean; autostart: boolean };
-
-export type OsApi = {
- mode: "mock" | "live";
- access: HostAccess;
- auth: {
- token: (u: string, p: string) => Promise<{ token: string; expires_at: number }>;
- me: () => Promise<{ user: { name: string; id: string } }>;
- };
- fs: {
- list: (path: string) => Promise<FsList>;
- read: (path: string) => Promise<string>;
- write: (path: string, content: string) => Promise<{ ok: boolean }>;
- mkdir: (path: string) => Promise<{ kind: "dir" }>;
- remove: (path: string) => Promise<{ ok: boolean }>;
- /** Move/rename: `to` is the full destination path (rename == move within dir). */
- move: (from: string, to: string) => Promise<{ ok: boolean }>;
- /** Recursive copy of a file or dir to a full destination path. */
- copy: (from: string, to: string) => Promise<{ ok: boolean }>;
- /** Binary-safe upload of files (and folders, via relPath) into `dest`.
- * `onProgress` fires as bytes go out (chunked under the hood for reliability). */
- upload: (
- dest: string,
- files: UploadFile[],
- onProgress?: (p: UploadProgress) => void,
- ) => Promise<UploadResult>;
- /** Find folders by name under a root (default ~/projects). Read-only. */
- search: (query: string) => Promise<FsHit[]>;
- usage: () => Promise<FsUsage>;
- };
- exec: {
- /** Run a shell command on the host (cwd defaults to home). One-shot, captured output. */
- run: (cmd: string, cwd?: string) => Promise<ExecResult>;
- };
- sys: {
- stats: () => Promise<SysStats>;
- statsStream: (onEvent: (s: Partial<SysStats>) => void) => Unsub;
- processes: () => Promise<Process[]>;
- services: () => Promise<ServiceInventory>;
- serviceLogs: (scope: ServiceScope, unit: string, limit?: number) => Promise<ServiceLogs>;
- servicePower: (scope: ServiceScope, unit: string, action: ServiceAction) => Promise<SystemService>;
- packageUpdates: () => Promise<PackageUpdateSummary>;
- };
- // Managed apps, not the UI app list. `start`/`stop` used to sit here pointed at
- // /apps/:slug/start and /apps/:slug/stop — neither of which is a route — while
- // `list` hit /apps, which returns [] by construction.
- apps: {
- list: () => Promise<ManagedAppSummary[]>;
- logs: (id: string) => Promise<{ available: boolean; entries: string[] }>;
- power: (id: string, action: ManagedAppAction) => Promise<ManagedAppSummary>;
- };
- browser: {
- status: () => Promise<BrowserState>;
- power: (on: boolean) => Promise<BrowserState>;
- };
-};
+export type {
+ Unsub, HostAccessRole, HostAccess, SysStats, FsEntry, FsRoot, FsList, FsUsage, FsHit,
+ UploadFile, UploadResult, UploadProgress, ExecResult, Process, ServiceScope, ServiceAction,
+ SystemService, ServiceInventory, ServiceLogs, PackageUpdate, PackageUpdateSummary, AppManifest,
+ ManagedAppSummary, ManagedAppAction, BrowserState, OsApi,
+} from "@/lib/contracts/os-api";
+import type { OsApi } from "@/lib/contracts/os-api";
const HostApiContext = createContext<OsApi | null>(null);
diff --git a/frontend/slices/image-picker/lib/imageStyle.ts b/frontend/slices/image-picker/lib/imageStyle.ts
index 9d0bf6f9..fb06bef0 100644
--- a/frontend/slices/image-picker/lib/imageStyle.ts
+++ b/frontend/slices/image-picker/lib/imageStyle.ts
@@ -1,25 +1 @@
-/** Build the CSS for an image value. URL-backed images apply a vertical focal
- * point via background-position; colour/gradient values go straight into
- * `background`. `resolvedUrl` is the host-resolved URL for upload (FileRef)
- * values. */
-
-import type { CSSProperties } from "react";
-import type { ImageValue } from "../types";
-import { isUrlImage } from "./parseImage";
-
-export function imageStyle(img: ImageValue, resolvedUrl?: string | null): CSSProperties {
- const posY = img.positionY ?? 50;
- if (isUrlImage(img)) {
- const url = resolvedUrl ?? img.value;
- // Escape the CSS string: backslash/quote get backslash-escaped and newlines
- // stripped so a crafted value can't break out of the url("…") literal.
- const safeUrl = url.replace(/[\\"]/g, "\\$&").replace(/[\r\n]/g, "");
- return {
- backgroundImage: `url("${safeUrl}")`,
- backgroundSize: "cover",
- backgroundPosition: `center ${posY}%`,
- backgroundRepeat: "no-repeat",
- };
- }
- return { background: img.value };
-}
+export { imageStyle } from "@/lib/contracts/image";
diff --git a/frontend/slices/image-picker/lib/parseImage.ts b/frontend/slices/image-picker/lib/parseImage.ts
index 1535d423..3f58a18e 100644
--- a/frontend/slices/image-picker/lib/parseImage.ts
+++ b/frontend/slices/image-picker/lib/parseImage.ts
@@ -1,46 +1 @@
-/** Normalize a stored image field into an ImageValue (or null). Keeps legacy
- * raw-string values working — raw URLs / CSS colours / gradients are detected
- * and wrapped. */
-
-import type { ImageValue, ImageField } from "../types";
-
-function looksLikeGradient(s: string): boolean {
- return /^(linear|radial|conic)-gradient\(/i.test(s.trim());
-}
-
-function looksLikeColor(s: string): boolean {
- const v = s.trim();
- return /^#[0-9a-f]{3,8}$/i.test(v)
- || /^(rgb|rgba|hsl|hsla)\(/i.test(v)
- || /^(red|blue|green|black|white|gray|grey|yellow|orange|purple|pink|brown)$/i.test(v);
-}
-
-function looksLikeUrl(s: string): boolean {
- return /^https?:\/\//i.test(s.trim()) || /^storage:/i.test(s.trim());
-}
-
-export function parseImage(field: ImageField): ImageValue | null {
- if (!field) return null;
- if (typeof field === "object") return field;
- const value = field.trim();
- if (!value) return null;
- if (looksLikeGradient(value)) return { type: "gradient", value, positionY: 50 };
- if (looksLikeColor(value)) return { type: "color", value, positionY: 50 };
- if (looksLikeUrl(value)) return { type: "link", value, positionY: 50 };
- return { type: "color", value, positionY: 50 };
-}
-
-/** color / gradient — value is a CSS background, no URL resolution needed. */
-export function isCssImage(c: ImageValue): boolean {
- return c.type === "color" || c.type === "gradient";
-}
-
-/** texture / upload / link / unsplash — value is an image URL or FileRef. */
-export function isUrlImage(c: ImageValue): boolean {
- return !isCssImage(c);
-}
-
-/** Storage-backed (upload) values need the host to resolve their FileRef. */
-export function imageRef(c: ImageValue | null): string | null {
- return c && c.type === "upload" ? c.value : null;
-}
+export { parseImage, isCssImage, isUrlImage, imageRef } from "@/lib/contracts/image";
diff --git a/frontend/slices/image-picker/types.ts b/frontend/slices/image-picker/types.ts
index 1bb79714..3f511ee1 100644
--- a/frontend/slices/image-picker/types.ts
+++ b/frontend/slices/image-picker/types.ts
@@ -6,20 +6,8 @@
* server holds OS_UNSPLASH_ACCESS_KEY). Drops into any app — page cover,
* profile header, card hero, wallpaper, … */
-export type ImageSource = "color" | "gradient" | "texture" | "upload" | "link" | "unsplash";
-
-export interface ImageValue {
- type: ImageSource;
- /** color/gradient → CSS value; texture/upload/link/unsplash → URL or FileRef. */
- value: string;
- /** Vertical focal point 0–100 (default 50) — used when rendered as a banner. */
- positionY?: number;
- /** Per-type metadata. unsplash: { photographer, source, thumb, … }. */
- metadata?: Record<string, unknown>;
-}
-
-/** A stored image field — legacy raw string, an ImageValue object, or empty. */
-export type ImageField = string | ImageValue | null | undefined;
+export type { ImageSource, ImageValue, ImageField } from "@/lib/contracts/image";
+import type { ImageValue } from "@/lib/contracts/image";
export interface UnsplashPhoto {
id: string;
diff --git a/frontend/slices/os-shell/capabilities.ts b/frontend/slices/os-shell/capabilities.ts
index ddc6ed03..6d3794d1 100644
--- a/frontend/slices/os-shell/capabilities.ts
+++ b/frontend/slices/os-shell/capabilities.ts
@@ -2,7 +2,7 @@
import { useCallback, useSyncExternalStore } from "react";
import { effectiveServerTarget, selectServerTarget, useAppearance } from "@/lib/appearance";
-import { useOsApi } from "@/lib/os-api";
+import { useOsApi } from "@/features/appshell";
import { IS_DEMO } from "@/lib/demo";
import { faviconUrl, openQuicklink, useQuicklinks } from "@/lib/quicklinks";
import { openWindow, type ShellCapabilities, type SystemStats } from "@/features/appshell";
diff --git a/frontend/slices/os-shell/index.ts b/frontend/slices/os-shell/index.ts
index 90baa06f..37ee36d2 100644
--- a/frontend/slices/os-shell/index.ts
+++ b/frontend/slices/os-shell/index.ts
@@ -9,6 +9,7 @@ export {
} from "./shell.manifest";
export { topsideCapabilities } from "./capabilities";
export { A11yCommands } from "./a11y-commands";
+export { OsApiProvider } from "./os-api-provider";
// Built-in live wallpapers are MSO registrations into the generic AppShell
// registry. Importing the composition surface performs that registration once.
diff --git a/frontend/slices/os-shell/os-api-provider.tsx b/frontend/slices/os-shell/os-api-provider.tsx
new file mode 100644
index 00000000..8b401c0b
--- /dev/null
+++ b/frontend/slices/os-shell/os-api-provider.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import { useMemo, type ReactNode } from "react";
+import { HostApiProvider } from "@/features/appshell";
+import { useSession } from "@/features/auth";
+import { useAppearance } from "@/lib/appearance";
+import { IS_DEMO } from "@/lib/demo";
+import { HttpAdapter } from "@/lib/os-api/http-adapter";
+import { MockAdapter } from "@/lib/os-api/mock-adapter";
+
+/** MSO composition: choose mock/live adapter, then inject the generic host port. */
+export function OsApiProvider({ children }: { children: ReactNode }) {
+ const { tweaks } = useAppearance();
+ const { status, role } = useSession();
+ const mode = IS_DEMO || status !== "in" ? "mock" : tweaks.server.mode;
+ const api = useMemo(
+ () => (mode === "live" ? HttpAdapter({ url: "", role: role ?? "viewer" }) : MockAdapter()),
+ [mode, role],
+ );
+ return <HostApiProvider api={api}>{children}</HostApiProvider>;
+}
diff --git a/lib/appearance/store.tsx b/lib/appearance/store.tsx
index 9773e3cd..6bf738eb 100644
--- a/lib/appearance/store.tsx
+++ b/lib/appearance/store.tsx
@@ -9,7 +9,7 @@ import {
useState,
type ReactNode,
} from "react";
-import { parseImage, imageStyle, isCssImage, type ImageValue } from "@/features/image-picker";
+import { parseImage, imageStyle, isCssImage, type ImageValue } from "@/lib/contracts/image";
import { usePrefsSync } from "@/lib/prefs/use-prefs-sync";
import { TWEAK_DEFAULTS, type Tweaks, type ServerConfig } from "./types";
import { normalizeLiveWallpaper, normalizeWallpaper } from "./wallpapers";
diff --git a/lib/appearance/types.ts b/lib/appearance/types.ts
index 5f1198f6..4c0f17d4 100644
--- a/lib/appearance/types.ts
+++ b/lib/appearance/types.ts
@@ -1,5 +1,5 @@
import type { CSSProperties } from "react";
-import type { ImageValue } from "@/features/image-picker";
+import type { ImageValue } from "@/lib/contracts/image";
import type { LiveWallpaper, Wallpaper } from "./wallpapers";
export type Theme = "light" | "dark";
diff --git a/lib/contracts/image.ts b/lib/contracts/image.ts
new file mode 100644
index 00000000..730b306e
--- /dev/null
+++ b/lib/contracts/image.ts
@@ -0,0 +1,46 @@
+import type { CSSProperties } from "react";
+
+export type ImageSource = "color" | "gradient" | "texture" | "upload" | "link" | "unsplash";
+export interface ImageValue {
+ type: ImageSource;
+ value: string;
+ positionY?: number;
+ metadata?: Record<string, unknown>;
+}
+export type ImageField = string | ImageValue | null | undefined;
+
+const gradient = (value: string) => /^(linear|radial|conic)-gradient\(/i.test(value.trim());
+const color = (value: string) => {
+ const v = value.trim();
+ return /^#[0-9a-f]{3,8}$/i.test(v)
+ || /^(rgb|rgba|hsl|hsla)\(/i.test(v)
+ || /^(red|blue|green|black|white|gray|grey|yellow|orange|purple|pink|brown)$/i.test(v);
+};
+const url = (value: string) => /^https?:\/\//i.test(value.trim()) || /^storage:/i.test(value.trim());
+
+export function parseImage(field: ImageField): ImageValue | null {
+ if (!field) return null;
+ if (typeof field === "object") return field;
+ const value = field.trim();
+ if (!value) return null;
+ if (gradient(value)) return { type: "gradient", value, positionY: 50 };
+ if (color(value)) return { type: "color", value, positionY: 50 };
+ if (url(value)) return { type: "link", value, positionY: 50 };
+ return { type: "color", value, positionY: 50 };
+}
+export const isCssImage = (value: ImageValue) => value.type === "color" || value.type === "gradient";
+export const isUrlImage = (value: ImageValue) => !isCssImage(value);
+export const imageRef = (value: ImageValue | null) => value?.type === "upload" ? value.value : null;
+
+export function imageStyle(img: ImageValue, resolvedUrl?: string | null): CSSProperties {
+ const posY = img.positionY ?? 50;
+ if (isUrlImage(img)) {
+ const raw = resolvedUrl ?? img.value;
+ const safeUrl = raw.replace(/[\\"]/g, "\\$&").replace(/[\r\n]/g, "");
+ return {
+ backgroundImage: `url("${safeUrl}")`, backgroundSize: "cover",
+ backgroundPosition: `center ${posY}%`, backgroundRepeat: "no-repeat",
+ };
+ }
+ return { background: img.value };
+}
diff --git a/lib/contracts/os-api.ts b/lib/contracts/os-api.ts
new file mode 100644
index 00000000..9cc49805
--- /dev/null
+++ b/lib/contracts/os-api.ts
@@ -0,0 +1,81 @@
+/** Pure host I/O contract shared by server adapters and the brand-free AppShell. */
+export type Unsub = () => void;
+export type HostAccessRole = "viewer" | "operator" | "owner" | "demo";
+export type HostAccess = { role: HostAccessRole; canRead: boolean; canOperate: boolean; canOwn: boolean };
+export type SysStats = {
+ cpu: { pct: number; cores: number };
+ mem: { used: number; total: number };
+ disk: { used: number; total: number };
+ net?: { rx: number; tx: number };
+ uptime: number;
+};
+export type FsEntry = { name: string; kind: "dir" | "file"; size: number; ext?: string; mime?: string };
+export type FsRoot = { label: string; path: string };
+export type FsList = { path: string; entries: FsEntry[]; roots?: FsRoot[]; parent?: string | null };
+export type FsUsage = { used: number; total: number };
+export type FsHit = { name: string; path: string; kind: "dir" | "file" };
+export type UploadFile = { relPath: string; file: File };
+export type UploadResult = { written: number; failed?: string[] };
+export type UploadProgress = { loaded: number; total: number };
+export type ExecResult = { stdout: string; stderr: string; code: number };
+export type Process = { pid: number; name: string; status: string; cpu: number; mem: number };
+export type ServiceScope = "system" | "user";
+export type ServiceAction = "start" | "stop" | "restart";
+export type SystemService = {
+ unit: string; scope: ServiceScope; load: string; active: string; sub: string;
+ description: string; controllable: boolean;
+};
+export type ServiceInventory = {
+ services: SystemService[]; diagnostics: string[]; truncated: boolean;
+ controlAllowlistConfigured: boolean; generatedAt: string;
+};
+export type ServiceLogs = {
+ unit: string; scope: ServiceScope; entries: string[]; available: boolean; diagnostic?: string;
+};
+export type PackageUpdate = { name: string; current?: string; candidate: string; architecture?: string };
+export type PackageUpdateSummary = {
+ manager: "apt" | "dnf" | "yum" | "pacman" | "zypper" | null;
+ available: boolean; updates: PackageUpdate[]; truncated: boolean; checkedAt: string;
+ source: "local-cache"; diagnostic?: string;
+};
+export type AppManifest = { name: string; slug: string; runtime: string; entry: string };
+export type ManagedAppSummary = { id: string; name: string; installed: boolean; running: boolean };
+export type ManagedAppAction = "start" | "stop" | "restart" | "backup";
+export type BrowserState = { installed: boolean; running: boolean; autostart: boolean };
+
+export type OsApi = {
+ mode: "mock" | "live";
+ access: HostAccess;
+ auth: {
+ token: (u: string, p: string) => Promise<{ token: string; expires_at: number }>;
+ me: () => Promise<{ user: { name: string; id: string } }>;
+ };
+ fs: {
+ list: (path: string) => Promise<FsList>;
+ read: (path: string) => Promise<string>;
+ write: (path: string, content: string) => Promise<{ ok: boolean }>;
+ mkdir: (path: string) => Promise<{ kind: "dir" }>;
+ remove: (path: string) => Promise<{ ok: boolean }>;
+ move: (from: string, to: string) => Promise<{ ok: boolean }>;
+ copy: (from: string, to: string) => Promise<{ ok: boolean }>;
+ upload: (dest: string, files: UploadFile[], onProgress?: (p: UploadProgress) => void) => Promise<UploadResult>;
+ search: (query: string) => Promise<FsHit[]>;
+ usage: () => Promise<FsUsage>;
+ };
+ exec: { run: (cmd: string, cwd?: string) => Promise<ExecResult> };
+ sys: {
+ stats: () => Promise<SysStats>;
+ statsStream: (onEvent: (s: Partial<SysStats>) => void) => Unsub;
+ processes: () => Promise<Process[]>;
+ services: () => Promise<ServiceInventory>;
+ serviceLogs: (scope: ServiceScope, unit: string, limit?: number) => Promise<ServiceLogs>;
+ servicePower: (scope: ServiceScope, unit: string, action: ServiceAction) => Promise<SystemService>;
+ packageUpdates: () => Promise<PackageUpdateSummary>;
+ };
+ apps: {
+ list: () => Promise<ManagedAppSummary[]>;
+ logs: (id: string) => Promise<{ available: boolean; entries: string[] }>;
+ power: (id: string, action: ManagedAppAction) => Promise<ManagedAppSummary>;
+ };
+ browser: { status: () => Promise<BrowserState>; power: (on: boolean) => Promise<BrowserState> };
+};
diff --git a/lib/os-api/index.ts b/lib/os-api/index.ts
new file mode 100644
index 00000000..5e67cf6a
--- /dev/null
+++ b/lib/os-api/index.ts
@@ -0,0 +1,7 @@
+// Pure MSO host adapter surface. React/session composition lives in os-shell.
+export { rawUrl, zipUrl } from "./urls";
+export type {
+ OsApi, SysStats, FsEntry, FsList, FsRoot, FsUsage, FsHit, UploadFile, UploadResult,
+ UploadProgress, ExecResult, Process, HostAccess, HostAccessRole, ServiceScope, ServiceAction,
+ SystemService, ServiceInventory, ServiceLogs, PackageUpdate, PackageUpdateSummary,
+} from "./types";
diff --git a/lib/os-api/index.tsx b/lib/os-api/index.tsx
deleted file mode 100644
index 2bc519d8..00000000
--- a/lib/os-api/index.tsx
+++ /dev/null
@@ -1,73 +0,0 @@
-"use client";
-
-import { useMemo, type ReactNode } from "react";
-import { HostApiProvider } from "@/features/appshell";
-import { useAppearance } from "@/lib/appearance";
-import { useSession } from "@/features/auth";
-import { IS_DEMO } from "@/lib/demo";
-import { MockAdapter } from "./mock-adapter";
-import { HttpAdapter } from "./http-adapter";
-import type { OsApi } from "./types";
-
-// Same-origin URL for raw file bytes (image/video/audio/pdf). Demo media lives
-// in /demo-media/* as static public assets (served with no host/auth — works in
-// the demo). Everything else streams from the host via the cookie-authed raw
-// route (works as an <img>/<video>/<audio> src directly, no token plumbing).
-export function rawUrl(path: string): string {
- if (path.startsWith("/demo-media/")) return path;
- return "/api/v1/fs/raw?path=" + encodeURIComponent(path);
-}
-
-// Same-origin URL for a streamed zip of `names` (basenames) inside `base` (the
-// current dir). Cookie-authed via the GET route → a hidden <a download> streams
-// it through the browser's download manager. No demo fallback (no host).
-export function zipUrl(
- base: string,
- names: string[],
- filename: string,
- exclude: string[] = [],
-): string {
- const p = new URLSearchParams({ base, name: filename });
- for (const n of names) p.append("n", n);
- for (const x of exclude) p.append("x", x);
- return "/api/v1/fs/zip?" + p.toString();
-}
-
-// mso adapter injection: pick mock (default) ↔ live, then hand the concrete
-// api to the framework's HostApiProvider (which owns the context useOsApi reads).
-// Live talks to SAME-ORIGIN `/api/v1` route handlers (base url ""); the signed
-// session cookie rides along, the routes verify it, then proxy to the host agent
-// with the gateway secret (server-side only). Demo never touches the host.
-export function OsApiProvider({ children }: { children: ReactNode }) {
- const { tweaks } = useAppearance();
- const { status, role } = useSession();
- // Live only when signed in. A public/signed-out visitor stays on mock (the
- // /api host routes would 401 them anyway — this just avoids the error spray
- // and gives a clean mock experience); live activates the moment the owner
- // signs in (Settings → Server), since the shared session flips `status`.
- const mode = IS_DEMO || status !== "in" ? "mock" : tweaks.server.mode;
- const api = useMemo(
- () => (mode === "live" ? HttpAdapter({ url: "", role: role ?? "viewer" }) : MockAdapter()),
- [mode, role],
- );
- return <HostApiProvider api={api}>{children}</HostApiProvider>;
-}
-
-// The port hook + types live in the framework now; re-export so existing
-// `@/lib/os-api` importers keep resolving during the migration to the barrel.
-export { useOsApi } from "@/features/appshell";
-export type {
- OsApi,
- SysStats,
- FsEntry,
- FsList,
- FsRoot,
- FsUsage,
- FsHit,
- UploadFile,
- UploadResult,
- ExecResult,
- Process,
- HostAccess,
- HostAccessRole,
-} from "./types";
diff --git a/lib/os-api/types.ts b/lib/os-api/types.ts
index 25fb1295..a189e1b0 100644
--- a/lib/os-api/types.ts
+++ b/lib/os-api/types.ts
@@ -1,32 +1,8 @@
-// os-rr Cloud API contract — the single boundary between the OS and the VPS.
-// The OsApi PORT + host data types now live in the appshell framework
-// (appshell/lib/host-api) so app slices import them via a legal alias; this
-// module keeps the mso CONFIG + the concrete adapters (http/mock) that
-// satisfy the port. MockAdapter simulates in-browser; HttpAdapter calls the agent.
+// Concrete MSO adapters implement the transport-neutral host I/O contract.
export const API_VERSION = "v1";
-
export type {
- Unsub,
- HostAccessRole,
- HostAccess,
- SysStats,
- FsEntry,
- FsRoot,
- FsList,
- FsUsage,
- FsHit,
- UploadFile,
- UploadResult,
- UploadProgress,
- ExecResult,
- Process,
- ServiceScope,
- ServiceAction,
- SystemService,
- ServiceInventory,
- ServiceLogs,
- PackageUpdate,
- PackageUpdateSummary,
- AppManifest,
- OsApi,
-} from "@/features/appshell";
+ Unsub, HostAccessRole, HostAccess, SysStats, FsEntry, FsRoot, FsList, FsUsage, FsHit,
+ UploadFile, UploadResult, UploadProgress, ExecResult, Process, ServiceScope, ServiceAction,
+ SystemService, ServiceInventory, ServiceLogs, PackageUpdate, PackageUpdateSummary, AppManifest,
+ ManagedAppSummary, ManagedAppAction, BrowserState, OsApi,
+} from "@/lib/contracts/os-api";
diff --git a/lib/os-api/urls.ts b/lib/os-api/urls.ts
new file mode 100644
index 00000000..3a61719c
--- /dev/null
+++ b/lib/os-api/urls.ts
@@ -0,0 +1,11 @@
+export function rawUrl(path: string): string {
+ if (path.startsWith("/demo-media/")) return path;
+ return "/api/v1/fs/raw?path=" + encodeURIComponent(path);
+}
+
+export function zipUrl(base: string, names: string[], filename: string, exclude: string[] = []): string {
+ const params = new URLSearchParams({ base, name: filename });
+ for (const name of names) params.append("n", name);
+ for (const value of exclude) params.append("x", value);
+ return "/api/v1/fs/zip?" + params.toString();
+}