@orbit-work/oem-dev-host 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@orbit-work/oem-dev-host",
+  "version": "0.1.0",
+  "description": "Live OEM bridge for full Desktop, isolated-profile sandbox, and Slot workbench modes.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "orbit-oem-dev-host": "./src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/compiler.mjs"
+  },
+  "files": [
+    "src/cli.mjs",
+    "src/compiler.mjs",
+    "src/server.mjs"
+  ],
+  "dependencies": {
+    "@orbit-work/oem-sdk": "0.1.0",
+    "@orbit-work/ui": "0.1.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.6.3",
+    "vite": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/*.test.mjs"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { realpathSync } from "node:fs"
+import { access } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { startDevelopmentServer } from "./server.mjs"
+
+export function parseArgs(argv, env = process.env) {
+  const result = { project: process.cwd(), host: env.ORBIT_OEM_DEV_HOST_EXECUTABLE, mode: "full" }
+  let selectedMode
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === "--help" || arg === "-h") return { help: true }
+    if (arg === "--full" || arg === "--sandbox" || arg === "--workbench") {
+      const mode = arg.slice(2)
+      if (selectedMode && selectedMode !== mode) throw new Error("only one Dev Host mode can be selected")
+      selectedMode = mode
+      result.mode = mode
+      continue
+    }
+    if (arg !== "--project" && arg !== "--host") throw new Error(`unknown option: ${arg}`)
+    const value = argv[(index += 1)]
+    if (!value) throw new Error(`${arg} requires a value`)
+    result[arg.slice(2)] = value
+  }
+  return result
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(
+      "Usage: orbit-oem-dev-host [--project <directory>] [--host <compiled-dev-host-executable>] [--full|--sandbox|--workbench]",
+    )
+    console.log("  --full     Launch the complete Orbitwork application with live OEM composition (default)")
+    console.log("  --sandbox  Launch the complete Desktop and Orbit APIs in an isolated local profile")
+    console.log("  --workbench Launch the lightweight Slot contract workbench")
+    return
+  }
+  if (!args.host) {
+    throw new Error("Install the compiled Orbitwork OEM Dev Host, then set ORBIT_OEM_DEV_HOST_EXECUTABLE or pass --host")
+  }
+  const executable = path.resolve(args.host)
+  await access(executable)
+  const server = await startDevelopmentServer(path.resolve(args.project), { launch: executable, mode: args.mode })
+  console.log(
+    `[oem-dev-host] ${server.mode} mode connected at ${server.origin}; successful saves reload Desktop, failed builds keep the current renderer`,
+  )
+  const stop = async () => {
+    await server.close()
+    process.exit(0)
+  }
+  process.once("SIGINT", stop)
+  process.once("SIGTERM", stop)
+  server.child?.once("exit", (code) => {
+    void server.close().finally(() => process.exit(code ?? 0))
+  })
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch((error) => {
+    console.error(error.stack ?? error.message)
+    process.exitCode = 1
+  })
+}

package/src/compiler.mjs

@@ -0,0 +1,178 @@
+import { readFile, realpath } from "node:fs/promises"
+import path from "node:path"
+import { auditBrandPackage } from "@orbit-work/oem-sdk/audit"
+import react from "@vitejs/plugin-react"
+import { OEM_VITE_CONFIG } from "@orbit-work/oem-sdk/vite"
+import { build } from "vite"
+import ts from "typescript"
+
+const EXTERNALS = new Set([
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "@orbit-work/ui",
+  "@orbit-work/ui/appearance",
+  "@orbit-work/ui/slot/core",
+  "@orbit-work/ui/slot/react",
+  "@orbit-work/oem-sdk",
+  "@orbit-work/oem-sdk/runtime",
+])
+function exactDevOrigin(value, label) {
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error(`${label} must be an exact HTTP(S) origin`)
+  }
+  if (!new Set(["http:", "https:"]).has(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error(`${label} must be an exact HTTP(S) origin without credentials, path, query, or fragment`)
+  }
+  if (url.protocol === "http:" && !new Set(["localhost", "127.0.0.1", "::1"]).has(url.hostname)) {
+    throw new Error(`${label} may use HTTP only for loopback`)
+  }
+  return url.origin
+}
+
+export function parseDevelopmentConfig(value) {
+  if (value === undefined) return { network: { allowedOrigins: [] } }
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => key !== "network")) {
+    throw new Error("orbit-dev.local.json supports only the network object")
+  }
+  if (!value.network || typeof value.network !== "object" || Array.isArray(value.network)) {
+    throw new Error("orbit-dev.local.json network must be an object")
+  }
+  if (Object.keys(value.network).some((key) => key !== "allowedOrigins") || !Array.isArray(value.network.allowedOrigins)) {
+    throw new Error("orbit-dev.local.json network.allowedOrigins must be an array")
+  }
+  const allowedOrigins = value.network.allowedOrigins.map((origin, index) => exactDevOrigin(origin, `network.allowedOrigins[${index}]`))
+  if (new Set(allowedOrigins).size !== allowedOrigins.length) throw new Error("development origins must not contain duplicates")
+  return { network: { allowedOrigins } }
+}
+
+async function readJsonIfPresent(file) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"))
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined
+    throw error
+  }
+}
+
+function moduleShim(specifier, namespace) {
+  const names = Object.keys(namespace).filter((name) => name !== "default" && /^[A-Za-z_$][\w$]*$/.test(name))
+  const lines = [`const namespace = globalThis.__ORBIT_OEM_DEV_EXTERNALS__[${JSON.stringify(specifier)}];`]
+  if ("default" in namespace) lines.push("export default namespace.default;")
+  for (const name of names) lines.push(`export const ${name} = namespace[${JSON.stringify(name)}];`)
+  return lines.join("\n")
+}
+
+async function externalPlugin() {
+  const shims = new Map()
+  for (const specifier of EXTERNALS) {
+    const namespace = await import(specifier)
+    shims.set(specifier, moduleShim(specifier, namespace))
+  }
+  return {
+    name: "orbit-oem-dev-host-singletons",
+    enforce: "pre",
+    resolveId(id) {
+      return EXTERNALS.has(id) ? `\0orbit-host:${id}` : null
+    },
+    load(id) {
+      return id.startsWith("\0orbit-host:") ? shims.get(id.slice("\0orbit-host:".length)) : null
+    },
+  }
+}
+
+function dataUrl(file, bytes) {
+  const extension = path.extname(file).toLowerCase()
+  const mime = extension === ".svg" ? "image/svg+xml" : extension === ".webp" ? "image/webp" : "image/png"
+  return `data:${mime};base64,${bytes.toString("base64")}`
+}
+
+export function immutableDevelopmentIdentity(manifest) {
+  return JSON.stringify({ identity: manifest.identity, appIcon: manifest.assets.appIcon, tray: manifest.assets.tray ?? null })
+}
+
+function typecheckProject(root) {
+  const configFile = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json")
+  if (!configFile) throw new Error("OEM Dev Host requires a tsconfig.json")
+  const loaded = ts.readConfigFile(configFile, ts.sys.readFile)
+  if (loaded.error) throw new Error(ts.flattenDiagnosticMessageText(loaded.error.messageText, "\n"))
+  const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, root)
+  const program = ts.createProgram(parsed.fileNames, { ...parsed.options, noEmit: true })
+  const diagnostic = ts.getPreEmitDiagnostics(program)[0]
+  if (!diagnostic) return
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")
+  if (!diagnostic.file || diagnostic.start === undefined) throw new Error(message)
+  const position = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+  const error = new Error(`${diagnostic.file.fileName}:${position.line + 1}:${position.character + 1}: ${message}`)
+  error.name = "OemTypecheckError"
+  throw error
+}
+
+export async function compileOemDevelopmentProject(projectRoot, { expectedIdentity } = {}) {
+  const root = await realpath(path.resolve(projectRoot))
+  const manifestFile = path.join(root, "orbit-brand.json")
+  const development = parseDevelopmentConfig(await readJsonIfPresent(path.join(root, "orbit-dev.local.json")))
+  const audit = await auditBrandPackage(manifestFile, { developmentAllowedOrigins: development.network.allowedOrigins })
+  typecheckProject(root)
+  const identity = immutableDevelopmentIdentity(audit.manifest)
+  if (expectedIdentity && identity !== expectedIdentity) {
+    throw new Error("Dev Host identity, app icon, or tray changed; rebuild and reinstall the dedicated Dev Host")
+  }
+  const locales = Object.fromEntries(
+    await Promise.all(
+      Object.entries(audit.manifest.locales ?? {}).map(async ([locale, relative]) => [
+        locale,
+        JSON.parse(await readFile(path.resolve(root, relative), "utf8")),
+      ]),
+    ),
+  )
+  const logoFile = path.resolve(root, audit.manifest.assets.logo)
+  const logo = dataUrl(logoFile, await readFile(logoFile))
+  let javascript = ""
+  let css = ""
+  if (audit.manifest.entry) {
+    const result = await build({
+      configFile: false,
+      root,
+      plugins: [await externalPlugin(), react()],
+      resolve: { dedupe: [...OEM_VITE_CONFIG.resolve.dedupe] },
+      css: { modules: { ...OEM_VITE_CONFIG.css.modules } },
+      build: {
+        ...OEM_VITE_CONFIG.build,
+        write: false,
+        minify: false,
+        sourcemap: "inline",
+        lib: {
+          entry: path.resolve(root, audit.manifest.entry),
+          name: "OrbitOemDevelopmentEntry",
+          formats: ["iife"],
+          fileName: () => "bundle.js",
+        },
+        rollupOptions: {
+          output: { footer: "globalThis.__ORBIT_OEM_DEV_ACCEPT__?.(OrbitOemDevelopmentEntry.default);" },
+        },
+      },
+    })
+    const output = Array.isArray(result) ? result.flatMap((item) => item.output) : result.output
+    javascript = output.find((item) => item.type === "chunk" && item.fileName.endsWith(".js"))?.code ?? ""
+    const cssAsset = output.find((item) => item.type === "asset" && item.fileName.endsWith(".css"))
+    css = cssAsset ? String(cssAsset.source) : ""
+  }
+  return {
+    identity,
+    snapshot: { manifest: audit.manifest, locales, logo, development },
+    javascript,
+    css,
+  }
+}
+
+export function formatBuildError(error) {
+  const diagnostic = error?.errors?.[0]
+  if (!diagnostic) return error instanceof Error ? error.message : String(error)
+  const location = diagnostic.location
+  return `${location?.file ?? "OEM build"}${location ? `:${location.line}:${location.column}` : ""}: ${diagnostic.text}`
+}

package/src/server.mjs

@@ -0,0 +1,176 @@
+import { spawn } from "node:child_process"
+import { createHash } from "node:crypto"
+import { watch } from "node:fs"
+import http from "node:http"
+import path from "node:path"
+import { compileOemDevelopmentProject, formatBuildError } from "./compiler.mjs"
+
+export const OEM_DEV_HOST = "127.0.0.1"
+export const OEM_DEV_HOST_PORT = 43127
+export const OEM_DEV_HOST_RENDERER_ORIGIN = "app://orbit"
+
+function json(response, status, value) {
+  response.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" })
+  response.end(JSON.stringify(value))
+}
+
+const DEV_HOST_MODES = new Set(["full", "sandbox", "workbench"])
+const WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+async function startFixtureSidecarStub() {
+  const sockets = new Set()
+  const server = http.createServer()
+  server.on("upgrade", (request, socket) => {
+    const key = String(request.headers["sec-websocket-key"] ?? "")
+    if (!key) {
+      socket.destroy()
+      return
+    }
+    const accept = createHash("sha1").update(`${key}${WEBSOCKET_GUID}`).digest("base64")
+    socket.write(
+      [
+        "HTTP/1.1 101 Switching Protocols",
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        `Sec-WebSocket-Accept: ${accept}`,
+        "",
+        "",
+      ].join("\r\n"),
+    )
+    sockets.add(socket)
+    socket.on("close", () => sockets.delete(socket))
+    socket.on("error", () => sockets.delete(socket))
+  })
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, OEM_DEV_HOST, resolve)
+  })
+  const address = server.address()
+  if (!address || typeof address === "string") throw new Error("fixture Sidecar stub did not bind a TCP port")
+  return {
+    url: `ws://${OEM_DEV_HOST}:${address.port}`,
+    close: async () => {
+      for (const socket of sockets) socket.destroy()
+      await new Promise((resolve) => server.close(resolve))
+    },
+  }
+}
+
+export function developmentHostEnvironment(mode, env = process.env) {
+  if (!DEV_HOST_MODES.has(mode)) throw new Error(`unsupported OEM Dev Host mode: ${mode}`)
+  return { ...env, ORBIT_OEM_DEV_HOST: "1", ORBIT_OEM_DEV_HOST_MODE: mode }
+}
+
+export async function startDevelopmentServer(
+  projectRoot,
+  { port = OEM_DEV_HOST_PORT, launch, mode = "full", fixtureRuntime = false } = {},
+) {
+  if (!DEV_HOST_MODES.has(mode)) throw new Error(`unsupported OEM Dev Host mode: ${mode}`)
+  let current = null
+  let identity = null
+  let revision = 0
+  let rebuilding = false
+  let rebuildAgain = false
+  const clients = new Set()
+  const notify = (event, data) => {
+    for (const response of clients) response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+  }
+  const rebuild = async () => {
+    if (rebuilding) {
+      rebuildAgain = true
+      return
+    }
+    rebuilding = true
+    try {
+      const next = await compileOemDevelopmentProject(projectRoot, { expectedIdentity: identity })
+      identity ??= next.identity
+      current = next
+      revision += 1
+      notify("ready", { revision })
+      console.log(`[oem-dev-host] build ${revision} ready`)
+    } catch (error) {
+      const message = formatBuildError(error)
+      notify("error", { message })
+      console.error(`[oem-dev-host] ${message}`)
+    } finally {
+      rebuilding = false
+      if (rebuildAgain) {
+        rebuildAgain = false
+        void rebuild()
+      }
+    }
+  }
+  await rebuild()
+  if (!current) throw new Error("initial OEM build failed; fix the reported error before starting Dev Host")
+
+  const server = http.createServer((request, response) => {
+    const url = new URL(request.url ?? "/", `http://${OEM_DEV_HOST}:${port}`)
+    const requestOrigin = request.headers.origin
+    if (requestOrigin && requestOrigin !== OEM_DEV_HOST_RENDERER_ORIGIN) {
+      return json(response, 403, { error: "browser origin is not allowed" })
+    }
+    response.setHeader("Access-Control-Allow-Origin", OEM_DEV_HOST_RENDERER_ORIGIN)
+    response.setHeader("Vary", "Origin")
+    if (url.pathname === "/status") return json(response, 200, { revision, snapshot: current.snapshot })
+    if (url.pathname === "/bundle.js") {
+      response.writeHead(200, { "Content-Type": "text/javascript; charset=utf-8", "Cache-Control": "no-store" })
+      return response.end(current.javascript)
+    }
+    if (url.pathname === "/bundle.css") {
+      response.writeHead(200, { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-store" })
+      return response.end(current.css)
+    }
+    if (url.pathname === "/events") {
+      response.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-store",
+        Connection: "keep-alive",
+        "Access-Control-Allow-Origin": OEM_DEV_HOST_RENDERER_ORIGIN,
+        Vary: "Origin",
+      })
+      response.write(`event: connected\ndata: ${JSON.stringify({ revision })}\n\n`)
+      clients.add(response)
+      request.on("close", () => clients.delete(response))
+      return
+    }
+    json(response, 404, { error: "not found" })
+  })
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(port, OEM_DEV_HOST, resolve)
+  })
+
+  const fixtureSidecar = fixtureRuntime ? await startFixtureSidecarStub() : null
+
+  let timer
+  const watcher = watch(path.resolve(projectRoot), { recursive: true }, (_event, filename) => {
+    const relative = String(filename ?? "")
+    if (!relative || /(?:^|[\\/])(?:node_modules|dist|preview-dist)(?:[\\/]|$)/.test(relative)) return
+    clearTimeout(timer)
+    timer = setTimeout(() => void rebuild(), 90)
+  })
+  const child = launch
+    ? spawn(launch, [], {
+        stdio: "inherit",
+        env: developmentHostEnvironment(mode, {
+          ...process.env,
+          ...(fixtureSidecar ? { ORBIT_SIDECAR_WS_URL: fixtureSidecar.url } : {}),
+        }),
+      })
+    : null
+  const close = async () => {
+    clearTimeout(timer)
+    watcher.close()
+    for (const client of clients) client.end()
+    child?.kill()
+    await new Promise((resolve) => server.close(resolve))
+    await fixtureSidecar?.close()
+  }
+  return {
+    origin: `http://${OEM_DEV_HOST}:${port}`,
+    mode,
+    fixtureSidecarUrl: fixtureSidecar?.url,
+    close,
+    child,
+  }
+}