@mohou/host 1.0.20

package/README.md

@@ -0,0 +1,10 @@
+---
+status: locked
+updated: 2026-10-01
+---
+
+# @mohou/host
+
+Role: `provider`.
+
+The call loop: build one `AppContext` from injected ports, run one method, dispose the call. Binding the brain is one part of that loop. Storage is the SQLite file beside that loop. Host also compiles the app and serves the loopback surface. It does not embed a model vendor. Product: [packages](../../../docs/architecture/packages.md).

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@mohou/host",
+  "version": "1.0.20",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "themes",
+    "lib/types",
+    "README.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./http": {
+      "types": "./src/http/layout.ts",
+      "default": "./src/http/layout.ts"
+    },
+    "./diagnostics": {
+      "types": "./src/tools/diagnostics.ts",
+      "default": "./src/tools/diagnostics.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@tailwindcss/node": "^4.3.3",
+    "@tailwindcss/oxide": "^4.3.3",
+    "better-sqlite3": "^13.0.3",
+    "esbuild": "^0.28.2",
+    "hono": "^4.13.8",
+    "isomorphic-git": "^1.42.2",
+    "lodash": "^4.18.1",
+    "lodash-es": "^4.18.1",
+    "motion": "^12.23.12",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
+    "@mohou/app-view": "^1.0.20",
+    "@mohou/contract": "^1.0.20",
+    "@mohou/runtime-provider": "^1.0.20",
+    "@mohou/ui": "^1.0.20",
+    "@mohou/mcp-client": "^1.0.20"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/react": "^19.2.0"
+  },
+  "scripts": {
+    "build:vendor": "node --experimental-strip-types src/compile/build-vendor-cli.ts"
+  }
+}

package/src/apps/monogram.ts

@@ -0,0 +1,15 @@
+/**
+ * Two-character gallery badge. A manifest acronym wins. Latin letters are
+ * uppercased. Otherwise the first two letters or digits of the name. If the
+ * name has fewer, the first two characters.
+ * @param name - manifest name, already non-empty
+ * @param acronym - author acronym, already two letters or digits when present
+ */
+export function monogram(name: string, acronym?: string): string {
+  if (acronym !== undefined) {
+    return /^[A-Za-z]{2}$/.test(acronym) ? acronym.toUpperCase() : acronym
+  }
+  const letters = name.replace(/[^A-Za-z0-9]/g, '').slice(0, 2).toUpperCase()
+  if (letters.length === 2) return letters
+  return name.trim().slice(0, 2).toUpperCase()
+}

package/src/apps/registry.ts

@@ -0,0 +1,238 @@
+import { randomBytes } from 'node:crypto'
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { ContractError, appEntries, parseAppId, resolveManifest, type AppId, type AppListItem } from '@mohou/contract'
+
+import { resolveAppPath } from '../files/tools.ts'
+import { hostAppsDir, hostLayout, hostTrashDir } from '../host/layout.ts'
+import { monogram } from './monogram.ts'
+
+/** Registry failures that are not definition failures. */
+export class RegistryError extends Error {
+  readonly code: 'app-duplicate' | 'app-not-registered' | 'app-not-trashed'
+
+  /**
+   * @param code - `app-duplicate`, `app-not-registered`, or `app-not-trashed`
+   * @param message - human text; not the match key
+   */
+  constructor(code: 'app-duplicate' | 'app-not-registered' | 'app-not-trashed', message: string) {
+    super(message)
+    this.name = 'RegistryError'
+    this.code = code
+  }
+}
+
+export interface AppSummary {
+  id: AppId
+  name: string
+  description: string
+  version: string
+  /** Gallery badge. Author acronym, or a monogram derived from `name`. */
+  acronym: string
+  /** Manifest tags. Omitted when the author set none. */
+  tags?: readonly string[]
+  /** Manifest kind. Omitted for an ordinary app. */
+  kind?: 'workbench'
+  directory: string
+}
+
+/** Owner list row. Directory stays off this object. Times are omitted when history has no commit. */
+export function listedApp(
+  app: AppSummary,
+  times: { readonly createdAt?: string; readonly updatedAt?: string } = {},
+  activity?: { readonly openCount: number; readonly lastOpenedAt: string },
+): ListedApp {
+  return {
+    id: app.id,
+    name: app.name,
+    description: app.description,
+    version: app.version,
+    acronym: app.acronym,
+    ...app.tags === undefined ? {} : { tags: app.tags },
+    ...app.kind === undefined ? {} : { kind: app.kind },
+    ...times.createdAt === undefined ? {} : { createdAt: times.createdAt },
+    ...times.updatedAt === undefined ? {} : { updatedAt: times.updatedAt },
+    ...activity === undefined ? {} : { activity },
+  }
+}
+
+export type ListedApp = AppListItem
+
+/**
+ * Apps on disk under `runtimeRoot/apps`. Register does not overwrite.
+ * @param runtimeRoot - host runtime root; not a locked path
+ */
+export function createAppRegistry(runtimeRoot: string) {
+  const appsDir = hostAppsDir(runtimeRoot)
+  return {
+    runtimeRoot,
+    list: () => listApps(appsDir, runtimeRoot),
+    get: (appId: string) => getApp(appsDir, appId),
+    register: (appId: string, files: Record<string, string>) => registerApp(appsDir, appId, files),
+    trash: (appId: string) => trashApp(appsDir, runtimeRoot, appId),
+    restoreTrashed: (appId: string) => restoreTrashed(appsDir, runtimeRoot, appId),
+    listTrash: () => listTrash(runtimeRoot),
+  }
+}
+
+async function listApps(appsDir: string, runtimeRoot: string): Promise<{ apps: AppSummary[]; runtimeRoot: string }> {
+  let names: string[] = []
+  try {
+    names = await readdir(appsDir)
+  } catch {
+    return { apps: [], runtimeRoot }
+  }
+  const apps: AppSummary[] = []
+  for (const name of names) {
+    const summary = await readSummary(path.join(appsDir, name), name)
+    if (summary !== undefined) apps.push(summary)
+  }
+  return { apps, runtimeRoot }
+}
+
+async function getApp(appsDir: string, appId: string): Promise<AppSummary> {
+  const id = admitId(appId)
+  const summary = await readSummary(path.join(appsDir, id), id)
+  if (summary === undefined) throw new RegistryError('app-not-registered', `app is not registered: ${appId}`)
+  return summary
+}
+
+async function registerApp(appsDir: string, appId: string, files: Record<string, string>): Promise<AppSummary> {
+  const id = admitId(appId)
+  const finalDir = path.join(appsDir, id)
+  if (await exists(finalDir)) throw new RegistryError('app-duplicate', `app already exists: ${id}`)
+  const staging = path.join(appsDir, `.registering-${id}`)
+  await rm(staging, { recursive: true, force: true })
+  await mkdir(staging, { recursive: true })
+  try {
+    for (const [relative, content] of Object.entries(files)) {
+      const full = resolveAppPath(staging, relative)
+      await mkdir(path.dirname(full), { recursive: true })
+      await writeFile(full, content)
+    }
+    const manifest = await readManifest(staging, id)
+    await rename(staging, finalDir)
+    return summaryOf(manifest, finalDir)
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true })
+    throw error
+  }
+}
+
+async function trashApp(appsDir: string, runtimeRoot: string, appId: string): Promise<void> {
+  const id = admitId(appId)
+  const from = path.join(appsDir, id)
+  if (!(await exists(from))) throw new RegistryError('app-not-registered', `app is not registered: ${id}`)
+  const trash = hostTrashDir(runtimeRoot)
+  await mkdir(trash, { recursive: true })
+  const stamp = `${String(Date.now()).padStart(16, '0')}-${randomBytes(2).toString('hex')}`
+  await rename(from, path.join(trash, `${id}${hostLayout.trashSep}${stamp}`))
+}
+
+async function restoreTrashed(appsDir: string, runtimeRoot: string, appId: string): Promise<AppSummary> {
+  const id = admitId(appId)
+  const live = path.join(appsDir, id)
+  if (await exists(live)) throw new RegistryError('app-duplicate', `app already exists: ${id}`)
+  const latest = await newestTrash(runtimeRoot, id)
+  if (latest === undefined) throw new RegistryError('app-not-trashed', `app is not in trash: ${id}`)
+  await rename(latest, live)
+  const summary = await readSummary(live, id)
+  if (summary === undefined) throw new RegistryError('app-not-trashed', `app is not in trash: ${id}`)
+  return summary
+}
+
+async function listTrash(runtimeRoot: string): Promise<AppSummary[]> {
+  const trash = hostTrashDir(runtimeRoot)
+  let names: string[] = []
+  try {
+    names = await readdir(trash)
+  } catch {
+    return []
+  }
+  const newest = new Map<string, string>()
+  for (const name of names) {
+    const split = splitTrashName(name)
+    if (split === undefined) continue
+    const current = newest.get(split.id)
+    if (current === undefined || split.stamp > current) newest.set(split.id, split.stamp)
+  }
+  const apps: AppSummary[] = []
+  for (const [id, stamp] of newest) {
+    const summary = await readSummary(path.join(trash, `${id}${hostLayout.trashSep}${stamp}`), id).catch(() => undefined)
+    if (summary !== undefined) apps.push(summary)
+  }
+  return apps.sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+}
+
+function splitTrashName(name: string): { id: string; stamp: string } | undefined {
+  const at = name.indexOf(hostLayout.trashSep)
+  if (at <= 0) return undefined
+  const id = name.slice(0, at)
+  const stamp = name.slice(at + hostLayout.trashSep.length)
+  if (stamp === '') return undefined
+  try {
+    parseAppId(id)
+  } catch {
+    return undefined
+  }
+  return { id, stamp }
+}
+
+async function newestTrash(runtimeRoot: string, id: string): Promise<string | undefined> {
+  const trash = hostTrashDir(runtimeRoot)
+  let names: string[] = []
+  try {
+    names = await readdir(trash)
+  } catch {
+    return undefined
+  }
+  const prefix = `${id}${hostLayout.trashSep}`
+  const matches = names.filter(name => name.startsWith(prefix)).sort()
+  const latest = matches.at(-1)
+  return latest === undefined ? undefined : path.join(trash, latest)
+}
+
+function admitId(appId: string): AppId {
+  try {
+    return parseAppId(appId)
+  } catch (error) {
+    throw new ContractError('app-id-invalid', `app id is not reverse-DNS: ${appId}`, { cause: error })
+  }
+}
+
+async function readSummary(directory: string, directoryName: string): Promise<AppSummary | undefined> {
+  const manifest = await readManifest(directory, directoryName).catch(() => undefined)
+  if (manifest === undefined) return undefined
+  return summaryOf(manifest, directory)
+}
+
+async function readManifest(directory: string, directoryName: string) {
+  const text = await readFile(path.join(directory, appEntries.manifest), 'utf8')
+  return resolveManifest(JSON.parse(text) as unknown, directoryName)
+}
+
+function summaryOf(
+  manifest: { id: AppId; name: string; description: string; version: string; acronym?: string; tags?: readonly string[]; kind?: 'workbench' },
+  directory: string,
+): AppSummary {
+  return {
+    id: manifest.id,
+    name: manifest.name,
+    description: manifest.description,
+    version: manifest.version,
+    acronym: monogram(manifest.name, manifest.acronym),
+    directory,
+    ...manifest.tags === undefined ? {} : { tags: manifest.tags },
+    ...manifest.kind === undefined ? {} : { kind: manifest.kind },
+  }
+}
+
+async function exists(directory: string): Promise<boolean> {
+  try {
+    await readdir(directory)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/apps/startup-seed.ts

@@ -0,0 +1,95 @@
+import { access, cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { hostAppsDir, hostLayout, hostTrashDir } from '../host/layout.ts'
+
+/** Once per runtime root. Deleting samples must not re-seed on every boot. */
+export const startupSeedMarker = '.startup-seed'
+
+/**
+ * Skill facades copied into an empty library.
+ * `today` = personal home; `board` = second card so glass featured layout has company.
+ */
+export const startupSamples = [
+  { template: 'today', appId: 'com.mohou.today', fallbackName: '今日待办' },
+  { template: 'board', appId: 'com.mohou.board', fallbackName: 'Board' },
+] as const
+
+export type StartupSeedResult =
+  | { readonly kind: 'seeded'; readonly appIds: readonly string[] }
+  | { readonly kind: 'skipped'; readonly reason: 'marked' | 'has-apps' | 'no-template' }
+
+/**
+ * Ensure `apps/` and `trash/` exist. On a fresh runtime (no marker, no apps),
+ * copy skill startup facades so the library shows glass cards immediately.
+ * @param runtimeRoot - host runtime root
+ * @param skillSource - author skill directory that contains `templates/`
+ */
+export async function ensureRuntimeAppsLayout(
+  runtimeRoot: string,
+  skillSource?: string,
+): Promise<StartupSeedResult> {
+  const appsDir = hostAppsDir(runtimeRoot)
+  const trashDir = hostTrashDir(runtimeRoot)
+  await mkdir(appsDir, { recursive: true })
+  await mkdir(trashDir, { recursive: true })
+
+  const marker = path.join(runtimeRoot, startupSeedMarker)
+  if (await present(marker)) return { kind: 'skipped', reason: 'marked' }
+
+  const existing = await listAppDirs(appsDir)
+  if (existing.length > 0) {
+    await writeFile(marker, `${JSON.stringify({ seeded: false, reason: 'has-apps' }, null, 2)}\n`)
+    return { kind: 'skipped', reason: 'has-apps' }
+  }
+
+  if (skillSource === undefined || skillSource.length === 0) {
+    await writeFile(marker, `${JSON.stringify({ seeded: false, reason: 'no-template' }, null, 2)}\n`)
+    return { kind: 'skipped', reason: 'no-template' }
+  }
+
+  const appIds: string[] = []
+  for (const sample of startupSamples) {
+    const templateDir = path.join(skillSource, 'templates', sample.template)
+    if (!(await present(path.join(templateDir, 'manifest.json')))) continue
+    const dest = path.join(appsDir, sample.appId)
+    await cp(templateDir, dest, { recursive: true })
+    await rewriteManifestId(path.join(dest, 'manifest.json'), sample.appId, sample.fallbackName)
+    appIds.push(sample.appId)
+  }
+
+  if (appIds.length === 0) {
+    await writeFile(marker, `${JSON.stringify({ seeded: false, reason: 'no-template' }, null, 2)}\n`)
+    return { kind: 'skipped', reason: 'no-template' }
+  }
+
+  await writeFile(marker, `${JSON.stringify({ seeded: true, appIds, samples: startupSamples }, null, 2)}\n`)
+  return { kind: 'seeded', appIds }
+}
+
+async function rewriteManifestId(file: string, appId: string, fallbackName: string): Promise<void> {
+  const raw = JSON.parse(await readFile(file, 'utf8')) as Record<string, unknown>
+  raw.id = appId
+  if (typeof raw.name !== 'string' || raw.name.length === 0) raw.name = fallbackName
+  await writeFile(file, `${JSON.stringify(raw, null, 2)}\n`)
+}
+
+async function listAppDirs(appsDir: string): Promise<string[]> {
+  const names = await readdir(appsDir).catch(() => [] as string[])
+  const out: string[] = []
+  for (const name of names) {
+    if (name.startsWith('.')) continue
+    if (name === hostLayout.logs) continue
+    if (await present(path.join(appsDir, name, 'manifest.json'))) out.push(name)
+  }
+  return out
+}
+
+async function present(file: string): Promise<boolean> {
+  try {
+    await access(file)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/bash/client.ts

@@ -0,0 +1,21 @@
+import type { CommandHandle, CommandPolicy, CommandResult } from '../shell/command.ts'
+import { createCommand, scrubShellEnv } from '../shell/command.ts'
+import { BashError } from './codes.ts'
+
+export type { CommandPolicy as BashPolicy, CommandResult as BashResult, CommandHandle as BashHandle }
+
+/** Parent environment minus key, secret, token, and password entries. */
+export function scrubBashEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  return scrubShellEnv(env)
+}
+
+/**
+ * Build `ctx.bash`. Each command is a fresh `bash -c`.
+ * Bash is not translated into PowerShell. A Windows machine needs `bash` on `PATH`.
+ * @param policy - resolved host bounds
+ * @param callSignal - aborting it stops the child
+ * @param shell - executable name; tests inject a missing one
+ */
+export function createBash(policy: CommandPolicy, callSignal?: AbortSignal, shell = 'bash'): CommandHandle {
+  return createCommand(policy, callSignal, command => [shell, '-c', command], () => new BashError('bash-unavailable', 'bash is not available'))
+}

package/src/bash/codes.ts

@@ -0,0 +1,21 @@
+/** Codes the bash call emits. Timeout and output cap are not codes. */
+
+export const bashCodes = ['bash-unavailable'] as const
+
+/** A bash failure. Callers match `code`. */
+export type BashCode = (typeof bashCodes)[number]
+
+/** Failure from `ctx.bash`. The message is for a person. */
+export class BashError extends Error {
+  readonly code: BashCode
+
+  /**
+   * @param code - one of {@link bashCodes}
+   * @param message - human text; not the match key
+   */
+  constructor(code: BashCode, message: string) {
+    super(message)
+    this.name = 'BashError'
+    this.code = code
+  }
+}

package/src/compile/allowlist.ts

@@ -0,0 +1,89 @@
+/** One platform-module table. The UI compiler, the backend loader, and the iframe import map all read it. */
+
+export type PlatformSide = 'ui' | 'backend' | 'both'
+
+/** Served iframe file names. Spell them here, not at each call site. */
+export const platformLayout = {
+  root: '/mma',
+  runtime: 'runtime.js',
+  sdk: 'sdk.js',
+  vendors: 'vendors',
+} as const
+
+export interface PlatformModule {
+  specifier: string
+  side: PlatformSide
+  file?: string
+  /** Compile this pattern into the app. A `/*` row is not a served file. */
+  bundle?: boolean
+}
+
+const runtimeFile = platformRuntimePath()
+const lodashFile = platformVendorPath('lodash')
+const motionFile = platformVendorPath('motion')
+
+export const platformModules: readonly PlatformModule[] = [
+  { specifier: '@mohou/contract', side: 'backend' },
+  { specifier: 'react', side: 'ui', file: runtimeFile },
+  { specifier: 'react/jsx-runtime', side: 'ui', file: runtimeFile },
+  { specifier: 'react-dom', side: 'ui', file: runtimeFile },
+  { specifier: 'react-dom/client', side: 'ui', file: runtimeFile },
+  { specifier: '@mohou/ui', side: 'ui', file: platformSdkPath() },
+  { specifier: 'lodash', side: 'both', file: lodashFile },
+  { specifier: 'lodash-es', side: 'both', file: lodashFile },
+  { specifier: 'lodash/*', side: 'both', bundle: true },
+  { specifier: 'lodash-es/*', side: 'both', bundle: true },
+  { specifier: 'motion', side: 'ui', file: motionFile },
+  { specifier: 'motion/react', side: 'ui', file: motionFile },
+]
+
+/** Whether this side may import the specifier. An exact row wins over a pattern. */
+export function platformModuleAllowed(specifier: string, side: 'ui' | 'backend'): boolean {
+  const row = platformRow(specifier)
+  if (row === undefined) return false
+  return row.side === 'both' || row.side === side
+}
+
+/** A pattern row with `bundle` is compiled into the app. The root row stays the served file. */
+export function platformBundled(specifier: string): boolean {
+  return platformRow(specifier)?.bundle === true
+}
+
+function platformRow(specifier: string): PlatformModule | undefined {
+  const exact = platformModules.find(row => row.specifier === specifier)
+  if (exact !== undefined) return exact
+  return platformModules.find(row => matchesPattern(row.specifier, specifier))
+}
+
+/** A trailing `/*` matches that prefix plus at least one character. */
+function matchesPattern(pattern: string, specifier: string): boolean {
+  if (!pattern.endsWith('/*')) return false
+  const prefix = pattern.slice(0, -1)
+  return specifier.startsWith(prefix) && specifier.length > prefix.length
+}
+
+/** Import map for the iframe. Only rows with a served file. */
+export function platformImportMap(): Readonly<Record<string, string>> {
+  const imports: Record<string, string> = {}
+  for (const row of platformModules) {
+    if (row.file === undefined || row.side === 'backend' || row.specifier.includes('*')) continue
+    imports[row.specifier] = row.file
+  }
+  return imports
+}
+
+export function platformRuntimePath(): string {
+  return joinPlatform(platformLayout.runtime)
+}
+
+export function platformSdkPath(): string {
+  return joinPlatform(platformLayout.sdk)
+}
+
+export function platformVendorPath(id: string): string {
+  return joinPlatform(`${platformLayout.vendors}/${id}.js`)
+}
+
+function joinPlatform(name: string): string {
+  return `${platformLayout.root}/${name}`
+}

package/src/compile/asset-path.ts

@@ -0,0 +1,48 @@
+/** Codes `resolveAssetUrl` throws in the iframe. Callers match `code`. */
+export const assetInvalidCode = 'asset-invalid' as const
+
+/**
+ * Admit an author path relative to the app directory.
+ * Returns the path inside `assets/`. Throws `asset-invalid` otherwise.
+ * Self-contained so the runner can inline it.
+ */
+export function admitAssetRef(raw: string): string {
+  function fail(): never {
+    const error = new Error('asset path is invalid') as Error & { code: string }
+    error.code = 'asset-invalid'
+    throw error
+  }
+  if (typeof raw !== 'string' || raw.length === 0) fail()
+  const slash = raw.replace(/\\/g, '/')
+  if (slash.startsWith('/') || /^[A-Za-z]:\//.test(slash)) fail()
+  const fromRoot = slash.startsWith('./') ? slash.slice(2) : slash
+  if (!fromRoot.startsWith('assets/')) fail()
+  const inner = fromRoot.slice('assets/'.length)
+  if (inner.length === 0 || inner.startsWith('/') || inner.startsWith('./') || inner.includes('..') || inner.includes('//')) fail()
+  const parts = inner.split('/')
+  const segment = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+  for (const part of parts) {
+    if (!segment.test(part)) fail()
+  }
+  const last = parts[parts.length - 1] ?? ''
+  const dot = last.lastIndexOf('.')
+  if (dot <= 0) fail()
+  const ext = last.slice(dot + 1).toLowerCase()
+  if (ext !== 'png' && ext !== 'jpg' && ext !== 'jpeg' && ext !== 'gif' && ext !== 'webp' && ext !== 'svg') fail()
+  return parts.join('/')
+}
+
+/** Admit the URL tail after `/assets/`. */
+export function admitAssetInner(raw: string): string {
+  return admitAssetRef(`assets/${raw}`)
+}
+
+/** Content type for an admitted inner path. */
+export function assetMediaType(inner: string): string {
+  const ext = inner.slice(inner.lastIndexOf('.') + 1).toLowerCase()
+  if (ext === 'png') return 'image/png'
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg'
+  if (ext === 'gif') return 'image/gif'
+  if (ext === 'webp') return 'image/webp'
+  return 'image/svg+xml'
+}

package/src/compile/autogen.ts

@@ -0,0 +1,71 @@
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { snapshotSkip } from '../files/skip.ts'
+import { bundleUi } from './bundle-ui.ts'
+
+/** Generated UI bundle and stylesheet. Snapshots and listings skip this name. */
+export const autogenDirName = '.autogen'
+
+const entryFile = 'entry.js'
+const sheetFile = 'ui.css'
+
+/**
+ * Freshness of the app sources. `.autogen` and other skipped names do not count.
+ * The same stamp invalidates the bundle and the stylesheet.
+ * @param appDir - absolute app directory
+ */
+export async function sourceStamp(appDir: string): Promise<string> {
+  let max = 0
+  let count = 0
+  const walk = async (dir: string): Promise<void> => {
+    const names = await readdir(dir).catch(() => [])
+    for (const name of names) {
+      if (snapshotSkip.has(name) || name === autogenDirName) continue
+      const file = path.join(dir, name)
+      const info = await stat(file).catch(() => undefined)
+      if (info === undefined) continue
+      if (info.isDirectory()) {
+        await walk(file)
+        continue
+      }
+      count += 1
+      if (info.mtimeMs > max) max = info.mtimeMs
+    }
+  }
+  await walk(appDir)
+  return `${max}-${count}`
+}
+
+/** Read one generated file when its stamp still matches the sources. */
+export async function readAutogen(appDir: string, file: string): Promise<string | undefined> {
+  const dir = path.join(appDir, autogenDirName)
+  const saved = await readFile(path.join(dir, `${file}.stamp`), 'utf8').catch(() => '')
+  if (saved !== await sourceStamp(appDir)) return undefined
+  return readFile(path.join(dir, file), 'utf8').catch(() => undefined)
+}
+
+/** Write one generated file and its stamp. A write failure does not change the returned body. */
+export async function writeAutogen(appDir: string, file: string, body: string): Promise<void> {
+  const dir = path.join(appDir, autogenDirName)
+  await mkdir(dir, { recursive: true })
+  const stamp = await sourceStamp(appDir)
+  await writeFile(path.join(dir, file), body)
+  await writeFile(path.join(dir, `${file}.stamp`), stamp)
+}
+
+/** Remove the generated directory. `cleanCaches` uses this for both files. */
+export async function purgeAutogen(appDir: string): Promise<void> {
+  await rm(path.join(appDir, autogenDirName), { recursive: true, force: true })
+}
+
+/** Bundle `ui.tsx`, or read `.autogen/entry.js` when the stamp matches. The bytes are not kept. */
+export async function cachedUiBundle(appDir: string): Promise<string> {
+  const hit = await readAutogen(appDir, entryFile)
+  if (hit !== undefined) return hit
+  const code = (await bundleUi(appDir)).code
+  await writeAutogen(appDir, entryFile, code).catch(() => undefined)
+  return code
+}
+
+export { sheetFile }