lecodes-cli 0.16.0 → 0.16.2

package/runtime/sdk/server/host.ts

@@ -0,0 +1,74 @@
+/**
+ * `sdk/server` — the HOST side of the app backend, imported normally by the runner
+ * (packages/lecodes-runner), the backend and tests. Nothing here is bundled into project code; the
+ * bundle carries its own SDK copy and meets this module only through the `globalThis.__lecodes*`
+ * seams (see ./runtime.ts).
+ */
+
+export {
+  loadServerModules, createInvoker, createJoinGuard, setChannelPublisher, setRequestProvider,
+} from "./runtime"
+export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration } from "./runtime"
+export type { RequestContext } from "./context"
+export { setDbTransport } from "./db/defineDb"
+export { marciHttpTransport, marciRequest, encodeMarciId, MarciHttpError } from "./db/httpTransport"
+export type { MarciHttpOptions } from "./db/httpTransport"
+export type { MarciOp, MarciTransport } from "./db/marci/query"
+export type { ServerManifest, ServerExport } from "../compile/serverSplit"
+export { validateArgs, ValidationError } from "./validate"
+export type { ParamSchema, Schema as ParamSchemaNode } from "./validate"
+export { createAuthHost, signNonce, verifyNonce, sha256 } from "./auth/host"
+export type { AuthHost, AuthHostConfig, AuthMail } from "./auth/host"
+export type { AuthUser, AuthState, AuthOps, OAuthProfile, OAuthCredential } from "./auth/types"
+export type { AuthProvider, AppConfig } from "./auth/appConfig"
+
+import type { LoadedServer } from "./runtime"
+import type { Field, FieldDef } from "./db/fields"
+import type { Model } from "./db/types"
+
+/** JSON view of one field for the platform (Data tab, docs): `FieldDef` with nested struct fields flattened
+ *  to defs and functions/undefineds dropped. */
+export type FieldDescription = Omit<FieldDef, "fields" | "default"> & { fields?: Record<string, FieldDescription>, default?: unknown }
+
+/** What the runner reports to the platform after loading a bundle: schema text + models + the
+ *  endpoint/channel lists (with the manifest's param schemas). */
+export type ServerDescription = {
+  /** `.marci` schema text ("" when the project defines no db). */
+  marci: string
+  models: Record<string, { fields: Record<string, FieldDescription> }>
+  endpoints: { id: string, params: unknown[] | null }[]
+  channels: string[]
+  /** Which models the auth runtime binds to (`null` = the project has no db) and the app.json providers. */
+  auth: { user: string | null, session: string | null, providers: string[] }
+  /** `app.json` name (when the compile embedded one). */
+  appName?: string
+}
+
+const describeField = (f: Field<any, any>): FieldDescription => {
+  const def = f.def
+  const out: FieldDescription = { ...def, fields: undefined, default: undefined }
+  delete out.fields
+  delete out.default
+  if (def.hasDefault) out.default = def.default === undefined ? null : def.default
+  if (def.fields) out.fields = Object.fromEntries(Object.entries(def.fields).map(([k, v]) => [k, describeField(v)]))
+  return JSON.parse(JSON.stringify(out))
+}
+
+export const describeServer = (server: LoadedServer): ServerDescription => {
+  const db = server.dbs[0]
+  const models: ServerDescription["models"] = {}
+  if (db) {
+    for (const [name, m] of Object.entries(db.$models as Record<string, Model>)) {
+      models[name] = { fields: Object.fromEntries(Object.entries(m.fields as Record<string, Field<any, any>>).map(([k, f]) => [k, describeField(f)])) }
+    }
+  }
+  const params = (server.manifest.params ?? {}) as Record<string, unknown[]>
+  return {
+    marci: db?.$schema ?? "",
+    models,
+    endpoints: [...server.endpoints.keys()].map(id => ({ id, params: params[id] ?? null })),
+    channels: [...server.channels.keys()],
+    auth: { user: db?.$auth.user ?? null, session: db?.$auth.session ?? null, providers: server.manifest.app?.auth?.providers ?? [] },
+    appName: server.manifest.app?.name,
+  }
+}

package/runtime/sdk/server/inject.ts

@@ -0,0 +1,13 @@
+/*
+ * The SERVER inject module — the globals available in `*.server.ts` files (docs/backend-plan.md §4).
+ * chisel injects these into the server bundle exactly like ./inject.ts does for the client bundle;
+ * nothing here may reach the client bundle. Keep this the ONLY file that exports server globals.
+ *
+ * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, request, auth.
+ */
+
+export { t, model, defineDb, ref } from "./db"
+export { ApiError } from "./errors"
+export { channel } from "./channel"
+export { request } from "./context"
+export { auth } from "./auth/global"

package/runtime/sdk/server/runtime.ts

@@ -0,0 +1,133 @@
+/**
+ * Host side of a compiled server bundle — used by the runner (packages/lecodes-runner) and by tests.
+ * Imported normally (Node/Bun), NOT through chisel: the bundle carries its own SDK copy and talks
+ * to this module only through globals (`__lecodesServer`, `__lecodesRequest`, `__lecodesPublish`).
+ *
+ *   evaluate the bundle (it sets globalThis.__lecodesServer)
+ *   const server = loadServerModules()          // classify exports, name channels
+ *   const invoke = createInvoker(server)        // validate → run in request context → envelope
+ *   await invoke("notes.server.ts#listNotes", [20], { headers, ip })
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { ServerManifest } from "../compile/serverSplit"
+import type { AuthHost } from "./auth/host"
+import type { AuthState } from "./auth/types"
+import { setChannelPublisher, type Channel } from "./channel"
+import { setRequestProvider, type RequestContext } from "./context"
+import type { Db } from "./db/types"
+import { takeRegisteredDbs } from "./db/defineDb"
+import { validateArgs, ValidationError, type ParamSchema } from "./validate"
+
+export type ServerRegistration = { modules: Record<string, Record<string, unknown>>, manifest: ServerManifest }
+
+export type LoadedServer = {
+  endpoints: Map<string, (...args: any[]) => unknown>
+  channels: Map<string, Channel<any>>
+  /** Every `defineDb` handle — exported or not (the bundle registers them on globalThis; normally exactly one). */
+  dbs: Db<any>[]
+  manifest: ServerManifest
+}
+
+const isDb = (v: unknown): v is Db<any> => typeof v === "object" && v !== null && typeof (v as Db<any>).$schema === "string"
+const isChannel = (v: unknown): v is Channel<any> => typeof v === "object" && v !== null && (v as Channel<any>).__channel === true
+
+/** Read the registration a server bundle left on `globalThis.__lecodesServer` (or a given one). */
+export const loadServerModules = (
+  reg: ServerRegistration | undefined = (globalThis as any).__lecodesServer,
+): LoadedServer => {
+  if (!reg) throw new Error("loadServerModules: no server bundle registered (globalThis.__lecodesServer)")
+  const out: LoadedServer = { endpoints: new Map(), channels: new Map(), dbs: [], manifest: reg.manifest }
+  for (const [mod, exports] of Object.entries(reg.modules)) {
+    for (const [name, value] of Object.entries(exports)) {
+      const id = `${mod}#${name}`
+      if (typeof value === "function") out.endpoints.set(id, value as (...args: any[]) => unknown)
+      else if (isChannel(value)) { value.__id = id; out.channels.set(id, value) }
+      else if (isDb(value)) out.dbs.push(value)
+    }
+  }
+  // Non-exported handles (`const db = defineDb(...)`): the bundle's SDK copy registered them on globalThis.
+  for (const db of takeRegisteredDbs()) if (!out.dbs.includes(db)) out.dbs.push(db)
+  return out
+}
+
+/** The wire envelope. `session` = a token the client must store from now on (new guest session / rotation). */
+export type InvokeResult =
+  | { ok: true, result: unknown, session?: string }
+  | { ok: false, status: number, message: string, session?: string }
+
+export type InvokerOptions = {
+  /** Validate args against the manifest's param schemas (default true; endpoints without a schema pass). */
+  validate?: boolean
+  /** Where unexpected (non-ApiError) failures are reported. Default: console.error. */
+  onError?: (id: string, error: unknown) => void
+  /** The auth host (./auth/host.ts): resolves the bearer token into `ctx.auth` before each call. Absent = no sessions. */
+  auth?: AuthHost | null
+}
+
+// The bundle's ApiError is a different class object than ours (its own SDK copy) — duck-type it.
+const apiStatus = (e: unknown): number | null =>
+  e && typeof e === "object" && (e as { name?: string }).name === "ApiError" && typeof (e as { status?: unknown }).status === "number"
+    ? (e as { status: number }).status : null
+
+/**
+ * Build the invoker: `invoke(id, args, ctx)` runs endpoint `id` inside an AsyncLocalStorage-scoped
+ * request context (what the `request`/`auth` globals read) and returns the wire envelope.
+ */
+// One request store for endpoints AND channel guards (a second store would steal the provider).
+const als = new AsyncLocalStorage<RequestContext>()
+const installProvider = () => setRequestProvider(() => als.getStore())
+
+// A token minted/rotated during the call rides on the envelope (the client transport stores it).
+const withSession = (r: InvokeResult, rc: RequestContext): InvokeResult => {
+  const issued = (rc.auth as AuthState | undefined)?.issuedToken
+  return issued ? { ...r, session: issued } : r
+}
+
+export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) => {
+  installProvider()
+  const validate = opts.validate ?? true
+  const onError = opts.onError ?? ((id, e) => console.error(`[server] ${id}:`, e))
+  const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
+  const auth = opts.auth ?? null
+
+  return async (id: string, args: unknown[], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
+    const fn = server.endpoints.get(id)
+    if (!fn) return { ok: false, status: 404, message: `Unknown endpoint ${id}` }
+    if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
+    const rc: RequestContext = { ...ctx, id }
+    try {
+      if (validate && params?.[id]) validateArgs(params[id], args)
+      if (auth) await auth.resolve(rc)
+      const result = await als.run(rc, () => fn(...args))
+      return withSession({ ok: true, result: result === undefined ? null : result }, rc)
+    } catch (e) {
+      const status = apiStatus(e)
+      if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
+      if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
+      onError(id, e)
+      return withSession({ ok: false, status: 500, message: "Internal error" }, rc)
+    }
+  }
+}
+
+/** Run a channel's `onJoin` guard for a subscription (same request scoping as endpoints). */
+export const createJoinGuard = (server: LoadedServer, opts: Pick<InvokerOptions, "auth"> = {}) => {
+  installProvider()
+  const auth = opts.auth ?? null
+  return async (channelId: string, topic: string, ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
+    const ch = server.channels.get(channelId)
+    if (!ch) return { ok: false, status: 404, message: `Unknown channel ${channelId}` }
+    const rc: RequestContext = { ...ctx, id: channelId }
+    try {
+      if (auth) await auth.resolve(rc)
+      await als.run(rc, () => ch.options.onJoin?.(topic))
+      return withSession({ ok: true, result: null }, rc)
+    } catch (e) {
+      const status = apiStatus(e)
+      return withSession({ ok: false, status: status ?? 500, message: status !== null ? (e as Error).message : "Internal error" }, rc)
+    }
+  }
+}
+
+export { setChannelPublisher, setRequestProvider }

package/runtime/sdk/server/validate.ts

@@ -0,0 +1,87 @@
+/**
+ * Runtime validation of endpoint arguments against the compact schemas the compiler derives from the
+ * TypeScript parameter types (src/compile/serverTypes.ts). Dependency-free; the schema is JSON so it
+ * travels inside the server bundle's manifest.
+ */
+
+export type Schema =
+  | { t: "any" }
+  | { t: "string" } | { t: "number" } | { t: "boolean" } | { t: "null" } | { t: "undefined" }
+  | { t: "lit", v: string | number | boolean }
+  | { t: "array", of: Schema }
+  | { t: "tuple", items: Schema[], rest?: Schema }
+  | { t: "object", props: Record<string, Schema>, optional?: string[], index?: Schema }
+  | { t: "union", of: Schema[] }
+
+/** One endpoint parameter: its schema and whether it may be omitted (`?`, default value, rest). */
+export type ParamSchema = { name: string, schema: Schema, optional?: boolean, rest?: boolean }
+
+export class ValidationError extends Error {
+  readonly status = 400
+  constructor(message: string) { super(message); this.name = "ValidationError" }
+}
+
+const typeName = (v: unknown) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v
+
+/** Returns the first problem as a message, or null when `value` matches. */
+export const check = (schema: Schema, value: unknown, path: string): string | null => {
+  switch (schema.t) {
+    case "any": return null
+    case "string": case "number": case "boolean":
+      return typeof value === schema.t ? null : `${path}: expected ${schema.t}, got ${typeName(value)}`
+    case "null": return value === null ? null : `${path}: expected null, got ${typeName(value)}`
+    case "undefined": return value === undefined ? null : `${path}: expected undefined, got ${typeName(value)}`
+    case "lit": return value === schema.v ? null : `${path}: expected ${JSON.stringify(schema.v)}, got ${JSON.stringify(value)}`
+    case "array":
+      if (!Array.isArray(value)) return `${path}: expected array, got ${typeName(value)}`
+      for (let i = 0; i < value.length; i++) { const e = check(schema.of, value[i], `${path}[${i}]`); if (e) return e }
+      return null
+    case "tuple": {
+      if (!Array.isArray(value)) return `${path}: expected tuple, got ${typeName(value)}`
+      if (value.length < schema.items.length || (!schema.rest && value.length > schema.items.length))
+        return `${path}: expected ${schema.items.length} items, got ${value.length}`
+      for (let i = 0; i < value.length; i++) {
+        const s = i < schema.items.length ? schema.items[i] : schema.rest!
+        const e = check(s, value[i], `${path}[${i}]`); if (e) return e
+      }
+      return null
+    }
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return `${path}: expected object, got ${typeName(value)}`
+      const obj = value as Record<string, unknown>
+      const optional = new Set(schema.optional ?? [])
+      for (const [k, s] of Object.entries(schema.props)) {
+        if (!(k in obj) || obj[k] === undefined) { if (optional.has(k)) continue; return `${path}.${k}: required` }
+        const e = check(s, obj[k], `${path}.${k}`); if (e) return e
+      }
+      for (const k of Object.keys(obj)) {
+        if (k in schema.props) continue
+        if (schema.index) { const e = check(schema.index, obj[k], `${path}.${k}`); if (e) return e }
+        // unknown keys without an index signature are ignored (structural typing)
+      }
+      return null
+    }
+    case "union": {
+      const errors: string[] = []
+      for (const s of schema.of) { const e = check(s, value, path); if (!e) return null; errors.push(e) }
+      return `${path}: no union member matched (${errors.join("; ")})`
+    }
+  }
+}
+
+/** Validate a positional argument list. Extra arguments are ignored (JS call semantics). */
+export const validateArgs = (params: ParamSchema[], args: unknown[]): void => {
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i]
+    if (p.rest) {
+      const rest = args.slice(i)
+      const e = check(p.schema, rest, p.name)
+      if (e) throw new ValidationError(e)
+      return
+    }
+    const v = args[i]
+    if (v === undefined) { if (p.optional) continue; throw new ValidationError(`${p.name}: required`) }
+    const e = check(p.schema, v, p.name)
+    if (e) throw new ValidationError(e)
+  }
+}