@mohou/host 1.0.20

package/src/host/config.ts

@@ -0,0 +1,239 @@
+import { readFile, writeFile } from 'node:fs/promises'
+
+import type { RuntimeProvider } from '@mohou/runtime-provider'
+
+import { ConfigError } from './codes.ts'
+import { hostConfigPath } from './layout.ts'
+import { allocateHostPort } from './port.ts'
+
+/** Appearance. A stored preference, not a resolved OS value. */
+export const hostThemes = ['system', 'light', 'dark'] as const
+
+export type HostTheme = (typeof hostThemes)[number]
+
+export interface HostPolicy {
+  runtimeRoot: string
+  hostPort: number
+  theme: HostTheme
+  palette: string
+  locale: string
+  chatLanguage: string
+  llm: { provider: string; model: string } | null
+  runtimeProvider: {
+    id: string
+    config?: { provider?: string; model?: string; options?: Record<string, string> }
+  }
+  /** Absent, or `default`, means the builtin library. Not required to boot. */
+  defaultWorkbenchId?: string
+}
+
+/** Seed numbers and names. Host policy, not a locked product value. */
+export interface HostSeed {
+  hostPort: number
+  theme: HostTheme
+  palette: string
+  locale: string
+}
+
+/** Port bound. Host policy, not a locked product value. */
+export interface PortBound {
+  min: number
+  max: number
+}
+
+export const DEFAULT_PORT_BOUND: PortBound = { min: 1024, max: 65535 }
+
+const PUBLIC_KEYS = ['runtimeRoot', 'hostPort', 'theme', 'palette', 'locale', 'chatLanguage', 'llm', 'runtimeProvider'] as const
+const OPTIONAL_KEYS = ['defaultWorkbenchId'] as const
+
+/**
+ * Read `host.json`. A missing file writes a complete seed. A present bad file throws and is left as it was.
+ * @param runtimeRoot - directory that contains the file
+ * @param seed - values used only when the file is absent
+ * @param ports - accepted host port range
+ */
+export async function resolveHostConfig(runtimeRoot: string, seed: HostSeed, ports: PortBound = DEFAULT_PORT_BOUND): Promise<HostPolicy> {
+  const file = hostConfigPath(runtimeRoot)
+  const text = await readFile(file, 'utf8').catch(() => undefined)
+  if (text === undefined) {
+    // First boot only: pick a free port before anything external can pin the MCP URL.
+    const hostPort = await allocateHostPort(seed.hostPort, ports)
+    const created = seedPolicy(runtimeRoot, { ...seed, hostPort })
+    await writeFile(file, `${JSON.stringify(created, null, 2)}\n`)
+    return created
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text) as unknown
+  } catch (error) {
+    throw new ConfigError('config-invalid', 'host config is not JSON', { cause: error })
+  }
+  return admitPolicy(parsed, runtimeRoot, ports)
+}
+
+/**
+ * Write the public fields. `locale` and `chatLanguage` must be the same value.
+ * A new `runtimeProvider.id` does not switch the live brain.
+ * @param runtimeRoot - directory that contains the file
+ * @param current - the resolved file
+ * @param raw - untrusted form body
+ * @param ports - accepted host port range
+ */
+export async function writeHostPolicy(
+  runtimeRoot: string,
+  current: HostPolicy,
+  raw: unknown,
+  ports: PortBound = DEFAULT_PORT_BOUND,
+): Promise<{ policy: HostPolicy; restartRequired: boolean }> {
+  const next = admitPolicy(raw, runtimeRoot, ports)
+  if (next.locale !== next.chatLanguage) {
+    throw new ConfigError('config-invalid', 'locale and chatLanguage must be the same value')
+  }
+  await writeFile(hostConfigPath(runtimeRoot), `${JSON.stringify(next, null, 2)}\n`)
+  return {
+    policy: next,
+    restartRequired: next.hostPort !== current.hostPort || next.runtimeProvider.id !== current.runtimeProvider.id,
+  }
+}
+
+/**
+ * Probe one registered provider. Does not write config and does not switch the live brain.
+ * @param id - provider id from the form
+ * @param providers - brains Shell registered
+ * @param liveId - the provider Host is running, if any
+ */
+export async function probeBrain(
+  id: string,
+  providers: readonly RuntimeProvider[],
+  liveId?: string,
+): Promise<{ healthy: true } | { healthy: false; code: string; message: string }> {
+  const provider = providers.find(item => item.id === id)
+  if (provider === undefined) {
+    return { healthy: false, code: 'provider-missing', message: `no runtime provider: ${id}` }
+  }
+  if (id === liveId) {
+    const healthy = provider.healthy()
+    if (!healthy) {
+      return { healthy: false, code: 'provider-unhealthy', message: `runtime provider is not healthy: ${id}` }
+    }
+    return { healthy: true }
+  }
+  try {
+    provider.configure?.({})
+    await provider.start()
+    const healthy = provider.healthy()
+    await provider.stop()
+    return healthy
+      ? { healthy: true }
+      : { healthy: false, code: 'provider-unhealthy', message: `runtime provider is not healthy: ${id}` }
+  } catch (error) {
+    await provider.stop().catch(() => undefined)
+    const message = error instanceof Error ? error.message : 'runtime provider probe failed'
+    const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+      ? error.code
+      : 'provider-unhealthy'
+    return { healthy: false, code, message }
+  }
+}
+
+function seedPolicy(runtimeRoot: string, seed: HostSeed): HostPolicy {
+  return {
+    runtimeRoot,
+    hostPort: seed.hostPort,
+    theme: seed.theme,
+    palette: seed.palette,
+    locale: seed.locale,
+    chatLanguage: seed.locale,
+    llm: null,
+    runtimeProvider: { id: 'echo' },
+  }
+}
+
+function admitPolicy(raw: unknown, runtimeRoot: string, ports: PortBound): HostPolicy {
+  if (!isRecord(raw)) throw new ConfigError('config-invalid', 'host config must be an object')
+  for (const key of Object.keys(raw)) {
+    if (!(PUBLIC_KEYS as readonly string[]).includes(key) && !(OPTIONAL_KEYS as readonly string[]).includes(key)) {
+      throw new ConfigError('config-invalid', `host config field is not public: ${key}`)
+    }
+  }
+  for (const key of PUBLIC_KEYS) {
+    if (!(key in raw)) throw new ConfigError('config-missing', `host config missing ${key}`)
+  }
+  if (raw.runtimeRoot !== runtimeRoot) {
+    throw new ConfigError('config-invalid', 'host config runtimeRoot does not match the runtime root')
+  }
+  const hostPort = raw.hostPort
+  if (typeof hostPort !== 'number' || !Number.isInteger(hostPort) || hostPort < ports.min || hostPort > ports.max) {
+    throw new ConfigError('config-invalid', 'host config hostPort is invalid')
+  }
+  const theme = raw.theme
+  if (typeof theme !== 'string' || !(hostThemes as readonly string[]).includes(theme)) {
+    throw new ConfigError('config-invalid', 'host config theme is invalid')
+  }
+  const palette = requiredText(raw.palette, 'palette')
+  const locale = requiredText(raw.locale, 'locale')
+  const chatLanguage = requiredText(raw.chatLanguage, 'chatLanguage')
+  return {
+    runtimeRoot,
+    hostPort,
+    theme: theme as HostTheme,
+    palette,
+    locale,
+    chatLanguage,
+    llm: admitLlm(raw.llm),
+    runtimeProvider: admitProvider(raw.runtimeProvider),
+    ...admitWorkbench(raw.defaultWorkbenchId),
+  }
+}
+
+function admitWorkbench(value: unknown): { defaultWorkbenchId: string } | Record<string, never> {
+  if (value === undefined || value === 'default') return {}
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new ConfigError('config-invalid', 'host config defaultWorkbenchId is invalid')
+  }
+  return { defaultWorkbenchId: value }
+}
+
+function admitLlm(value: unknown): HostPolicy['llm'] {
+  if (value === null) return null
+  if (!isRecord(value)) throw new ConfigError('config-invalid', 'host config llm is invalid')
+  return { provider: requiredText(value.provider, 'llm.provider'), model: requiredText(value.model, 'llm.model') }
+}
+
+function admitProvider(value: unknown): HostPolicy['runtimeProvider'] {
+  if (!isRecord(value)) throw new ConfigError('config-invalid', 'host config runtimeProvider is invalid')
+  const id = requiredText(value.id, 'runtimeProvider.id')
+  if (value.config === undefined) return { id }
+  if (!isRecord(value.config)) throw new ConfigError('config-invalid', 'host config runtimeProvider.config is invalid')
+  const config = value.config
+  if (config.provider !== undefined && typeof config.provider !== 'string') {
+    throw new ConfigError('config-invalid', 'host config runtimeProvider.config.provider is invalid')
+  }
+  if (config.model !== undefined && typeof config.model !== 'string') {
+    throw new ConfigError('config-invalid', 'host config runtimeProvider.config.model is invalid')
+  }
+  if (config.options !== undefined && !isStringRecord(config.options)) {
+    throw new ConfigError('config-invalid', 'host config runtimeProvider.config.options is invalid')
+  }
+  return {
+    id,
+    config: {
+      ...typeof config.provider === 'string' ? { provider: config.provider } : {},
+      ...typeof config.model === 'string' ? { model: config.model } : {},
+      ...isStringRecord(config.options) ? { options: config.options } : {},
+    },
+  }
+}
+
+function requiredText(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0) throw new ConfigError('config-invalid', `host config ${field} is invalid`)
+  return value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) && Object.values(value).every(item => typeof item === 'string')
+}

package/src/host/heat.ts

@@ -0,0 +1,35 @@
+/** One recorded open. The caller has already read it. */
+export interface HeatSample {
+  readonly appId: string
+  readonly openedAt: string
+}
+
+/** Observed use for one app. Absent means no sample, not zero. */
+export interface HeatValue {
+  readonly lastOpenedAt: string
+  readonly openCount: number
+}
+
+/** Heat keyed by app id. An empty map means the caller passed no samples. */
+export type HeatSnapshot = Readonly<Record<string, HeatValue>>
+
+/**
+ * Fold open samples into heat. The latest `openedAt` string wins.
+ * This function does not read the clock or the disk.
+ * @param samples - opens the caller already read
+ */
+export function heat(samples: readonly HeatSample[]): HeatSnapshot {
+  const snapshot: Record<string, HeatValue> = {}
+  for (const sample of samples) {
+    const previous = snapshot[sample.appId]
+    if (previous === undefined) {
+      snapshot[sample.appId] = { lastOpenedAt: sample.openedAt, openCount: 1 }
+      continue
+    }
+    snapshot[sample.appId] = {
+      lastOpenedAt: sample.openedAt > previous.lastOpenedAt ? sample.openedAt : previous.lastOpenedAt,
+      openCount: previous.openCount + 1,
+    }
+  }
+  return snapshot
+}

package/src/host/layout.ts

@@ -0,0 +1,81 @@
+import path from 'node:path'
+
+/** Names under the runtime root. Spell them here, not at each call site. */
+export const hostLayout = {
+  config: 'host.json',
+  apps: 'apps',
+  trash: 'trash',
+  trashSep: '_',
+  authoringToken: 'authoring.token',
+  mcp: 'mcp.json',
+  logs: 'logs',
+  appLog: 'app.log',
+  activity: 'activity.json',
+  /** The launcher records the outcome of an install here. The panel shows it once. */
+  updateResult: 'update-result.json',
+} as const
+
+export function hostConfigPath(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.config)
+}
+
+export function hostAppsDir(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.apps)
+}
+
+export function hostTrashDir(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.trash)
+}
+
+export function hostAuthoringToken(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.authoringToken)
+}
+
+export function hostMcpPath(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.mcp)
+}
+
+/** Usage on this machine. Not source history. */
+export function hostActivityPath(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.activity)
+}
+
+/** The launcher's record of the last install. Absent until an install has run. */
+export function hostUpdateResultPath(runtimeRoot: string): string {
+  return path.join(runtimeRoot, hostLayout.updateResult)
+}
+
+/** Active app log. It sits at `apps/<appId>/logs/app.log`. */
+export function hostAppLogPath(runtimeRoot: string, appId: string): string {
+  return path.join(runtimeRoot, hostLayout.apps, appId, hostLayout.logs, hostLayout.appLog)
+}
+
+/** Product home. Themes sit beside the runtime root, not inside it. */
+export const homeLayout = {
+  dir: '.mini-app',
+  runtime: 'runtime',
+  themes: 'themes',
+  packages: 'packages',
+  credentials: 'credentials.json',
+} as const
+
+export function homeDir(home: string): string {
+  return path.join(home, homeLayout.dir)
+}
+
+export function defaultRuntimeRoot(home: string): string {
+  return path.join(homeDir(home), homeLayout.runtime)
+}
+
+export function homeThemesDir(home: string): string {
+  return path.join(homeDir(home), homeLayout.themes)
+}
+
+/** Drop folder for local tarball updates. Not user data. */
+export function homePackagesDir(home: string): string {
+  return path.join(homeDir(home), homeLayout.packages)
+}
+
+export function homeCredentialsPath(home: string): string {
+  return path.join(homeDir(home), homeLayout.credentials)
+}

package/src/host/log.ts

@@ -0,0 +1,142 @@
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs'
+import path from 'node:path'
+
+import { hostLayout } from './layout.ts'
+
+/** Byte cap for one app. Host policy, not a locked number. */
+export const DEFAULT_HOST_LOG_BYTES = 5 * 1024 * 1024
+
+/** Sealed piece. A write never reads log bytes. Host policy, not a locked number. */
+const SEGMENT_BYTES = 1024 * 1024
+
+const ACTIVE = hostLayout.appLog
+
+export interface HostLog {
+  write(appId: string, ...args: unknown[]): void
+  read(appId: string): readonly string[]
+}
+
+/**
+ * Append-only JSONL log at `apps/<appId>/logs`.
+ * One record is one line. A record is written whole, even when it is larger than the segment.
+ * The active file is sealed before a record would cross the segment size.
+ * Past `maxBytes`, the oldest sealed file is deleted. The newest file stays.
+ * `write` uses stat, rename, and unlink. It does not read the log.
+ * @param runtimeRoot - host runtime root
+ * @param maxBytes - cap across the segments of one app
+ */
+export function createHostLog(runtimeRoot: string, maxBytes = DEFAULT_HOST_LOG_BYTES): HostLog {
+  const segmentBytes = Math.min(SEGMENT_BYTES, maxBytes)
+  return {
+    write(appId, ...args) {
+      const dir = logDir(runtimeRoot, appId)
+      mkdirSync(dir, { recursive: true })
+      const line = jsonLine(args)
+      const active = path.join(dir, ACTIVE)
+      if (fileSize(active) > 0 && fileSize(active) + Buffer.byteLength(line) > segmentBytes) seal(dir)
+      appendFileSync(active, line)
+      if (fileSize(active) > segmentBytes) seal(dir)
+      dropOldest(dir, maxBytes)
+    },
+    read(appId) {
+      const lines: string[] = []
+      for (const name of segmentNames(logDir(runtimeRoot, appId))) {
+        let text: string
+        try {
+          text = readFileSync(path.join(logDir(runtimeRoot, appId), name), 'utf8')
+        } catch {
+          continue
+        }
+        lines.push(...recordLines(text))
+      }
+      return lines
+    },
+  }
+}
+
+function logDir(runtimeRoot: string, appId: string): string {
+  if (appId === '' || appId.includes('/') || appId.includes('\\') || appId.includes('..')) {
+    throw new Error(`log app id is not a single segment: ${appId}`)
+  }
+  return path.join(runtimeRoot, hostLayout.apps, appId, hostLayout.logs)
+}
+
+function jsonLine(args: unknown[]): string {
+  return `${JSON.stringify({ t: new Date().toISOString(), line: args.map(textOf).join(' ') })}\n`
+}
+
+function recordLines(text: string): string[] {
+  const lines: string[] = []
+  for (const row of text.split('\n')) {
+    if (row === '') continue
+    try {
+      const value: unknown = JSON.parse(row)
+      if (typeof value === 'object' && value !== null && 'line' in value && typeof value.line === 'string') {
+        lines.push(value.line)
+        continue
+      }
+    } catch {
+      // A line that is not a record is kept as text.
+    }
+    lines.push(row)
+  }
+  return lines
+}
+
+function fileSize(file: string): number {
+  try {
+    return statSync(file).size
+  } catch {
+    return 0
+  }
+}
+
+function seal(dir: string): void {
+  const active = path.join(dir, ACTIVE)
+  if (fileSize(active) === 0) return
+  renameSync(active, path.join(dir, `${nextId(dir)}.log`))
+}
+
+function nextId(dir: string): string {
+  let max = 0
+  for (const name of segmentNames(dir)) {
+    if (name === ACTIVE) continue
+    const id = Number(name.slice(0, -'.log'.length))
+    if (Number.isInteger(id) && id > max) max = id
+  }
+  return String(max + 1).padStart(6, '0')
+}
+
+function dropOldest(dir: string, maxBytes: number): void {
+  const segments = segmentNames(dir).map(name => ({
+    name,
+    path: path.join(dir, name),
+    size: fileSize(path.join(dir, name)),
+  }))
+  let total = segments.reduce((sum, item) => sum + item.size, 0)
+  for (const item of segments.slice(0, -1)) {
+    if (total <= maxBytes) return
+    unlinkSync(item.path)
+    total -= item.size
+  }
+}
+
+function segmentNames(dir: string): string[] {
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return []
+  }
+  return names.filter(name => name.endsWith('.log')).sort()
+}
+
+function textOf(value: unknown): string {
+  if (typeof value === 'string') return value
+  if (value instanceof Error) return value.message
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return Object.prototype.toString.call(value)
+  }
+}