@mohou/host 1.0.20

package/src/compile/build-vendor-cli.ts

@@ -0,0 +1,8 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { buildVendorFiles } from './build-vendor.ts'
+
+const outDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../vendor')
+const written = await buildVendorFiles({ outDir })
+for (const file of written) console.log(file)

package/src/compile/build-vendor.ts

@@ -0,0 +1,160 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import * as esbuild from 'esbuild'
+
+import { platformModules, type PlatformModule } from './allowlist.ts'
+
+const require = createRequire(import.meta.url)
+
+/** Package directory the loopback server reads. Built at pack time, or once before listen if absent. */
+export function vendorOutputDir(): string {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '../../vendor')
+}
+
+/**
+ * Write one file per distinct `file` in the table. Rows that share a `file` are one build,
+ * from the first specifier. A `/*` row is not a vendor file. Does not mount a route.
+ * @param options - output directory and the table, defaulting to `platformModules`
+ * @returns paths written
+ */
+/** Bump when vendor transform contract changes so installed trees rebuild. */
+const VENDOR_STAMP = 'jsx-automatic-1'
+
+/** Build when a served file or the stamp is missing. A request never builds. */
+export async function ensureVendorFiles(outDir: string): Promise<void> {
+  const names = ['runtime.js', 'lodash.js', 'motion.js', 'sdk.js']
+  const stampPath = path.join(outDir, '.stamp')
+  const stampText = await readFile(stampPath, 'utf8').catch(() => '')
+  const stampOk = stampText.trim() === VENDOR_STAMP
+  if (stampOk && names.every(name => existsSync(path.join(outDir, name)))) return
+  await buildVendorFiles({ outDir })
+  await writeFile(stampPath, `${VENDOR_STAMP}
+`)
+}
+
+export async function buildVendorFiles(options: {
+  readonly outDir: string
+  readonly rows?: readonly PlatformModule[]
+}): Promise<string[]> {
+  const rows = options.rows ?? platformModules
+  const groups = new Map<string, string[]>()
+  for (const row of rows) {
+    if (row.file === undefined || row.specifier.includes('*')) continue
+    const list = groups.get(row.file) ?? []
+    list.push(row.specifier)
+    groups.set(row.file, list)
+  }
+  const written: string[] = []
+  for (const [file, specifiers] of groups) {
+    const dest = path.join(options.outDir, path.basename(file))
+    await mkdir(options.outDir, { recursive: true })
+    await writeFile(dest, await buildGroup(file, specifiers))
+    written.push(dest)
+  }
+  return written
+}
+
+async function buildGroup(file: string, specifiers: string[]): Promise<string> {
+  const first = specifiers[0]
+  if (first === undefined) throw new Error(`vendor produced no module: ${file}`)
+  const result = await esbuild.build({
+    stdin: {
+      contents: facade(file, specifiers),
+      resolveDir: path.dirname(require.resolve(first)),
+      sourcefile: path.basename(file),
+      loader: 'js',
+    },
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    // Packaged @mohou/ui has no tsconfig; without this, esbuild falls back to
+    // classic JSX (`React.createElement`) and leaves bare `React` unbound in the iframe.
+    jsx: 'automatic',
+    external: vendorExternals(file),
+    plugins: [workspacePackageExtensions()],
+    ...file.endsWith('/sdk.js') ? { banner: { js: sdkReactRequire } } : {},
+    write: false,
+  })
+  const code = result.outputFiles[0]?.text
+  if (code === undefined) throw new Error(`vendor produced no module: ${file}`)
+  return code
+}
+
+const sdkReactRequire = [
+  "import * as ReactNs from 'react'",
+  'const ReactMod = Object.assign({}, ReactNs.default, ReactNs)',
+  'const require = (id) => {',
+  "  if (id === 'react') return ReactMod",
+  "  throw new Error('Dynamic require of \"' + id + '\" is not supported')",
+  '}',
+].join('\n')
+
+function vendorExternals(file: string): string[] {
+  if (file.endsWith('/runtime.js')) return []
+  if (file.endsWith('/sdk.js')) return ['react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', 'motion', 'motion/react']
+  return ['react', 'react/jsx-runtime']
+}
+
+/**
+ * npm package exports map `@mohou/ui/*` → `./src/*` without a suffix.
+ * esbuild then looks for an extensionless file and fails outside the monorepo TS resolver.
+ */
+function workspacePackageExtensions(): esbuild.Plugin {
+  const scopes = ['@mohou/ui/', '@mohou/app-view/'] as const
+  return {
+    name: 'mini-app-package-extensions',
+    setup(build) {
+      build.onResolve({ filter: /^@mohou\/(ui|app-view)\// }, (args) => {
+        const scope = scopes.find(prefix => args.path.startsWith(prefix))
+        if (scope === undefined) return undefined
+        const pkgName = scope.slice(0, -1)
+        const sub = args.path.slice(scope.length)
+        let pkgRoot: string
+        try {
+          pkgRoot = path.dirname(require.resolve(`${pkgName}/package.json`))
+        } catch {
+          return undefined
+        }
+        for (const ext of ['.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.js']) {
+          const candidate = path.join(pkgRoot, 'src', `${sub}${ext}`)
+          if (existsSync(candidate)) return { path: candidate }
+        }
+        return undefined
+      })
+    },
+  }
+}
+
+function facade(file: string, specifiers: string[]): string {
+  if (file.endsWith('/runtime.js')) {
+    return [
+      "import React from 'react'",
+      "import { jsx, jsxs, Fragment } from 'react/jsx-runtime'",
+      "import { createPortal, flushSync, unstable_batchedUpdates } from 'react-dom'",
+      "import { createRoot, hydrateRoot } from 'react-dom/client'",
+      'export { jsx, jsxs, Fragment, createRoot, hydrateRoot, createPortal, flushSync, unstable_batchedUpdates }',
+      'export const {',
+      '  Children, Component, PureComponent, StrictMode, Suspense,',
+      '  cloneElement, createContext, createElement, createRef, forwardRef, isValidElement,',
+      '  lazy, memo, startTransition, use, useCallback, useContext, useDebugValue,',
+      '  useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect,',
+      '  useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, useTransition,',
+      '  version,',
+      '} = React',
+      'export default Object.assign({}, React, { createRoot, hydrateRoot, jsx, jsxs, Fragment })',
+    ].join('\n')
+  }
+  if (file.endsWith('/motion.js')) {
+    return "export * from 'motion'\nexport * from 'motion/react'\n"
+  }
+  const entry = specifiers.find(specifier => specifier.endsWith('-es')) ?? specifiers[0] ?? ''
+  const lines = [`export * from ${JSON.stringify(entry)}`]
+  if (specifiers.some(specifier => specifier === 'lodash' || specifier === 'lodash-es')) {
+    lines.push(`export { default } from ${JSON.stringify(entry)}`)
+  }
+  return `${lines.join('\n')}\n`
+}

package/src/compile/bundle-ui.ts

@@ -0,0 +1,137 @@
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { appEntries, ContractError } from '@mohou/contract'
+import * as esbuild from 'esbuild'
+
+import { platformBundled } from './allowlist.ts'
+import { CompileError } from './codes.ts'
+import { buildFailureText } from './failure.ts'
+import { importDecision, sideOf } from './imports.ts'
+
+const require = createRequire(import.meta.url)
+
+export interface UiBundle {
+  readonly code: string
+}
+
+/**
+ * Bundle `ui.tsx` in memory. React and motion stay external. Lodash is included. Component names are kept.
+ * A relative import whose real path leaves the app is `import-escape`.
+ * @param appDir - absolute app directory
+ * @param logLevel - `silent` when the caller already expects the build to fail. Omitted, esbuild prints the failure.
+ */
+export async function bundleUi(appDir: string, logLevel?: 'silent'): Promise<UiBundle> {
+  const stopped: { code: string; message: string } = { code: '', message: '' }
+  let result: esbuild.BuildResult
+  try {
+    result = await esbuild.build({
+      absWorkingDir: appDir,
+      entryPoints: [path.join(appDir, appEntries.ui)],
+      bundle: true,
+      format: 'esm',
+      platform: 'browser',
+      jsx: 'automatic',
+      keepNames: true,
+      write: false,
+      ...logLevel === undefined ? {} : { logLevel },
+      plugins: [uiPlugin(appDir, stopped)],
+    })
+  } catch (error) {
+    const code = stopped.code
+    if (code === 'import-forbidden' || code === 'import-escape') {
+      throw new ContractError(code, stopped.message, { cause: error })
+    }
+    const message = stopped.message || buildFailureText(error) || 'ui failed to bundle'
+    throw new CompileError('ui-invalid', message, { cause: error })
+  }
+  const code = result.outputFiles?.[0]?.text
+  if (code === undefined) throw new CompileError('ui-invalid', 'ui produced no bundle')
+  return { code }
+}
+
+function uiPlugin(appDir: string, stopped: { code: string; message: string }): esbuild.Plugin {
+  const root = realpathSync(appDir)
+  return {
+    name: 'mini-app-ui',
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind === 'entry-point') return undefined
+        if (args.importer.length > 0 && inside(root, args.importer) === undefined) return undefined
+        const importer = args.importer.length > 0 ? inside(root, args.importer) ?? appEntries.ui : appEntries.ui
+        if (args.path.startsWith('.')) {
+          const decision = importDecision(sideOf(importer), args.path, importer)
+          if (decision !== 'allow') {
+            const denied = typeof decision === 'object'
+              ? decision
+              : { code: 'import-forbidden' as const, message: `ui cannot import ${args.path}` }
+            stopped.code = denied.code
+            stopped.message = denied.message
+            return { errors: [{ text: stopped.message }] }
+          }
+          return resolveInside(root, args, stopped)
+        }
+        const decision = importDecision(sideOf(importer), args.path, importer)
+        if (decision === 'allow' && platformBundled(args.path)) {
+          try {
+            return { path: require.resolve(args.path) }
+          } catch (error) {
+            stopped.code = 'ui-invalid'
+            stopped.message = `ui cannot resolve ${args.path}`
+            return { errors: [{ text: stopped.message, detail: error }] }
+          }
+        }
+        if (decision === 'allow') return { path: args.path, external: true }
+        const denied = typeof decision === 'object'
+          ? decision
+          : { code: 'import-forbidden' as const, message: `ui cannot import ${args.path}` }
+        stopped.code = denied.code
+        stopped.message = denied.message
+        return { errors: [{ text: stopped.message }] }
+      })
+    },
+  }
+}
+
+function resolveInside(
+  root: string,
+  args: { path: string; importer: string },
+  stopped: { code: string; message: string },
+): esbuild.OnResolveResult {
+  const base = path.dirname(args.importer)
+  const target = path.resolve(base, args.path)
+  const real = resolveSourceFile(target)
+  if (real === undefined) {
+    stopped.code = 'ui-invalid'
+    stopped.message = `ui cannot resolve ${args.path}`
+    return { errors: [{ text: stopped.message }] }
+  }
+  const rel = path.relative(root, real)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    stopped.code = 'import-escape'
+    stopped.message = `ui cannot import ${args.path}`
+    return { errors: [{ text: stopped.message }] }
+  }
+  return { path: real }
+}
+
+/** Extensionless relative imports (templates often omit `.tsx`). */
+function resolveSourceFile(target: string): string | undefined {
+  const suffixes = ['', '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js']
+  for (const suffix of suffixes) {
+    try {
+      return realpathSync(`${target}${suffix}`)
+    } catch {
+      // try next
+    }
+  }
+  return undefined
+}
+
+function inside(root: string, file: string): string | undefined {
+  const real = realpathSync(file)
+  const rel = path.relative(root, real)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return undefined
+  return rel.split(path.sep).join('/')
+}

package/src/compile/codes.ts

@@ -0,0 +1,22 @@
+/** Codes the backend loader emits. Import checks still use the definition codes. */
+
+export const compileCodes = ['backend-invalid', 'ui-invalid', 'shared-invalid', 'event-undeclared'] as const
+
+/** A backend load failure. Callers match `code`. */
+export type CompileCode = (typeof compileCodes)[number]
+
+/** Failure while loading `main.api.ts`. The message is for a person. */
+export class CompileError extends Error {
+  readonly code: CompileCode
+
+  /**
+   * @param code - one of {@link compileCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause`
+   */
+  constructor(code: CompileCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'CompileError'
+    this.code = code
+  }
+}

package/src/compile/failure.ts

@@ -0,0 +1,38 @@
+import type * as esbuild from 'esbuild'
+
+/** Error lines one compile message carries. Host policy, not a locked number. */
+export const FAILURE_LINES_MAX = 5
+
+/**
+ * What esbuild said went wrong, one line per message. A resolve plugin names its own failures; this covers the rest.
+ * @param error - the value `esbuild.build` rejected with
+ */
+export function buildFailureText(error: unknown): string | undefined {
+  const errors = failureErrors(error)
+  if (errors.length === 0) return undefined
+  const lines = errors.slice(0, FAILURE_LINES_MAX).map(oneLine)
+  const hidden = errors.length - lines.length
+  if (hidden > 0) lines.push(`and ${hidden} more`)
+  return lines.join('\n')
+}
+
+function failureErrors(error: unknown): readonly esbuild.Message[] {
+  if (typeof error !== 'object' || error === null) return []
+  const found: unknown = 'errors' in error ? error.errors : undefined
+  if (!Array.isArray(found)) return []
+  return found.filter(isMessage)
+}
+
+function isMessage(value: unknown): value is esbuild.Message {
+  return typeof value === 'object'
+    && value !== null
+    && 'text' in value
+    && typeof value.text === 'string'
+    && value.text.length > 0
+}
+
+function oneLine(message: esbuild.Message): string {
+  const at = message.location
+  if (at === null) return message.text
+  return `${at.file}:${at.line}:${at.column}: ${message.text}`
+}

package/src/compile/imports.ts

@@ -0,0 +1,43 @@
+import { builtinModules } from 'node:module'
+
+import { appEntries, appTrees, classifyImport, type DefinitionCode, type ImportSide } from '@mohou/contract'
+
+import { platformModuleAllowed } from './allowlist.ts'
+
+const nodeBuiltins = new Set(builtinModules)
+
+export type ImportDecision =
+  | { readonly code: DefinitionCode; readonly message: string }
+  | 'allow'
+  | 'builtin'
+  | 'install'
+
+/** One decision for a specifier. The loader and the reload check both call this. */
+export function importDecision(side: ImportSide, specifier: string, fromFile = 'ui.tsx'): ImportDecision {
+  const crossed = classifyImport(specifier, side, fromFile)
+  if (crossed !== undefined) return { code: crossed, message: `${side} cannot import ${specifier}` }
+  if (specifier.startsWith('.')) return 'allow'
+  if (isNodeBuiltin(specifier)) {
+    if (side === 'backend') return 'builtin'
+    return { code: 'import-forbidden', message: `${side} cannot import ${specifier}` }
+  }
+  if (side !== 'shared' && platformModuleAllowed(specifier, side)) return 'allow'
+  if (inPlatformTable(specifier)) return { code: 'import-forbidden', message: `${side} cannot import ${specifier}` }
+  if (side === 'backend') return 'install'
+  return { code: 'import-forbidden', message: `${side} cannot import ${specifier}` }
+}
+
+export function sideOf(rel: string): ImportSide {
+  if (rel === appEntries.ui || rel.startsWith(`${appTrees.ui}/`)) return 'ui'
+  if (rel.startsWith(`${appTrees.shared}/`)) return 'shared'
+  return 'backend'
+}
+
+function inPlatformTable(specifier: string): boolean {
+  return platformModuleAllowed(specifier, 'ui') || platformModuleAllowed(specifier, 'backend')
+}
+
+function isNodeBuiltin(specifier: string): boolean {
+  const name = specifier.startsWith('node:') ? specifier.slice('node:'.length) : specifier
+  return nodeBuiltins.has(name)
+}

package/src/compile/leave.ts

@@ -0,0 +1,47 @@
+/**
+ * Runner guard for links and forms.
+ * A same-frame external URL would replace the app document. The sandbox does not stop that.
+ * `javascript:` still runs. A same-origin URL stays. `http` and `https` off this origin, and `mailto:`, open outside.
+ * An app script can remove the listeners. That is the same limit as the sandbox attribute.
+ */
+export function leaveGuardSource(): string {
+  return `function linkLeave(href, pageHref) {
+  let url
+  try {
+    url = new URL(href, pageHref)
+  } catch {
+    return 'block'
+  }
+  if (url.protocol === 'javascript:') return 'script'
+  if (url.protocol === 'mailto:') return 'mail'
+  const page = new URL(pageHref)
+  if (url.protocol === 'http:' || url.protocol === 'https:') {
+    return url.origin === page.origin ? 'stay' : 'browser'
+  }
+  return 'block'
+}
+document.addEventListener('click', (event) => {
+  if (event.defaultPrevented || event.button !== 0) return
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+  const node = event.target
+  if (!node || typeof node.closest !== 'function') return
+  const anchor = node.closest('a[href]')
+  if (!anchor) return
+  const target = (anchor.getAttribute('target') || '').toLowerCase()
+  if (target === '_blank') return
+  const leave = linkLeave(anchor.getAttribute('href') || '', location.href)
+  if (leave === 'stay' || leave === 'script') return
+  event.preventDefault()
+  if (leave === 'browser' || leave === 'mail') window.open(anchor.href, '_blank', 'noopener')
+}, true)
+document.addEventListener('submit', (event) => {
+  const form = event.target
+  if (!(form instanceof HTMLFormElement)) return
+  const target = (form.getAttribute('target') || '').toLowerCase()
+  if (target === '_blank') return
+  const leave = linkLeave(form.action, location.href)
+  if (leave === 'stay' || leave === 'script') return
+  event.preventDefault()
+  if (leave === 'browser' || leave === 'mail') window.open(form.action, '_blank', 'noopener')
+}, true)`
+}

package/src/compile/load-backend.ts

@@ -0,0 +1,95 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { appEntries, ContractError, type AppApiMethod } from '@mohou/contract'
+import * as esbuild from 'esbuild'
+
+import { CompileError } from './codes.ts'
+import { buildFailureText } from './failure.ts'
+import { importDecision, sideOf } from './imports.ts'
+
+const require = createRequire(import.meta.url)
+
+export interface LoadedBackend {
+  api: Record<string, AppApiMethod>
+}
+
+/**
+ * Transpile and load `main.api.ts`. `defineApp` is the real contract export.
+ * Installed libraries resolve only from this app's `node_modules`.
+ * @param appDir - absolute app directory
+ * @param logLevel - `silent` when the caller already expects the build to fail. Omitted, esbuild prints the failure.
+ */
+export async function loadBackend(appDir: string, logLevel?: 'silent'): Promise<LoadedBackend> {
+  const stopped: { code: string; message: string } = { code: '', message: '' }
+  let result: esbuild.BuildResult
+  try {
+    result = await esbuild.build({
+      absWorkingDir: appDir,
+      entryPoints: [path.join(appDir, appEntries.backend)],
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      write: false,
+      ...logLevel === undefined ? {} : { logLevel },
+      plugins: [allowlistPlugin(appDir, stopped)],
+    })
+  } catch (error) {
+    const code = stopped.code
+    if (code === 'import-forbidden' || code === 'import-escape') {
+      throw new ContractError(code, stopped.message, { cause: error })
+    }
+    const message = stopped.message || buildFailureText(error) || 'backend failed to load'
+    throw new CompileError('backend-invalid', message, { cause: error })
+  }
+  const output = result.outputFiles?.[0]?.text
+  if (output === undefined) throw new CompileError('backend-invalid', 'backend produced no module')
+  const loaded: unknown = await import(`data:text/javascript;base64,${Buffer.from(output).toString('base64')}`)
+  const app = isRecord(loaded) ? loaded.default : undefined
+  if (!isRecord(app) || !isRecord(app.api)) {
+    throw new CompileError('backend-invalid', 'backend must default-export defineApp(...)')
+  }
+  return { api: app.api as Record<string, AppApiMethod> }
+}
+
+function allowlistPlugin(appDir: string, stopped: { code: string; message: string }): esbuild.Plugin {
+  return {
+    name: 'mini-app-allowlist',
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind === 'entry-point' || args.importer.length === 0) return undefined
+        const rel = insideApp(appDir, args.importer)
+        if (rel === undefined) return undefined
+        const decision = importDecision(sideOf(rel), args.path, rel)
+        if (decision === 'builtin') return { path: args.path, external: true }
+        if (decision === 'allow') {
+          if (args.path.startsWith('.')) return undefined
+          return { path: require.resolve(args.path) }
+        }
+        if (decision === 'install') {
+          const local = path.join(appDir, 'node_modules', args.path)
+          if (existsSync(local)) return { path: local }
+          stopped.code = 'backend-invalid'
+          stopped.message = `install ${args.path} with mini_app_install`
+          return { errors: [{ text: stopped.message }] }
+        }
+        stopped.code = decision.code
+        stopped.message = decision.message
+        return { errors: [{ text: decision.message }] }
+      })
+    },
+  }
+}
+
+function insideApp(appDir: string, importer: string): string | undefined {
+  const root = realpathSync(appDir)
+  const file = realpathSync(path.isAbsolute(importer) ? importer : path.resolve(appDir, importer))
+  const rel = path.relative(root, file)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return undefined
+  return rel.split(path.sep).join('/')
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}