@mohou/host 1.0.20

package/src/credentials/file.ts

@@ -0,0 +1,113 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { CredentialError } from './codes.ts'
+import { admitCredentialName, type CredentialProvider } from './provider.ts'
+
+interface CredentialEntry {
+  readonly description: string
+  readonly secret: string
+}
+
+/**
+ * One JSON file as one credential store. Read and write reach the same file, so the two sides
+ * cannot drift. A missing file is an empty source.
+ * A present bad file throws `credential-unreadable` and is not rewritten.
+ * @param file - absolute path. The name lives in `homeLayout`.
+ */
+export function createFileCredentials(file: string): CredentialProvider {
+  return {
+    writable: true,
+    async list() {
+      const entries = await readCredentialFile(file)
+      return [...entries.entries()]
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([name, entry]) => ({ name, description: entry.description }))
+    },
+    async get(name) {
+      admitCredentialName(name)
+      const entries = await readCredentialFile(file)
+      return entries.get(name)?.secret
+    },
+    put: (name, description, secret) => writeFileCredential(file, name, description, secret),
+    remove: name => deleteFileCredential(file, name),
+  }
+}
+
+/**
+ * Write one account into the JSON source. Not a method on the read port.
+ * A present bad file is not overwritten.
+ * @param file - absolute path
+ * @param name - owner-chosen account name
+ * @param description - text the author can recognize
+ * @param secret - the one value
+ */
+export async function writeFileCredential(file: string, name: string, description: string, secret: string): Promise<void> {
+  admitCredentialName(name)
+  const entries = await readCredentialFile(file)
+  const next = new Map(entries)
+  next.set(name, { description, secret })
+  await writeEntries(file, next)
+}
+
+/**
+ * Remove one account from the JSON source. A missing name leaves the file unchanged.
+ * @param file - absolute path
+ * @param name - owner-chosen account name
+ */
+export async function deleteFileCredential(file: string, name: string): Promise<void> {
+  admitCredentialName(name)
+  const entries = await readCredentialFile(file)
+  if (!entries.has(name)) return
+  const next = new Map(entries)
+  next.delete(name)
+  await writeEntries(file, next)
+}
+
+async function writeEntries(file: string, entries: ReadonlyMap<string, CredentialEntry>): Promise<void> {
+  await mkdir(path.dirname(file), { recursive: true })
+  const body: Record<string, CredentialEntry> = {}
+  for (const [name, entry] of entries) body[name] = entry
+  // The file holds secrets in the clear, so it is owner-only. `mode` covers a new file and the
+  // chmod tightens one that an earlier version wrote world-readable.
+  await writeFile(file, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 })
+  await chmod(file, 0o600).catch(() => undefined)
+}
+
+async function readCredentialFile(file: string): Promise<ReadonlyMap<string, CredentialEntry>> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch (error) {
+    if (isNotFound(error)) return new Map()
+    throw new CredentialError('credential-unreadable', 'credential file cannot be read', { cause: error })
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch (error) {
+    throw new CredentialError('credential-unreadable', 'credential file is not JSON', { cause: error })
+  }
+  return resolveCredentialFile(raw)
+}
+
+function resolveCredentialFile(raw: unknown): ReadonlyMap<string, CredentialEntry> {
+  if (!isRecord(raw)) throw new CredentialError('credential-unreadable', 'credential file must be an object')
+  const entries = new Map<string, CredentialEntry>()
+  for (const [name, value] of Object.entries(raw)) {
+    if (name === '') throw new CredentialError('credential-unreadable', 'credential file has an empty name')
+    if (!isRecord(value) || typeof value.description !== 'string' || typeof value.secret !== 'string') {
+      throw new CredentialError('credential-unreadable', `credential file entry is incomplete: ${name}`)
+    }
+    entries.set(name, { description: value.description, secret: value.secret })
+  }
+  return entries
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT'
+}

package/src/credentials/provider.ts

@@ -0,0 +1,66 @@
+import { CredentialError } from './codes.ts'
+
+/** One account an author can recognize. No secret. */
+export interface CredentialListing {
+  readonly name: string
+  readonly description: string
+}
+
+/**
+ * One credential store. Read and write are one abstraction, so Shell swaps the implementation in
+ * one place: the built-in JSON file today, a system keychain later.
+ *
+ * App code does not see this interface. `ctx.credentials` projects `get` alone.
+ */
+export interface CredentialProvider {
+  /** Whether {@link put} and {@link remove} do anything. A read-only source is false. */
+  readonly writable: boolean
+  list(): Promise<readonly CredentialListing[]>
+  get(name: string): Promise<string | undefined>
+  /**
+   * Write one account. An existing name keeps its place and takes the new description and secret.
+   * @param name - owner-chosen account name
+   * @param description - text the owner recognizes
+   * @param secret - the one value
+   */
+  put(name: string, description: string, secret: string): Promise<void>
+  /**
+   * Remove one account. A missing name changes nothing.
+   * @param name - owner-chosen account name
+   */
+  remove(name: string): Promise<void>
+}
+
+/**
+ * No source. `list` is empty, `get` is `undefined`, and the write side says why it cannot write.
+ * An empty name is still `credential-invalid`.
+ */
+export function emptyCredentials(): CredentialProvider {
+  return {
+    writable: false,
+    list: () => Promise.resolve([]),
+    get: name => Promise.resolve().then(() => {
+      admitCredentialName(name)
+      return undefined
+    }),
+    put: (name) => {
+      admitCredentialName(name)
+      return Promise.reject(cannotWrite())
+    },
+    remove: (name) => {
+      admitCredentialName(name)
+      return Promise.reject(cannotWrite())
+    },
+  }
+}
+
+/** Reject an empty name before the source is read. */
+export function admitCredentialName(name: string): string {
+  if (name === '') throw new CredentialError('credential-invalid', 'credential name is empty')
+  return name
+}
+
+/** The failure of a write against a store that has no writable source. */
+export function cannotWrite(): CredentialError {
+  return new CredentialError('credential-write-unavailable', 'no credential source can be written')
+}

package/src/events/app-events.ts

@@ -0,0 +1,214 @@
+/** Retained events per app when the caller omits a bound. Host policy, not a locked number. */
+export const DEFAULT_APP_EVENT_TAIL = 50
+
+/** Retry hint sent when a subscriber opens. Host policy, not a locked number. */
+export const DEFAULT_APP_EVENT_RETRY_MS = 3000
+
+/** Ping interval while a subscriber is attached. Host policy, not a locked number. */
+export const DEFAULT_APP_EVENT_PING_MS = 15_000
+
+/** One author event. Diagnostics never use this shape. */
+export interface AuthorEvent {
+  readonly name: string
+  readonly data: unknown
+  readonly seq: number
+}
+
+/** The retained tail no longer contains `since`. The UI refetches. It does not invent events. */
+export interface AppGap {
+  readonly type: 'app:gap'
+  readonly appId: string
+  readonly since: number
+}
+
+/** Sent to the subscriber that just opened. Not an author channel. */
+export interface AppRetry {
+  readonly type: 'retry'
+  readonly retryMs: number
+}
+
+/** Sent while at least one subscriber is attached. Not an author channel. */
+export interface AppPing {
+  readonly type: 'ping'
+}
+
+export type AppStreamItem = AuthorEvent | AppGap | AppRetry | AppPing
+
+/** What `useApp().on` and `useApp().onAny` see. Ping and the retry hint stay on the stream. */
+export interface AppHooks {
+  on(name: string, callback: (data: unknown) => void): () => void
+  onAny(callback: (event: { name: string; data: unknown }) => void): () => void
+}
+
+/** The per-app author buffer. Diagnostics do not use this. */
+export interface AppEvents {
+  push(appId: string, name: string, data?: unknown): void
+  subscribe(appId: string, lastSeq: number, listener: (item: AppStreamItem) => void): () => void
+  observe(listener: (appId: string, event: AuthorEvent) => void): () => void
+  retained(): ReadonlyArray<{ readonly appId: string; readonly gap?: { readonly since: number }; readonly events: readonly AuthorEvent[] }>
+  dispose(): void
+}
+
+interface AppLog {
+  seq: number
+  events: AuthorEvent[]
+  listeners: Set<(item: AppStreamItem) => void>
+  ping: ReturnType<typeof setInterval> | undefined
+}
+
+/**
+ * Per-app author stream. `tailLength` is host policy and is not locked.
+ * @param options - buffer bound and the warning log
+ */
+export function createAppEvents(options: {
+  readonly tailLength: number
+  readonly retryMs?: number
+  readonly pingMs?: number
+  readonly log?: (message: string) => void
+}): AppEvents {
+  const retryMs = options.retryMs ?? DEFAULT_APP_EVENT_RETRY_MS
+  const pingMs = options.pingMs ?? DEFAULT_APP_EVENT_PING_MS
+  const apps = new Map<string, AppLog>()
+  const observers = new Set<(appId: string, event: AuthorEvent) => void>()
+  const log = options.log ?? ((message: string) => {
+    console.warn(message)
+  })
+
+  function read(appId: string): AppLog {
+    const existing = apps.get(appId)
+    if (existing !== undefined) return existing
+    const created: AppLog = { seq: 0, events: [], listeners: new Set(), ping: undefined }
+    apps.set(appId, created)
+    return created
+  }
+
+  return {
+    push(appId, name, data) {
+      if (data !== undefined && !isJson(data)) {
+        log(`ctx.push("${name}") dropped: data is not JSON`)
+        return
+      }
+      const app = read(appId)
+      app.seq += 1
+      const event: AuthorEvent = { name, data, seq: app.seq }
+      app.events.push(event)
+      if (app.events.length > options.tailLength) {
+        app.events.splice(0, app.events.length - options.tailLength)
+      }
+      for (const listener of [...app.listeners]) listener(event)
+      for (const observer of [...observers]) observer(appId, event)
+    },
+    observe(listener) {
+      observers.add(listener)
+      return () => {
+        observers.delete(listener)
+      }
+    },
+    retained() {
+      const rows = []
+      for (const [appId, app] of apps) {
+        const oldest = app.events[0]
+        if (oldest === undefined) continue
+        const gap = oldest.seq > 1 ? { since: 0 } : undefined
+        rows.push({
+          appId,
+          events: app.events,
+          ...gap === undefined ? {} : { gap },
+        })
+      }
+      return rows
+    },
+    subscribe(appId, lastSeq, listener) {
+      const app = read(appId)
+      listener({ type: 'retry', retryMs })
+      const oldest = app.events[0]
+      if (oldest !== undefined && oldest.seq > lastSeq + 1) {
+        listener({ type: 'app:gap', appId, since: lastSeq })
+      }
+      for (const event of app.events) {
+        if (event.seq > lastSeq) listener(event)
+      }
+      app.listeners.add(listener)
+      if (app.listeners.size === 1 && pingMs > 0 && app.ping === undefined) {
+        const timer = setInterval(() => {
+          for (const current of [...app.listeners]) current({ type: 'ping' })
+        }, pingMs)
+        timer.unref()
+        app.ping = timer
+      }
+      return () => {
+        app.listeners.delete(listener)
+        if (app.listeners.size === 0 && app.ping !== undefined) {
+          clearInterval(app.ping)
+          app.ping = undefined
+        }
+      }
+    },
+    dispose() {
+      observers.clear()
+      for (const app of apps.values()) {
+        if (app.ping !== undefined) clearInterval(app.ping)
+        app.ping = undefined
+        app.listeners.clear()
+      }
+    },
+  }
+}
+
+/**
+ * Forward every app onto one listener. Live events are registered before the retained tail is copied.
+ * The panel uses this on the host stream so an open tab does not hold its own socket.
+ */
+export function forwardFrames(events: AppEvents, listener: (event: unknown) => void): () => void {
+  const stop = events.observe((appId, event) => {
+    listener({ type: 'app:event', appId, name: event.name, data: event.data, seq: event.seq })
+  })
+  for (const row of events.retained()) {
+    if (row.gap !== undefined) listener({ type: 'app:gap', appId: row.appId, since: row.gap.since })
+    for (const event of row.events) {
+      listener({ type: 'app:event', appId: row.appId, name: event.name, data: event.data, seq: event.seq })
+    }
+  }
+  return stop
+}
+
+/** Map the author stream onto `on` / `onAny`. A gap is `{ name: "*", data: { gap: true } }` for `onAny` only. */
+export function bindAppHooks(events: AppEvents, appId: string, lastSeq = 0): AppHooks {
+  return {
+    on(name, callback) {
+      return events.subscribe(appId, lastSeq, (item) => {
+        if (!isAuthorEvent(item)) return
+        if (name !== '*' && item.name !== name) return
+        callback(item.data)
+      })
+    },
+    onAny(callback) {
+      return events.subscribe(appId, lastSeq, (item) => {
+        if (isGap(item)) {
+          callback({ name: '*', data: { gap: true } })
+          return
+        }
+        if (!isAuthorEvent(item)) return
+        callback({ name: item.name, data: item.data })
+      })
+    },
+  }
+}
+
+function isAuthorEvent(item: AppStreamItem): item is AuthorEvent {
+  return 'seq' in item
+}
+
+function isGap(item: AppStreamItem): item is AppGap {
+  return 'type' in item && item.type === 'app:gap'
+}
+
+function isJson(value: unknown): boolean {
+  if (typeof value === 'function' || typeof value === 'symbol' || value === undefined) return false
+  try {
+    JSON.stringify(value)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/events/error-ring.ts

@@ -0,0 +1,109 @@
+/** Kinds an iframe may report. A resource-load error with no message is dropped. */
+export const errorKinds = ['render', 'module', 'uncaught', 'async'] as const
+
+export type ErrorKind = (typeof errorKinds)[number]
+
+export interface AppErrorRecord {
+  seq: number
+  kind: ErrorKind
+  message: string
+  componentStack?: string
+}
+
+/** Ring cap when the caller omits one. Host policy, not a locked number. */
+const DEFAULT_CAP = 50
+
+interface Ring {
+  seq: number
+  errors: AppErrorRecord[]
+  dropped: number
+  opened: boolean
+}
+
+interface AdmittedError {
+  kind: ErrorKind
+  message: string
+  componentStack?: string
+}
+
+/**
+ * Admit one iframe error report. A bad kind or an empty message is dropped.
+ * @param raw - untrusted JSON
+ */
+export function admitErrorReport(raw: unknown): AdmittedError | undefined {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return undefined
+  const kind = 'kind' in raw ? raw.kind : undefined
+  const message = 'message' in raw ? raw.message : undefined
+  const componentStack = 'componentStack' in raw ? raw.componentStack : undefined
+  if (typeof kind !== 'string' || !isErrorKind(kind)) return undefined
+  if (typeof message !== 'string' || message.length === 0) return undefined
+  return {
+    kind,
+    message,
+    ...typeof componentStack === 'string' ? { componentStack } : {},
+  }
+}
+
+/**
+ * Per-app error ring. Diagnostics never enter the author event buffer.
+ * @param cap - retained errors; older ones increment `dropped`
+ */
+export function createErrorRing(cap = DEFAULT_CAP) {
+  const apps = new Map<string, Ring>()
+
+  function ring(appId: string): Ring {
+    const existing = apps.get(appId)
+    if (existing !== undefined) return existing
+    const created: Ring = { seq: 0, errors: [], dropped: 0, opened: false }
+    apps.set(appId, created)
+    return created
+  }
+
+  return {
+    record(appId: string, raw: unknown) {
+      const admitted = admitErrorReport(raw)
+      if (admitted === undefined) return
+      const current = ring(appId)
+      current.seq += 1
+      const entry: AppErrorRecord = {
+        seq: current.seq,
+        kind: admitted.kind,
+        message: admitted.message,
+        ...admitted.componentStack === undefined ? {} : { componentStack: admitted.componentStack },
+      }
+      current.errors.push(entry)
+      while (current.errors.length > cap) {
+        current.errors.shift()
+        current.dropped += 1
+      }
+    },
+    markOpened(appId: string) {
+      ring(appId).opened = true
+    },
+    clearReload(appId: string) {
+      const current = ring(appId)
+      current.errors = []
+      current.dropped = 0
+      current.opened = false
+    },
+    read(appId: string, since?: number, clear = false) {
+      const current = ring(appId)
+      if (clear) current.errors = []
+      const errors = since === undefined ? [...current.errors] : current.errors.filter(item => item.seq > since)
+      const hint = current.errors.length === 0 && !current.opened
+      return {
+        errors,
+        lastSeq: current.seq,
+        dropped: current.dropped,
+        ...hint ? { emptyHint: 'open the app before treating an empty ring as clean' } : {},
+      }
+    },
+    forget(appId: string) {
+      apps.delete(appId)
+    },
+  }
+}
+
+function isErrorKind(value: string): value is ErrorKind {
+  return (errorKinds as readonly string[]).includes(value)
+}

package/src/events/host-events.ts

@@ -0,0 +1,39 @@
+/** Host stream events. An author UI does not subscribe to this map. */
+
+export type HostEvent =
+  | { type: 'app:open'; appId: string; title?: string }
+  | { type: 'workbench:default'; appId: string }
+  | { type: 'app:reload'; appId: string }
+  | { type: 'storage-size'; appId: string; table: string; keys: string[] }
+  | {
+    type: 'app:eval'
+    appId: string
+    requestId: string
+    code: string
+    budgetMs: number
+    maxBytes: number
+    maxNodes: number
+    maxDepth: number
+  }
+
+/**
+ * In-process host stream. `GET /api/events` is the HTTP projection.
+ * `app:open` focuses a tab. `app:reload` refetches and does not create one.
+ */
+export function createHostEvents() {
+  const listeners = new Set<(event: HostEvent) => void>()
+  return {
+    subscribe(listener: (event: HostEvent) => void) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    publish(event: HostEvent) {
+      for (const listener of [...listeners]) listener(event)
+    },
+    get connected() {
+      return listeners.size > 0
+    },
+  }
+}