lecodes-cli 0.16.0 → 0.16.2

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "lecodes-cli",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "dependencies": {
-    "@letary/chisel": "^0.6.0",
+    "@letary/chisel": "^0.8.0",
     "jimp": "^1.6.1"
   },
   "devDependencies": {
@@ -10,12 +10,14 @@
     "lecodes-renderer": "workspace:*",
     "qrcode-terminal": "^0.12.0",
     "lecodes-3d-editor": "workspace:*",
+    "lecodes-assets": "workspace:*",
     "sdk": "workspace:*"
   },
   "peerDependencies": {
-    "lecodes-design": "^0.8.0",
-    "lecodes-renderer": "^0.8.3",
-    "lecodes-3d-editor": "^0.3.0"
+    "lecodes-design": "^0.8.1",
+    "lecodes-renderer": "^0.8.4",
+    "lecodes-3d-editor": "^0.3.0",
+    "lecodes-assets": "^0.1.0"
   },
   "bin": {
     "lecodes": "dist/index.js"
@@ -43,13 +45,16 @@
     },
     "lecodes-3d-editor": {
       "optional": true
+    },
+    "lecodes-assets": {
+      "optional": true
     }
   },
   "scripts": {
     "icon": "bun scripts/make-icon.ts",
     "vendor-runtime": "bun scripts/vendor-runtime.ts",
     "sync-peers": "bun scripts/sync-peer-versions.ts",
-    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --banner=\"#!/usr/bin/env node\"",
+    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --external lecodes-assets --banner=\"#!/usr/bin/env node\"",
     "build:bin": "bun scripts/build-bin.ts",
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/index.ts",

package/runtime/sdk/compile/bundler.ts

@@ -57,6 +57,12 @@ const CHISEL_DEFINE: Record<string, string> = { RAD2DEG: "57.29577951308232", DE
 // `_onAnimationComplete`, `_emitAnim`, …), so keep every underscore-prefixed method on classes that survive.
 const CHISEL_KEEP = [ "_*" ]
 
+/** The two inject modules (paths inside chisel's file map, see collectSdkFiles): the client SDK
+ *  (every UI/2D/3D global) and the server SDK (`t`, `model`, `defineDb`, `channel`, … — see
+ *  src/server/inject.ts). A bundle gets exactly one of them. */
+export const CLIENT_INJECT = "/__sdk/inject.ts"
+export const SERVER_INJECT = "/__sdk/server/inject.ts"
+
 /** The SDK source root (parent of `inject.ts`). chisel needs the source tree, not a prebuilt bundle. */
 const resolveSdkSrc = (): string => {
   const inject = resolveInject()
@@ -133,6 +139,7 @@ const bundleProjectChisel = async (
   minifyOverride?: boolean,
   editor?: boolean,
   libraries?: Record<string, MemoryFiles>,
+  inject: string = CLIENT_INJECT,
 ): Promise<{ code: string, map: string | null, diagnostics: string[] }> => {
   const entry = normalize(entrypoint)
   const slugs = new Set(Object.keys(libraries ?? {}))
@@ -176,7 +183,7 @@ const bundleProjectChisel = async (
   const input = JSON.stringify({
     files: { ...sdkFiles, ...projFiles },
     entry,
-    inject: [ "/__sdk/inject.ts" ],
+    inject: [ inject ],
     format,
     minify,
     // Chain fusion, ON by default (`LECODES_CHISEL_FUSE=0` opts out): Vec3/date math chains lower to
@@ -241,4 +248,5 @@ export const bundleProjectWithMap = async (
   editor?: boolean,
   libraries?: Record<string, MemoryFiles>,
   sourcemap = true,
-): Promise<{ code: string, map: string | null, diagnostics: string[] }> => bundleProjectChisel(entrypoint, files, format, sourcemap, minify, editor, libraries)
+  inject?: string,
+): Promise<{ code: string, map: string | null, diagnostics: string[] }> => bundleProjectChisel(entrypoint, files, format, sourcemap, minify, editor, libraries, inject)

package/runtime/sdk/compile/compileProject.ts

@@ -7,6 +7,7 @@ import { bundleProjectWithMap, scanModulesChisel, type MemoryFiles } from "./bun
 import { detectEntry } from "./detectEntry"
 import { buildHeader } from "./header"
 import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
+import { stubServerEntries } from "./serverSplit"
 
 export type CompileFileType = "text" | "resource" | "shader"
 
@@ -57,16 +58,23 @@ export type CompileOptions = {
    *  `/__lib/<slug>/…` and reachable from project code via `import … from "<slug>"`. See
    *  docs/library-system-plan.md §4. */
   libraries?: Record<string, MemoryFiles>
+  /** Base URL of the project's deployed server (draft or prod), baked into the RPC/channel stubs
+   *  that replace every `*.server.ts` module in the client bundle (docs/backend-plan.md §4). Server
+   *  files never reach the client bundle either way; with no URL, calling an endpoint fails with
+   *  "server not deployed". */
+  serverUrl?: string
 }
 
 export const compileProject = async (opts: CompileOptions): Promise<string> => {
-  const entry = opts.entryOverride ?? detectEntry(opts.entries, scanModulesChisel).entry
+  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
+  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
   if (!entry) {
     throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
   }
 
   const files: Record<string, string> = {}
-  for (const e of opts.entries) {
+  for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // The host resolves the asset by name at runtime (reads the local file → systemId); the

package/runtime/sdk/compile/detectEntry.ts

@@ -37,6 +37,9 @@ export type DetectedEntry = {
 export const ENTRY_CONVENTION = "/main.ts"
 
 const isCode = (path: string) => /\.[tj]s$/.test(path) && !path.endsWith(".d.ts")
+/** Never entries: editor plugins and server modules (docs/backend-plan.md — a `*.server.ts` nobody
+ *  imports is still not the app; server files compile into their own bundle). */
+const isNonEntry = (path: string) => path.endsWith(".editor.ts") || /\.server\.[tj]s$/.test(path)
 
 const normalize = (path: string): string => {
   const parts: string[] = []
@@ -87,7 +90,7 @@ export const scanModulesFallback = (files: Files): Record<string, ScanModule> =>
 
 /**
  * Detect the project's entrypoint. `entries` is the full project file list; only `.ts`/`.js` text
- * files participate (`.d.ts` and `.editor.ts` are never entries, and editor-only imports don't
+ * files participate (`.d.ts`, `.editor.ts` and `*.server.ts` are never entries, and editor-only imports don't
  * remove a file from candidacy — production compiles don't bundle editor plugins).
  */
 export const detectEntry = (entries: DetectEntryInput[], scanner?: ModuleScanner): DetectedEntry => {
@@ -99,7 +102,7 @@ export const detectEntry = (entries: DetectEntryInput[], scanner?: ModuleScanner
     if (isCode(path)) files[path] = e.text
   }
 
-  const candidates = Object.keys(files).filter((p) => !p.endsWith(".editor.ts"))
+  const candidates = Object.keys(files).filter((p) => !isNonEntry(p))
   if (candidates.length === 0) return { entry: "", roots: [] }
 
   const scan = scanner?.(files) ?? scanModulesFallback(files)

package/runtime/sdk/compile/index.ts

@@ -1,7 +1,23 @@
 // The public entry of the SDK's bundle build system. The backend, CLI, and local renderer import
 // from here instead of re-forking a bundler. (Node + Bun safe — no top-level host globals.)
 
-export { bundleProject, bundleProjectWithMap, scanModulesChisel, type MemoryFiles } from "./bundler"
+export { bundleProject, bundleProjectWithMap, scanModulesChisel, CLIENT_INJECT, SERVER_INJECT, type MemoryFiles } from "./bundler"
+export {
+  compileServerBundle,
+  scanServerExports,
+  scanServerModules,
+  stubServerEntries,
+  serverStubSource,
+  serverEntrySource,
+  serverModuleId,
+  isServerPath,
+  SERVER_ENTRY_PATH,
+  type CompileServerOptions,
+  type ServerExport,
+  type ServerExportKind,
+  type ServerManifest,
+} from "./serverSplit"
+export { deriveEndpointParams, EndpointTypeError, type DeriveResult } from "./serverTypes"
 export {
   detectEntry,
   scanModulesFallback,

package/runtime/sdk/compile/serverSplit.ts

@@ -0,0 +1,233 @@
+/**
+ * The client/server split of a project (docs/backend-plan.md §4).
+ *
+ * `*.server.ts` files never reach the client bundle: `compileProject` swaps each one for a STUB
+ * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__serverOnly` — client SDK
+ * globals, src/runtime/rpc.ts), so `import { listNotes } from "./notes.server"` in client code keeps
+ * its types and calls the server. `compileServerBundle` bundles the same files with the SERVER inject
+ * behind a synthetic entry that registers every module on `globalThis.__lecodesServer` (chisel keeps
+ * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
+ *
+ * Export kinds are found by a static scan (no TS program needed): a function export is an
+ * endpoint, a `channel(...)` export is a channel, anything else is server-only.
+ */
+
+import type { AppConfig } from "../server/auth/appConfig"
+import { bundleProjectWithMap, SERVER_INJECT, type MemoryFiles } from "./bundler"
+import type { CompileEntry } from "./compileProject"
+import { deriveEndpointParams } from "./serverTypes"
+
+export const SERVER_FILE = /\.server\.[tj]s$/
+export const isServerPath = (path: string) => SERVER_FILE.test(path)
+
+/** Project path → endpoint-id prefix: no leading `./` or `/`, forward slashes. */
+export const serverModuleId = (path: string) => path.split("\\").join("/").replace(/^(\.\/|\/)+/, "")
+
+export type ServerExportKind = "fn" | "channel" | "other"
+export type ServerExport = { name: string, kind: ServerExportKind }
+
+// ───────────────────────────── static export scan ─────────────────────────────
+
+/** Blank out comments and string/template contents (keeps line structure) so the regexes below don't
+ *  trip on `export` inside a comment or a string. */
+export const blankCommentsAndStrings = (src: string): string => {
+  let out = ""
+  let i = 0
+  const n = src.length
+  while (i < n) {
+    const c = src[i], d = src[i + 1]
+    if (c === "/" && d === "/") { while (i < n && src[i] !== "\n") { out += " "; i++ } continue }
+    if (c === "/" && d === "*") {
+      out += "  "; i += 2
+      while (i < n && !(src[i] === "*" && src[i + 1] === "/")) { out += src[i] === "\n" ? "\n" : " "; i++ }
+      out += "  "; i += 2; continue
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      const q = c
+      out += q; i++
+      while (i < n && src[i] !== q) {
+        if (src[i] === "\\") { out += "  "; i += 2; continue }
+        out += src[i] === "\n" ? "\n" : " "; i++
+      }
+      out += q; i++; continue
+    }
+    out += c; i++
+  }
+  return out
+}
+
+const IDENT = "[A-Za-z_$][\\w$]*"
+const classifyInit = (init: string): ServerExportKind => {
+  const s = init.trimStart()
+  if (/^channel\s*[<(]/.test(s)) return "channel"
+  if (/^(async\s+)?function\b/.test(s)) return "fn"
+  if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
+  if (new RegExp(`^${IDENT}\\s*=>`).test(s)) return "fn"           // x => …
+  if (/^\(/.test(s)) {
+    // `(a, b) => …` — find the matching paren and look for `=>` (a type annotation may sit between)
+    let depth = 0
+    for (let i = 0; i < s.length; i++) {
+      if (s[i] === "(") depth++
+      else if (s[i] === ")") { depth--; if (depth === 0) return /^\s*(:[^=]*)?=>/.test(s.slice(i + 1)) ? "fn" : "other" }
+    }
+  }
+  return "other"
+}
+
+/** Exported names of a server module with their kinds. Default exports are rejected. */
+export const scanServerExports = (source: string, path = "<server module>"): ServerExport[] => {
+  const src = blankCommentsAndStrings(source)
+  if (/(^|\n)\s*export\s+default\b/.test(src)) {
+    throw new Error(`${path}: default exports are not endpoints — use named exports`)
+  }
+  // (position, name, kind) — kept in source order so ids/manifests are stable and readable
+  const found: { at: number, name: string, kind: ServerExportKind }[] = []
+  const add = (at: number, name: string, kind: ServerExportKind) => {
+    const i = found.findIndex(f => f.name === name)
+    if (i >= 0) found[i] = { at: found[i].at, name, kind }
+    else found.push({ at, name, kind })
+  }
+  // export [async] function name / export function* name
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(async\\s+)?function\\s*\\*?\\s*(${IDENT})`, "g"))) add(m.index!, m[3], "fn")
+  // export const|let|var name [: T] = init
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(?:const|let|var)\\s+(${IDENT})\\s*(?::[^=]*?)?=\\s*([^\\n]*)`, "g"))) {
+    add(m.index!, m[2], classifyInit(m[3]))
+  }
+  // export class name → server-only
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+class\\s+(${IDENT})`, "g"))) add(m.index!, m[2], "other")
+  // export { a, b as c } → classify by the local declaration
+  for (const m of src.matchAll(/(^|\n)\s*export\s*\{([^}]*)\}/g)) {
+    for (const part of m[2].split(",")) {
+      const [local, exported] = part.split(/\s+as\s+/).map(s => s.trim())
+      if (!local || /^type\s/.test(local)) continue
+      const name = exported ?? local
+      let kind: ServerExportKind = "other"
+      if (new RegExp(`(^|\\n)\\s*(async\\s+)?function\\s*\\*?\\s*${local}\\b`).test(src)) kind = "fn"
+      else {
+        const decl = src.match(new RegExp(`(^|\\n)\\s*(?:const|let|var)\\s+${local}\\s*(?::[^=]*?)?=\\s*([^\\n]*)`))
+        if (decl) kind = classifyInit(decl[2])
+      }
+      add(m.index!, name, kind)
+    }
+  }
+  return found.sort((a, b) => a.at - b.at).map(({ name, kind }) => ({ name, kind }))
+}
+
+// ───────────────────────────── client stubs ─────────────────────────────
+
+/** The client-side replacement of a `*.server.ts` module. `serverUrl` is baked in (draft/prod are
+ *  separate compiles); "" means "no server deployed" — calls fail with a clear error. */
+export const serverStubSource = (path: string, exports: ServerExport[], serverUrl: string): string => {
+  const mod = serverModuleId(path)
+  const url = JSON.stringify(serverUrl)
+  const lines = exports.map(({ name, kind }) => {
+    const id = JSON.stringify(`${mod}#${name}`)
+    if (kind === "fn") return `export const ${name} = __rpc(${url}, ${id})`
+    if (kind === "channel") return `export const ${name} = __channel(${url}, ${id})`
+    return `export const ${name} = __serverOnly(${id})`
+  })
+  return `// client stub of ${mod} — generated by the lecodes compiler\n${lines.join("\n")}\n`
+}
+
+// ───────────────────────────── server entry ─────────────────────────────
+
+export const SERVER_ENTRY_PATH = "/.server-entry.ts"
+/** The SDK's app-config placeholder (src/server/auth/appConfig.ts) — the compile overrides it in the file map
+ *  with the project's real values (project files win over SDK files), so `auth.model.user()` and friends see
+ *  app.json as an ordinary import. */
+export const APP_CONFIG_PATH = "/__sdk/server/auth/appConfig.ts"
+
+/** Compile-time manifest embedded in the server bundle (validators land here — see serverTypes.ts). */
+export type ServerManifest = {
+  modules: Record<string, ServerExport[]>
+  /** endpoint id → JSON-schema-ish param list (filled by the TS-checker pass; absent = unvalidated). */
+  params?: Record<string, unknown[]>
+  /** The `app.json` subset the server runtime reads (name, auth providers); the bundle itself gets it as the
+   *  compiled-in `appConfig` module (APP_CONFIG_PATH). */
+  app?: AppConfig
+  /** Some server file references the `auth` global: the runner then resolves a device session on every
+   *  request (minting one on first contact). Projects that never touch `auth` pay nothing. */
+  usesAuth?: boolean
+}
+
+/** The synthetic entry: imports every export by name (chisel has no namespace imports) and registers
+ *  the module map + manifest on `globalThis.__lecodesServer` — a side effect chisel keeps. */
+export const serverEntrySource = (modules: Record<string, ServerExport[]>, manifest: ServerManifest): string => {
+  const imports: string[] = []
+  const entries: string[] = []
+  Object.entries(modules).forEach(([path, exports], i) => {
+    const names = exports.map(e => `${e.name} as m${i}_${e.name}`).join(", ")
+    if (names) imports.push(`import { ${names} } from ${JSON.stringify(path)}`)
+    else imports.push(`import ${JSON.stringify(path)}`)
+    const props = exports.map(e => `${JSON.stringify(e.name)}: m${i}_${e.name}`).join(", ")
+    entries.push(`${JSON.stringify(serverModuleId(path))}: { ${props} }`)
+  })
+  return `${imports.join("\n")}\n;(globalThis as any).__lecodesServer = { modules: { ${entries.join(", ")} }, manifest: ${JSON.stringify(manifest)} }\n`
+}
+
+const normalizePath = (path: string) => {
+  const parts: string[] = []
+  for (const part of path.split("\\").join("/").split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+/** Scan every `*.server.ts` entry → module path → exports. Throws on a default export. */
+export const scanServerModules = (entries: CompileEntry[]): Record<string, ServerExport[]> => {
+  const out: Record<string, ServerExport[]> = {}
+  for (const e of entries) {
+    if (e.type !== "text" || !isServerPath(e.path)) continue
+    out[normalizePath(e.path)] = scanServerExports(e.text ?? "", serverModuleId(e.path))
+  }
+  return out
+}
+
+/** Replace each `*.server.ts` entry with its client stub (returns a new entries array). */
+export const stubServerEntries = (entries: CompileEntry[], serverUrl: string): CompileEntry[] =>
+  entries.map(e => e.type === "text" && isServerPath(e.path)
+    ? { ...e, text: serverStubSource(e.path, scanServerExports(e.text ?? "", serverModuleId(e.path)), serverUrl) }
+    : e)
+
+export type CompileServerOptions = {
+  entries: CompileEntry[]
+  /** Derive per-endpoint argument validators from the TS parameter types (serverTypes.ts) and embed
+   *  them in the manifest. Default true; throws `EndpointTypeError` on non-JSON parameter types. */
+  validate?: boolean
+  /** Precomputed param schemas to embed instead of deriving them. */
+  params?: Record<string, unknown[]>
+  /** Server bundles are readable by default (stack traces in the server console). */
+  minify?: boolean
+  sourcemap?: boolean
+  /** The project's `app.json` (name + auth providers) — embedded in the manifest and exposed to the bundle. */
+  app?: AppConfig
+}
+
+/** Bundle the project's server side. Returns the code (a script that registers
+ *  `globalThis.__lecodesServer`) and the manifest; `null` when the project has no server files. */
+export const compileServerBundle = async (opts: CompileServerOptions): Promise<{ code: string, manifest: ServerManifest } | null> => {
+  const modules = scanServerModules(opts.entries)
+  if (Object.keys(modules).length === 0) return null
+  const files: MemoryFiles = {}
+  for (const e of opts.entries) {
+    if (e.type !== "text") continue
+    if (e.path.toLowerCase().endsWith(".svg")) continue
+    files[normalizePath(e.path)] = e.text ?? ""
+  }
+  let params = opts.params
+  if (!params && opts.validate !== false) {
+    const derived = await deriveEndpointParams(opts.entries, modules)
+    for (const w of derived.warnings) console.warn(`warning: ${w}`)
+    params = derived.params
+  }
+  const usesAuth = opts.entries.some(e => e.type === "text" && isServerPath(e.path) && /\bauth\s*\./.test(blankCommentsAndStrings(e.text ?? "")))
+  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app, usesAuth }
+  if (opts.app) files[APP_CONFIG_PATH] = `export const app = ${JSON.stringify(opts.app)}\n`
+  files[SERVER_ENTRY_PATH] = serverEntrySource(modules, manifest)
+  const { code } = await bundleProjectWithMap(
+    SERVER_ENTRY_PATH, files, "esm", opts.minify ?? false, false, undefined, opts.sourcemap ?? false, SERVER_INJECT,
+  )
+  return { code, manifest }
+}

package/runtime/sdk/compile/serverTypes.ts

@@ -0,0 +1,227 @@
+/**
+ * Endpoint parameter schemas from TypeScript types (docs/backend-plan.md §2.3 / §4.3).
+ *
+ * Endpoints are plain functions; their argument types are ordinary TS annotations. The client is not
+ * trusted, so the server validates every call — and rather than making developers write a schema
+ * twice, this pass runs the TypeScript checker over the project's `*.server.ts` files (in memory) and
+ * lowers each exported function's parameter types to the compact JSON schema `src/server/validate.ts`
+ * interprets at runtime. The result is embedded in the server bundle's manifest.
+ *
+ * Supported: primitives, literals, unions, enums, arrays, tuples, object types / interfaces / type
+ * aliases (from any project file), optional properties, index signatures (`Record<string, T>`),
+ * optional / defaulted / rest parameters, `any`/`unknown` (= accept anything). Rejected with a
+ * compile error: functions, classes with methods, `Date`, `Map`/`Set`, symbols, recursive types —
+ * "endpoint args must be JSON-serializable". Return types are not validated.
+ *
+ * `typescript` is loaded lazily (it's a devDependency of the SDK and a dependency of the platform
+ * compile step); the browser-safe parts of the compiler never import this module's runtime.
+ */
+
+import type { CompileEntry } from "./compileProject"
+import type { ParamSchema, Schema } from "../server/validate"
+import { serverModuleId, type ServerExport } from "./serverSplit"
+
+type TS = typeof import("typescript")
+
+const normalizePath = (path: string) => {
+  const parts: string[] = []
+  for (const part of path.split("\\").join("/").split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+export class EndpointTypeError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`endpoint args must be JSON-serializable:\n  ${problems.join("\n  ")}`)
+    this.name = "EndpointTypeError"
+    this.problems = problems
+  }
+}
+
+export type DeriveResult = {
+  /** endpoint id → parameter schemas (only endpoints the checker could see). */
+  params: Record<string, ParamSchema[]>
+  warnings: string[]
+}
+
+/**
+ * Derive `{ "<module>#<fn>": ParamSchema[] }` for every function export of every `*.server.ts` entry.
+ * Throws `EndpointTypeError` when a parameter type can't be validated at runtime.
+ */
+export const deriveEndpointParams = async (entries: CompileEntry[], modules: Record<string, ServerExport[]>): Promise<DeriveResult> => {
+  let ts: TS
+  try {
+    ts = (await import("typescript")).default ?? (await import("typescript")) as unknown as TS
+  } catch {
+    throw new Error("serverTypes: the `typescript` package is required to compile server endpoints")
+  }
+
+  const files = new Map<string, string>()
+  for (const e of entries) {
+    if (e.type !== "text" || typeof e.text !== "string") continue
+    if (!/\.[tj]sx?$/.test(e.path)) continue
+    files.set(normalizePath(e.path), e.text)
+  }
+  const roots = Object.keys(modules).map(normalizePath).filter(p => files.has(p))
+
+  const options: import("typescript").CompilerOptions = {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    allowImportingTsExtensions: true,
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true,
+    types: [],
+    lib: ["lib.es2022.d.ts"],
+  }
+  const defaultLibPath = ts.getDefaultLibFilePath(options).split("\\").join("/")
+  const defaultLibDir = defaultLibPath.slice(0, defaultLibPath.lastIndexOf("/"))
+  const sys = ts.sys
+  const host: import("typescript").CompilerHost = {
+    fileExists: p => files.has(normalizePath(p)) || (p.split("\\").join("/").startsWith(defaultLibDir) && sys.fileExists(p)),
+    readFile: p => files.get(normalizePath(p)) ?? (p.split("\\").join("/").startsWith(defaultLibDir) ? sys.readFile(p) : undefined),
+    getSourceFile: (p, lang) => {
+      const text = files.get(normalizePath(p)) ?? (p.split("\\").join("/").startsWith(defaultLibDir) ? sys.readFile(p) : undefined)
+      return text === undefined ? undefined : ts.createSourceFile(p, text, lang, true)
+    },
+    getDefaultLibFileName: o => ts.getDefaultLibFilePath(o),
+    writeFile: () => {},
+    getCurrentDirectory: () => "/",
+    getCanonicalFileName: p => p,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => "\n",
+    directoryExists: () => true,
+    getDirectories: () => [],
+  }
+  const program = ts.createProgram(roots, options, host)
+  const checker = program.getTypeChecker()
+
+  const params: Record<string, ParamSchema[]> = {}
+  const warnings: string[] = []
+  const problems: string[] = []
+
+  for (const [path, exports] of Object.entries(modules)) {
+    const sf = program.getSourceFile(normalizePath(path))
+    if (!sf) { warnings.push(`${path}: not in the TS program`); continue }
+    const modSym = checker.getSymbolAtLocation(sf)
+    if (!modSym) continue
+    const exported = new Map(checker.getExportsOfModule(modSym).map(s => [s.name, s]))
+    for (const ex of exports) {
+      if (ex.kind !== "fn") continue
+      const id = `${serverModuleId(path)}#${ex.name}`
+      let sym = exported.get(ex.name)
+      if (!sym) { warnings.push(`${id}: export not found by the checker — unvalidated`); continue }
+      if (sym.flags & ts.SymbolFlags.Alias) sym = checker.getAliasedSymbol(sym)
+      const decl = sym.valueDeclaration ?? sym.declarations?.[0]
+      if (!decl) { warnings.push(`${id}: no declaration — unvalidated`); continue }
+      const type = checker.getTypeOfSymbolAtLocation(sym, decl)
+      const sig = type.getCallSignatures()[0]
+      if (!sig) { warnings.push(`${id}: not callable — unvalidated`); continue }
+      const list: ParamSchema[] = []
+      for (const p of sig.getParameters()) {
+        const pd = p.valueDeclaration as import("typescript").ParameterDeclaration | undefined
+        const ptype = checker.getTypeOfSymbolAtLocation(p, pd ?? decl)
+        const rest = !!pd?.dotDotDotToken
+        const optional = !!pd?.questionToken || !!pd?.initializer || rest
+        try {
+          // `x?: T` carries `undefined` in its type — the optional flag covers it, strip it from the schema
+          const members = ptype.flags & ts.TypeFlags.Union ? (ptype as import("typescript").UnionType).types : [ptype]
+          const schema = lowerMembers(ts, checker, pd?.questionToken ? members.filter(t => !(t.flags & ts.TypeFlags.Undefined)) : members, `${id}(${p.name})`, new Set())
+          list.push({ name: p.name, schema, optional, rest })
+        } catch (e) {
+          problems.push((e as Error).message)
+        }
+      }
+      params[id] = list
+    }
+  }
+  if (problems.length) throw new EndpointTypeError(problems)
+  return { params, warnings }
+}
+
+// ───────────────────────────── type → schema ─────────────────────────────
+
+const lower = (ts: TS, checker: import("typescript").TypeChecker, type: import("typescript").Type, where: string, stack: Set<import("typescript").Type>): Schema => {
+  const f = type.flags
+  const T = ts.TypeFlags
+  if (f & (T.Any | T.Unknown)) return { t: "any" }
+  if (f & T.Never) throw new Error(`${where}: never`)
+  if (f & T.Null) return { t: "null" }
+  if (f & (T.Undefined | T.Void)) return { t: "undefined" }
+  if (f & T.BooleanLiteral) return { t: "lit", v: (type as any).intrinsicName === "true" }
+  if (f & T.Boolean) return { t: "boolean" }
+  if (f & T.StringLiteral) return { t: "lit", v: (type as import("typescript").StringLiteralType).value }
+  if (f & T.NumberLiteral) return { t: "lit", v: (type as import("typescript").NumberLiteralType).value }
+  if (f & T.String) return { t: "string" }
+  if (f & T.Number) return { t: "number" }
+  if (f & (T.BigInt | T.BigIntLiteral | T.ESSymbol | T.UniqueESSymbol)) throw new Error(`${where}: ${checker.typeToString(type)} is not JSON`)
+  if (f & T.EnumLiteral && f & T.Union) {
+    return { t: "union", of: (type as import("typescript").UnionType).types.map(t => lower(ts, checker, t, where, stack)) }
+  }
+  if (f & T.Union) return lowerMembers(ts, checker, (type as import("typescript").UnionType).types, where, stack)
+  if (f & T.Intersection || f & T.Object) {
+    if (stack.has(type)) throw new Error(`${where}: recursive type ${checker.typeToString(type)}`)
+    if (type.getCallSignatures().length || type.getConstructSignatures().length) throw new Error(`${where}: functions are not JSON`)
+    stack.add(type)
+    try {
+      if (checker.isArrayType(type)) {
+        const [el] = checker.getTypeArguments(type as import("typescript").TypeReference)
+        return { t: "array", of: el ? lower(ts, checker, el, where, stack) : { t: "any" } }
+      }
+      if (checker.isTupleType(type)) {
+        const ref = type as import("typescript").TypeReference
+        const target = ref.target as import("typescript").TupleType
+        const args = checker.getTypeArguments(ref)
+        const items: Schema[] = []
+        let rest: Schema | undefined
+        target.elementFlags.forEach((flag, i) => {
+          const s = lower(ts, checker, args[i], where, stack)
+          if (flag & ts.ElementFlags.Rest || flag & ts.ElementFlags.Variadic) rest = (s.t === "array" ? s.of : s)
+          else items.push(flag & ts.ElementFlags.Optional ? { t: "union", of: [s, { t: "undefined" }] } : s)
+        })
+        return { t: "tuple", items, rest }
+      }
+      const name = checker.typeToString(type)
+      if (/^(Date|Map<|Set<|WeakMap<|WeakSet<|Promise<|RegExp$|ArrayBuffer$|Uint8Array$)/.test(name)) throw new Error(`${where}: ${name} is not JSON`)
+      const props: Record<string, Schema> = {}
+      const optional: string[] = []
+      for (const p of checker.getPropertiesOfType(type)) {
+        const pt = checker.getTypeOfSymbolAtLocation(p, p.valueDeclaration ?? p.declarations?.[0]!)
+        if (pt.getCallSignatures().length) throw new Error(`${where}.${p.name}: functions are not JSON`)
+        const isOpt = !!(p.flags & ts.SymbolFlags.Optional)
+        // an optional property's type carries `undefined` — strip it, the optional list covers it
+        const members = pt.flags & T.Union ? (pt as import("typescript").UnionType).types : [pt]
+        props[p.name] = lowerMembers(ts, checker, isOpt ? members.filter(t => !(t.flags & T.Undefined)) : members, `${where}.${p.name}`, stack)
+        if (isOpt) optional.push(p.name)
+      }
+      let index: Schema | undefined
+      for (const info of checker.getIndexInfosOfType(type)) {
+        if (info.keyType.flags & T.String) index = lower(ts, checker, info.type, `${where}[string]`, stack)
+      }
+      return { t: "object", props, ...(optional.length ? { optional } : {}), ...(index ? { index } : {}) }
+    } finally {
+      stack.delete(type)
+    }
+  }
+  if (f & T.TypeParameter) throw new Error(`${where}: generic parameter ${checker.typeToString(type)} can't be validated`)
+  throw new Error(`${where}: unsupported type ${checker.typeToString(type)}`)
+}
+
+/** Lower a list of union members: `boolean` arrives as `true | false` — fold it back; a single member is itself. */
+const lowerMembers = (ts: TS, checker: import("typescript").TypeChecker, members: readonly import("typescript").Type[], where: string, stack: Set<import("typescript").Type>): Schema => {
+  const T = ts.TypeFlags
+  if (members.length === 1) return lower(ts, checker, members[0], where, stack)
+  const isLit = (m: import("typescript").Type, v: string) => !!(m.flags & T.BooleanLiteral) && (m as any).intrinsicName === v
+  const foldBool = members.some(m => isLit(m, "true")) && members.some(m => isLit(m, "false"))
+  const of: Schema[] = foldBool ? [{ t: "boolean" }] : []
+  for (const m of members) {
+    if (foldBool && m.flags & T.BooleanLiteral) continue
+    of.push(lower(ts, checker, m, where, stack))
+  }
+  return of.length === 1 ? of[0] : { t: "union", of }
+}