lecodes-cli 0.16.1 → 0.17.0

package/runtime/sdk/inject.ts

@@ -34,6 +34,9 @@ export { localStorage } from "./runtime/storage"
 export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
 export { Input } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
+// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
+// only ever imports its server functions (docs/backend-plan.md §4).
+export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 export { openFilePicker } from "./runtime/files"
 export { share } from "./runtime/share"
@@ -115,6 +118,7 @@ export { QRScanner } from "./plugins/qr"
 export { CameraView, type CameraFacing } from "./plugins/camera"
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
+export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
 export { Service } from "./plugins/service"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
@@ -139,6 +143,12 @@ export { Physics } from "./gl/Physics"
 export { Trigger } from "./gl/Trigger"
 export { CharacterController } from "./gl/CharacterController"
 export { ModelAnimation } from "./gl/ModelAnimation"
+export { AnimationClip } from "./gl/AnimationClip"
+export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/AnimationClip"
+export { Animator } from "./gl/Animator"
+export type { AnimatorPlayOptions } from "./gl/Animator"
+export { IK } from "./gl/IK"
+export type { IKTwoBone, IKLookAt } from "./gl/IK"
 export { Light } from "./gl/Light"
 export { Material } from "./gl/Material"
 export { Geometry } from "./gl/Geometry"

package/runtime/sdk/plugins/oauth.ts

@@ -0,0 +1,61 @@
+// OAuth — native provider sign-in as a typed service plugin (docs/backend-plan.md §3.4). The
+// browser broker (`auth.oauth.url()` on the server + `openURL` in the app) works everywhere; on
+// hosts that ship a provider SDK (Yandex LoginSDK, VK ID, Sign in with Apple, Google Sign-In) the
+// user shouldn't leave the app — the host registers an "oauth" service that runs the native sheet
+// and hands back the provider's CREDENTIAL. The app then calls its own endpoint, which does
+// `auth.oauth.signIn(provider, credential)`: the server verifies the credential with the provider
+// (audience = the platform's app ids) and binds the device session. No token is ever trusted
+// client-side; the credential is opaque to the app.
+//
+// Host-OPTIONAL — gate on `OAuth.isSupported(provider)`; fall back to the browser broker otherwise.
+//
+// Service contract ("oauth"): call `signIn(provider) → OAuthCredential` (rejects "cancelled" /
+// "unavailable"), call `providers() → string[]` (which providers this host has SDKs for).
+
+import { ServiceClient } from "../runtime/service"
+
+export type OAuthProviderName = "google" | "apple" | "yandex" | "vk"
+
+/** What a native provider SDK yields — pass it verbatim to your endpoint / `auth.oauth.signIn`. */
+export type OAuthCredential = {
+  provider: OAuthProviderName
+  /** OAuth access token (Yandex, VK ID). */
+  accessToken?: string
+  /** OpenID identity token (Google, Apple). */
+  idToken?: string
+  /** Apple only sends the name once, on the first sign-in — forward it so the server can store it. */
+  name?: string
+  email?: string
+}
+
+/**
+ * Native provider sign-in. `OAuth.isSupported` reports whether this host registered the service;
+ * `OAuth.providers()` which providers it has SDKs for. Otherwise open `auth.oauth.url(provider)` (server)
+ * with `openURL` — the browser broker.
+ */
+// PURE IIFE so an app that never uses it tree-shakes the plugin away (see Geolocation).
+export const OAuth: {
+  /** Whether this host registered an "oauth" service. */
+  readonly isSupported: boolean
+  /** The providers this host can sign in with natively. */
+  providers(): Promise<OAuthProviderName[]>
+  /** Run the provider's native sheet; resolves with the credential for `auth.oauth.signIn`. Rejects "cancelled" / "unavailable". */
+  signIn(provider: OAuthProviderName): Promise<OAuthCredential>
+} = /*#__PURE__*/ (() => {
+  let client: ServiceClient | null = null
+  const service = (): ServiceClient => client ??= new ServiceClient("oauth")
+  const assertSupported = (): void => {
+    if (!ServiceClient.isSupported("oauth")) {
+      throw new Error("OAuth isn't available on this host — it needs a registered \"oauth\" service; open auth.oauth.url(provider) in the browser instead.")
+    }
+  }
+  return {
+    get isSupported() { return ServiceClient.isSupported("oauth") },
+    providers: async () => { assertSupported(); const p = await service().call("providers"); return Array.isArray(p) ? p : [] },
+    signIn: async (provider) => {
+      assertSupported()
+      const r = await service().call("signIn", provider)
+      return { provider, ...(r ?? {}) }
+    },
+  }
+})()

package/runtime/sdk/runtime/rpc.ts

@@ -0,0 +1,218 @@
+/**
+ * Client transport for the app backend (docs/backend-plan.md §3.2 / §3.3). The compiler replaces
+ * every `*.server.ts` module in the client bundle with a stub whose exports are built by the three
+ * globals below — user code never calls them; it imports the server function and calls it.
+ *
+ *   export const listNotes = __rpc("<serverUrl>", "notes.server.ts#listNotes")
+ *   export const chat      = __channel("<serverUrl>", "chat.server.ts#chat")
+ *   export const db        = __serverOnly("schema.server.ts#db")
+ *
+ * Wire (implemented by the runner):
+ *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
+ *   WS   <serverUrl>/ws  frames: → {t:"hello",session} {t:"sub",id,ch,topic} {t:"unsub",id}
+ *                                ← {t:"session",session} {t:"ok",id} {t:"err",id,status,message} {t:"ev",ch,topic,event,data}
+ *   (`ev` is addressed by channel + topic, not by subscription id, so the server can fan one publish out
+ *   to every socket of a topic natively; the client delivers it to each matching subscription.)
+ *
+ * The session token is transport-owned (cookie-like): stored under `lecodes.session:<serverUrl>` in
+ * localStorage, sent on every call and on the socket, replaced whenever a response carries `session`.
+ * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
+ */
+
+import { fetch } from "./fetch"
+import { localStorage } from "./storage"
+import { WebSocket } from "./net"
+
+/** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
+ *  (0 = the request itself failed: no network / no server). */
+export class RpcError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = "RpcError"
+    this.status = status
+  }
+}
+
+// ───────────────────────────── session token ─────────────────────────────
+
+const sessionKey = (serverUrl: string) => `lecodes.session:${serverUrl}`
+const getSession = (serverUrl: string): string | null => {
+  try { return localStorage.getItem(sessionKey(serverUrl)) } catch { return null }
+}
+const setSession = (serverUrl: string, token: string | null) => {
+  try {
+    if (token) localStorage.setItem(sessionKey(serverUrl), token)
+    else localStorage.removeItem(sessionKey(serverUrl))
+  } catch { /* storage-less host: the session lives for this run only */ }
+  sockets.get(serverUrl)?.onSessionChanged(token)
+}
+
+// ───────────────────────────── endpoints ─────────────────────────────
+
+const noServer = (id: string) => new RpcError(0, `Endpoint ${id}: the project has no deployed server (compile with serverUrl)`)
+
+/** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
+export const __rpc = (serverUrl: string, id: string) => {
+  const call = async (...args: unknown[]): Promise<any> => {
+    if (!serverUrl) throw noServer(id)
+    const headers: Record<string, string> = { "content-type": "application/json" }
+    const session = getSession(serverUrl)
+    if (session) headers.authorization = `Bearer ${session}`
+    let res
+    try {
+      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: JSON.stringify({ args }) })
+    } catch (e) {
+      throw new RpcError(0, `Endpoint ${id}: request failed (${(e as Error)?.message ?? e})`)
+    }
+    let body: any
+    try { body = res.json() } catch { body = null }
+    res.dispose()
+    if (body && typeof body === "object" && "session" in body) setSession(serverUrl, body.session ?? null)
+    if (body && body.ok === true) return body.result
+    if (body && body.ok === false) throw new RpcError(body.status ?? res.status, body.message ?? "")
+    throw new RpcError(res.status, `Endpoint ${id}: unexpected response (HTTP ${res.status})`)
+  }
+  return call
+}
+
+/** A server-only export (db, models, helpers) referenced from client code: any use throws. */
+export const __serverOnly = (id: string): any =>
+  new Proxy(function () {} as any, {
+    get: (_t, prop) => { if (prop === "then") return undefined; throw new RpcError(0, `${id} is server-only — it can't be used in client code`) },
+    apply: () => { throw new RpcError(0, `${id} is server-only — it can't be used in client code`) },
+  })
+
+// ───────────────────────────── channels ─────────────────────────────
+
+type Handlers = Record<string, ((payload: any) => void) | undefined> & {
+  /** The socket dropped and came back: subscriptions were re-sent, but events in between are lost — refetch. */
+  reconnect?: () => void
+  /** The subscription was refused (`onJoin` threw) or the socket can't connect. */
+  error?: (e: RpcError) => void
+}
+type Sub = { id: number, ch: string, topic: string, handlers: Handlers, ready: boolean }
+
+const BACKOFF_MS = [1000, 2000, 5000, 10000, 30000]
+
+/** One multiplexed socket per server URL, shared by every channel of the app. */
+class ChannelSocket {
+  private ws: WebSocket | null = null
+  private open = false
+  private subs = new Map<number, Sub>()
+  private nextId = 1
+  private attempts = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private closedByUs = false
+  private everOpened = false
+  private serverUrl: string
+
+  constructor(serverUrl: string) { this.serverUrl = serverUrl }
+
+  subscribe(ch: string, topic: string, handlers: Handlers): { close(): void } {
+    const sub: Sub = { id: this.nextId++, ch, topic, handlers, ready: false }
+    this.subs.set(sub.id, sub)
+    if (this.open) this.send({ t: "sub", id: sub.id, ch, topic })
+    else this.connect()
+    return {
+      close: () => {
+        if (!this.subs.delete(sub.id)) return
+        if (this.open) this.send({ t: "unsub", id: sub.id })
+        if (this.subs.size === 0) this.shutdown()
+      },
+    }
+  }
+
+  onSessionChanged(token: string | null) {
+    if (this.open) this.send({ t: "hello", session: token })
+  }
+
+  private connect() {
+    if (this.ws || this.timer !== null) return
+    this.closedByUs = false
+    const url = this.serverUrl.replace(/^http/, "ws") + "/ws"
+    const session = getSession(this.serverUrl)
+    const ws = new WebSocket(url, session ? { authorization: `Bearer ${session}` } : undefined)
+    this.ws = ws
+    ws.addEventListener("open", () => {
+      this.open = true
+      this.attempts = 0
+      this.send({ t: "hello", session: getSession(this.serverUrl) })
+      const reconnected = this.everOpened
+      this.everOpened = true
+      for (const sub of this.subs.values()) {
+        sub.ready = false
+        this.send({ t: "sub", id: sub.id, ch: sub.ch, topic: sub.topic })
+        if (reconnected) sub.handlers.reconnect?.()
+      }
+    })
+    ws.addEventListener("message", (data) => {
+      if (typeof data !== "string") return
+      let msg: any
+      try { msg = JSON.parse(data) } catch { return }
+      this.onFrame(msg)
+    })
+    const onDown = () => {
+      if (this.ws !== ws) return
+      this.ws = null
+      this.open = false
+      if (this.closedByUs || this.subs.size === 0) return
+      const delay = BACKOFF_MS[Math.min(this.attempts++, BACKOFF_MS.length - 1)]
+      this.timer = setTimeout(() => { this.timer = null; this.connect() }, delay)
+    }
+    ws.addEventListener("close", onDown)
+    ws.addEventListener("error", onDown)
+  }
+
+  private onFrame(msg: any) {
+    switch (msg?.t) {
+      case "session": setSession(this.serverUrl, msg.session ?? null); break
+      case "ok": { const s = this.subs.get(msg.id); if (s) s.ready = true; break }
+      case "err": {
+        const s = this.subs.get(msg.id)
+        if (!s) break
+        this.subs.delete(msg.id)
+        s.handlers.error?.(new RpcError(msg.status ?? 0, msg.message ?? "subscription refused"))
+        break
+      }
+      case "ev": {
+        for (const s of this.subs.values()) {
+          if (s.ch === msg.ch && s.topic === msg.topic) s.handlers[msg.event]?.(msg.data)
+        }
+        break
+      }
+    }
+  }
+
+  private send(frame: unknown) { this.ws?.send(JSON.stringify(frame)) }
+
+  private shutdown() {
+    this.closedByUs = true
+    if (this.timer !== null) { clearTimeout(this.timer); this.timer = null }
+    this.ws?.close()
+    this.ws = null
+    this.open = false
+    sockets.delete(this.serverUrl)
+  }
+}
+
+const sockets = new Map<string, ChannelSocket>()
+const socketFor = (serverUrl: string) => {
+  let s = sockets.get(serverUrl)
+  if (!s) { s = new ChannelSocket(serverUrl); sockets.set(serverUrl, s) }
+  return s
+}
+
+export interface ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> {
+  /** Subscribe to `topic`; handlers are keyed by event name (+ `reconnect`/`error`). Returns `{ close }`. */
+  subscribe(topic: string, handlers: { [K in keyof E]?: (payload: E[K]) => void } & { reconnect?: () => void, error?: (e: RpcError) => void }): { close(): void }
+}
+
+/** Build the client proxy of channel `id`. */
+export const __channel = (serverUrl: string, id: string): ClientChannel<any> => ({
+  subscribe(topic, handlers) {
+    if (!serverUrl) throw noServer(id)
+    return socketFor(serverUrl).subscribe(id, topic, handlers as Handlers)
+  },
+})

package/runtime/sdk/server/auth/appConfig.ts

@@ -0,0 +1,12 @@
+/**
+ * The project's `app.json` subset the server runtime reads (name, auth providers).
+ *
+ * This module is a placeholder the COMPILER REPLACES: `compileServerBundle({ app })` puts a module with the
+ * real values at this same path in chisel's file map (project files win over SDK files), so every SDK module
+ * that imports `app` gets the project's config as a plain dependency — no globals, no evaluation-order games.
+ * Outside a compiled bundle (tests, tooling) `globalThis.__lecodesApp` can stand in.
+ */
+export type AuthProvider = "email" | "google" | "apple" | "yandex" | "vk"
+export type AppConfig = { name?: string, auth?: { providers?: AuthProvider[] } }
+
+export const app: AppConfig = {}

package/runtime/sdk/server/auth/global.ts

@@ -0,0 +1,80 @@
+/**
+ * The `auth` server global (docs/backend-plan.md §3.4) — the BUNDLE side. State (`auth.user`,
+ * `auth.session`) is read from the current request, which the host resolved before the endpoint ran;
+ * operations (`auth.email.*`, `auth.oauth.url`, `signIn/signOut`, `sessions`) forward to the host's
+ * `AuthOps` on `globalThis.__lecodesAuth` (a seam: the compiled bundle carries its own SDK copy). Nothing
+ * here touches the db or a secret; `auth.model.*` are pure schema factories.
+ */
+
+import { currentRequest, type RequestContext } from "../context"
+import type { Model, Query } from "../db/types"
+import { ApiError } from "../errors"
+import { authSessionModel, authUserModel, type AuthProvider, type SessionFields, type UserFields } from "./models"
+import type { AuthOps, AuthState, AuthUser, OAuthCredential } from "./types"
+
+const seam = globalThis as unknown as { __lecodesAuth?: AuthOps }
+const ops = (): AuthOps => {
+  const o = seam.__lecodesAuth
+  if (!o) throw new Error("auth: not available — the host did not install the auth runtime (globalThis.__lecodesAuth)")
+  return o
+}
+const ctx = (): RequestContext => {
+  const c = currentRequest()
+  if (!c) throw new Error("auth: no current request — auth.* is only available while handling an endpoint or a channel join")
+  return c
+}
+const state = (): AuthState => {
+  const c = ctx()
+  const s = c.auth as AuthState | undefined
+  if (!s) throw new Error("auth: this project has no database — sessions need a defineDb() (auth.model.* are optional, Session is added for you)")
+  return s
+}
+
+/** The schema of the two built-in models, for typing `auth.sessions` (developer extras aren't visible here). */
+type AuthSchema = { User: Model<UserFields>, Session: Model<SessionFields> }
+
+export const auth = {
+  /** The signed-in user (built-in fields; custom ones via `db.user`) or `null`. Request-scoped. */
+  get user(): AuthUser | null { return state().user },
+  /** The device session — exists from the first request, before any login. */
+  get session(): { readonly id: number } { return { id: state().sessionId } },
+  /**
+   * The signed-in user, or `throw new ApiError(401)`; with `match`, every given field must equal the user's
+   * (`{ role: "admin" }`, `{ plan: "pro" }`) or it's a 403.
+   */
+  requireUser(match?: Record<string, unknown>): AuthUser {
+    const u = state().user
+    if (!u) throw new ApiError(401, "Sign in required")
+    if (match) for (const [k, v] of Object.entries(match)) if ((u as Record<string, unknown>)[k] !== v) throw new ApiError(403, "Forbidden")
+    return u
+  },
+  email: {
+    /** Emails a 6-digit code to `email` (always resolves — no "email exists" oracle; rate-limited). Needs `"email"` in app.json providers. */
+    sendCode: (email: string): Promise<void> => ops().email.sendCode(ctx(), email),
+    /** The only email sign-in: checks the code sent to this device session, finds/creates the `User`, binds the session. */
+    verify: (email: string, code: string): Promise<AuthUser> => ops().email.verify(ctx(), email, code),
+  },
+  oauth: {
+    /** A one-time sign-in URL for the platform's OAuth broker (`"google" | "apple" | "yandex" | "vk"`), bound to this device session — open it in the browser. */
+    url: (provider: Exclude<AuthProvider, "email">): Promise<string> => ops().oauth.url(ctx(), provider),
+    /**
+     * Sign in with a credential a NATIVE provider SDK produced in the app (client `OAuth.signIn(provider)`):
+     * the platform verifies it with the provider, finds/links/creates the `User`, binds this session. The
+     * in-app counterpart of the browser broker — same accounts either way.
+     */
+    signIn: (provider: Exclude<AuthProvider, "email">, credential: OAuthCredential): Promise<AuthUser> => ops().oauth.signIn(ctx(), provider, credential),
+  },
+  /** Escape hatch for developer-verified identities (Telegram initData, SSO): binds this session to `userId`. */
+  signIn: (userId: number): Promise<AuthUser> => ops().signIn(ctx(), userId),
+  /** Unbinds the user; the device stays a guest with the same `session.id` (token rotated). */
+  signOut: (): Promise<void> => ops().signOut(ctx()),
+  /** The current user's sessions ("my devices"): a `db.session` query — `await`, `.select()`, `.where(...).updateMany({ revoked: true })`. */
+  get sessions(): Query<AuthSchema, "Session"> { return ops().sessions(ctx()) },
+  /** Schema-time factories — see ./models.ts. */
+  model: {
+    user: authUserModel,
+    session: authSessionModel,
+  },
+}
+
+export type { AuthUser }