@tourik/yeet 0.0.0-stage → 0.1.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thanos Tourikas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# yeet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+yeet hosts small apps that AI agents build, deploy and check on their own. An app is one folder
+of TypeScript: a server with a database, sign-in and live queries, and a React page. This package
+holds the `yeet` command and the SDK that apps import.
+
+## Start an app
+
+```sh
+npx @tourik/yeet init notes
+cd notes
+npx yeet dev
+```
+
+- `yeet init notes` creates the folder `notes` with a small todo app in it: a table, a search, a
+  query, two mutations and a React page. It installs the app's npm packages and starts a git
+  repository. `notes` is also the app's id, which names it on the server.
+- The app's `package.json` holds this package under the name `yeet`. So the app imports
+  `yeet/server` and `yeet/react`, and `npx yeet` runs the command.
+- `yeet dev` serves the app at the address it prints, and reloads on every save. It starts on an
+  empty database and deletes it when it stops.
+
+Then open your coding agent in the folder and describe the app you want. `yeet init` wrote
+`AGENTS.md`, which tells the agent how to write, run, check and deploy a yeet app, and a
+`CLAUDE.md` that points Claude Code at it. `npx yeet agents-md` rewrites yeet's part of
+`AGENTS.md` after an update.
+
+Without a name, `yeet init` starts the app in the current folder, under the folder's name. It
+keeps every file that is already there. If it kept a `package.json`, it prints the `npm install`
+command for the packages that file lacks.
+
+## What an app looks like
+
+```
+server/index.ts    the tables, and the functions that clients call
+client/            the web page: index.html, index.tsx, index.css, public/
+shared/            TypeScript that both import
+yeet.json          the app's id
+```
+
+The server, in `server/index.ts`:
+
+```ts
+import { defineSchema, defineTable, mutation, query, v } from "yeet/server";
+
+export default defineSchema({
+  todos: defineTable({ owner: v.union(v.string(), v.null()), text: v.string() })
+    .index("by_owner", ["owner"]),
+});
+
+export const todos = query({
+  handler: (ctx) =>
+    ctx.db.query("todos").withIndex("by_owner", (q) => q.eq("owner", ctx.auth.userId)).collect(),
+});
+
+export const addTodo = mutation({
+  args: { text: v.string() },
+  handler: (ctx, { text }) => ctx.db.insert("todos", { owner: ctx.auth.userId, text }),
+});
+```
+
+The page, in `client/index.tsx`:
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { useMutation, useQuery, YeetProvider } from "yeet/react";
+
+declare module "yeet/react" {
+  interface Register {
+    server: typeof import("../server/index");
+  }
+}
+
+function Todos() {
+  const todos = useQuery("todos");
+  const addTodo = useMutation("addTodo");
+  if (todos === undefined) return <p>Loading…</p>;
+  return (
+    <>
+      <button onClick={() => addTodo({ text: "Buy milk" })}>Add</button>
+      <ul>
+        {todos.map((todo) => (
+          <li key={todo._id}>{String(todo.text)}</li>
+        ))}
+      </ul>
+    </>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(
+  <YeetProvider>
+    <Todos />
+  </YeetProvider>,
+);
+```
+
+`useQuery` keeps its result up to date: when a mutation changes what a query read, every open
+page gets the new result.
+
+## The server API
+
+The API resembles Convex's, but it is its own. `server.d.ts` in this package declares all of it.
+
+- A `query` only reads. A `mutation` reads and writes in one transaction. An `action` can `fetch`
+  and wait, and reaches the data through `ctx.runQuery` and `ctx.runMutation`.
+- `ctx.auth.userId` is the signed-in user's id, or `null`.
+- Tables can have indexes and text search. Functions can run later (`ctx.scheduler`) or on a
+  timetable (`cronJobs()`). An app can answer plain HTTP under `/api/` (`httpRouter()`).
+- Server code imports only `yeet/server` and its own files: no npm package. It runs in neither
+  Node nor a browser, so `crypto`, `TextEncoder`, `btoa` and `Buffer` do not exist. Client code
+  can import npm packages.
+- There is no `v.any()`, `.filter()`, `.paginate()` or `ctx.auth.getUserIdentity()`: `yeet check`
+  reports each use with its line.
+
+## Commands
+
+Every command takes `--json`, and `npx yeet --help` lists them all.
+
+| Command | What it does |
+|---|---|
+| `yeet init [name]` | Starts a new app, in the new folder `<name>` or in the current one |
+| `yeet dev` | Serves the app locally, on an empty database |
+| `yeet run <name> '<json args>' --port <port>` | Calls a function on a running `yeet dev` |
+| `yeet logs --port <port> --errors` | Shows the calls that failed, with their arguments |
+| `yeet check` | Checks the types, the build, and the new code on a copy of the live data |
+| `yeet deploy` | Builds the app and makes it live |
+| `yeet deploy --preview <name>` | Serves the code at its own address, on a copy of the live data |
+| `yeet status`, `yeet logs` | Show the deployed app |
+| `yeet rollback` | Brings back the previous deploy |
+| `yeet login` | Logs in through the browser |
+| `yeet mcp` | Serves the main commands to an agent as MCP tools |
+
+## Deploying
+
+- Without a login, `npx yeet deploy` creates an unclaimed app at a random address under
+  `yeet.tourik.dev`. It expires 7 days after its last deploy, and it cannot `fetch` or keep
+  secrets.
+- With an account, `npx yeet login` and then `npx yeet deploy` serve the app at
+  `https://<id>.yeet.tourik.dev`. `npx yeet claim` gives an unclaimed app to your account.
+- Each deployed app has its own database. `npx yeet access` shows and sets who may sign in to it.
+
+## License
+
+MIT

package/bin/yeet.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Runs the yeet binary of the package for this computer, which npm installed as an optional
+// dependency of @tourik/yeet.
+const { spawn } = require("node:child_process");
+
+const targets = Object.keys(require("../package.json").optionalDependencies).map((name) =>
+  name.slice("@tourik/yeet-".length),
+);
+const target = `${process.platform}-${process.arch}`;
+let binary;
+try {
+  binary = require.resolve(`@tourik/yeet-${target}/bin/yeet`);
+} catch {
+  console.error(
+    targets.includes(target)
+      ? `the package @tourik/yeet-${target} is not installed; install again without --omit=optional, or without a package-lock.json made on another computer`
+      : `yeet has no build for ${target}; it runs on ${targets.join(", ")}`,
+  );
+  process.exit(1);
+}
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => child.kill(signal));
+}
+child.on("error", (error) => {
+  console.error(`cannot run ${binary}: ${error.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (code !== null) process.exit(code);
+  process.removeAllListeners(signal);
+  process.kill(process.pid, signal);
+});

package/client.ts

@@ -0,0 +1,272 @@
+import type { Value } from "./server";
+
+export type Args = Record<string, Value>;
+
+export type QueryState = { value: unknown } | { error: Error };
+
+export interface AuthState {
+  readonly isLoading: boolean;
+  readonly userId: string | null;
+}
+
+interface Subscription {
+  id: number;
+  name: string;
+  args: Args;
+  state: QueryState | undefined;
+  listeners: Set<() => void>;
+}
+
+interface PendingMutation {
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+}
+
+type ServerMessage =
+  | { type: "result"; id: number; value: unknown; version: number }
+  | { type: "mutated"; id: number; value: unknown; version: number }
+  | { type: "error"; id: number | null; message: string }
+  | { type: "auth"; userId: string | null }
+  | { type: "client"; build: string }
+  | { type: "reload" };
+
+const MAX_RECONNECT_DELAY_MS = 5000;
+
+function sortedKeys(value: Value | undefined): Value | undefined {
+  if (Array.isArray(value)) return value.map(sortedKeys) as Value[];
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortedKeys(value[key])]));
+}
+
+/** React Native's WebSocket, which takes headers as a third argument; browsers ignore it. */
+type NativeWebSocket = new (
+  url: string,
+  protocols: string | string[] | undefined,
+  options: { headers: Record<string, string> },
+) => WebSocket;
+
+interface Listening {
+  addEventListener(type: string, listener: () => void, options: { once: boolean }): void;
+}
+
+/**
+ * The browser globals the client uses, typed here because React Native's TypeScript setup has no
+ * browser types.
+ */
+interface Page extends Listening {
+  readonly document: Listening & { readonly hidden: boolean; hasFocus(): boolean };
+  readonly location: { readonly protocol: string; readonly host: string; reload(): void };
+}
+
+/** The web page the client runs on, which reloads after a deploy, or undefined in a phone app. */
+export function page() {
+  return "document" in globalThis ? (globalThis as unknown as Page) : undefined;
+}
+
+/** Reloads the page at once when the user is not on it, or else as soon as they leave it. */
+function reloadWhenLeft(web: Page) {
+  if (web.document.hidden || !web.document.hasFocus()) return web.location.reload();
+  const reload = () => web.location.reload();
+  web.addEventListener("blur", reload, { once: true });
+  web.document.addEventListener("visibilitychange", reload, { once: true });
+}
+
+export function queryKey(name: string, args: Args) {
+  return `${name}:${JSON.stringify(sortedKeys(args))}`;
+}
+
+/**
+ * One WebSocket to a yeet app, shared by every query and mutation of a page. It is open while
+ * anything listens to a query or to the sign-in state.
+ */
+export class YeetClient {
+  private socket: WebSocket | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  private listeners = 0;
+  private nextId = 1;
+  private reconnectAttempts = 0;
+  private readonly subscriptions = new Map<string, Subscription>();
+  private readonly pending = new Map<number, PendingMutation>();
+  private auth: AuthState = { isLoading: true, userId: null };
+  private build: string | undefined;
+  private readonly authListeners = new Set<() => void>();
+
+  /**
+   * `url` is the app's WebSocket, such as `wss://wovies.yeet.tourik.dev/sync`. A phone app passes
+   * the `token` from `yeet/sign-in`; a web page signs in with its cookie instead.
+   */
+  constructor(
+    private readonly url: string,
+    private readonly token?: string,
+  ) {}
+
+  subscribe(name: string, args: Args, listener: () => void): () => void {
+    const key = queryKey(name, args);
+    let subscription = this.subscriptions.get(key);
+    if (subscription === undefined) {
+      subscription = { id: this.nextId++, name, args, state: undefined, listeners: new Set() };
+      this.subscriptions.set(key, subscription);
+      this.sendSubscribe(subscription);
+    }
+    subscription.listeners.add(listener);
+    const subscribed = subscription;
+    const release = this.hold();
+    return () => {
+      subscribed.listeners.delete(listener);
+      if (subscribed.listeners.size === 0) {
+        this.subscriptions.delete(key);
+        this.send({ type: "unsubscribe", id: subscribed.id });
+      }
+      release();
+    };
+  }
+
+  queryState(name: string, args: Args): QueryState | undefined {
+    return this.subscriptions.get(queryKey(name, args))?.state;
+  }
+
+  /** Resolves once the mutation committed, after every subscribed query shows its writes. */
+  mutation(name: string, args: Args): Promise<unknown> {
+    return this.request("mutate", name, args);
+  }
+
+  /** Resolves with the action's value once it finished. */
+  action(name: string, args: Args): Promise<unknown> {
+    return this.request("call", name, args);
+  }
+
+  authState(): AuthState {
+    return this.auth;
+  }
+
+  onAuthChange(listener: () => void): () => void {
+    this.authListeners.add(listener);
+    const release = this.hold();
+    return () => {
+      this.authListeners.delete(listener);
+      release();
+    };
+  }
+
+  /**
+   * Closes the WebSocket and opens a new one at once, even when the old one still looks open,
+   * as it may after the device slept. Queries subscribe again; a mutation in flight fails.
+   */
+  reconnect() {
+    if (this.listeners === 0) return;
+    this.disconnect();
+    this.connect();
+  }
+
+  private hold() {
+    if (this.listeners++ === 0 && this.socket === null) this.connect();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.listeners--;
+      // React StrictMode unsubscribes and subscribes again right away; closing in between would
+      // open a second socket for nothing.
+      void Promise.resolve().then(() => {
+        if (this.listeners === 0) this.disconnect();
+      });
+    };
+  }
+
+  private connect() {
+    clearTimeout(this.reconnectTimer);
+    const socket =
+      this.token === undefined
+        ? new WebSocket(this.url)
+        : new (WebSocket as unknown as NativeWebSocket)(this.url, undefined, {
+            headers: { Authorization: `Bearer ${this.token}` },
+          });
+    this.socket = socket;
+    socket.onopen = () => {
+      this.reconnectAttempts = 0;
+      for (const subscription of this.subscriptions.values()) this.sendSubscribe(subscription);
+    };
+    socket.onmessage = (event) => this.receive(JSON.parse(event.data as string) as ServerMessage);
+    socket.onclose = () => {
+      this.dropConnection();
+      const delay = Math.min(250 * 2 ** this.reconnectAttempts++, MAX_RECONNECT_DELAY_MS);
+      this.reconnectTimer = setTimeout(() => this.connect(), delay);
+    };
+  }
+
+  private disconnect() {
+    clearTimeout(this.reconnectTimer);
+    this.reconnectAttempts = 0;
+    if (this.socket === null) return;
+    this.socket.onclose = null;
+    this.socket.close();
+    this.dropConnection();
+  }
+
+  private dropConnection() {
+    this.socket = null;
+    for (const mutation of this.pending.values()) {
+      mutation.reject(new Error("connection lost before the server replied; the call may have run"));
+    }
+    this.pending.clear();
+  }
+
+  private receive(message: ServerMessage) {
+    switch (message.type) {
+      case "result":
+        if (this.pending.has(message.id)) return this.settle(message.id)?.resolve(message.value);
+        return this.setQueryState(message.id, { value: message.value });
+      case "mutated":
+        return this.settle(message.id)?.resolve(message.value);
+      case "error":
+        if (message.id === null) return console.error(`yeet: ${message.message}`);
+        if (this.pending.has(message.id)) return this.settle(message.id)?.reject(new Error(message.message));
+        return this.setQueryState(message.id, { error: new Error(message.message) });
+      case "auth":
+        this.auth = { isLoading: false, userId: message.userId };
+        for (const listener of this.authListeners) listener();
+        return;
+      case "client":
+        if (this.build === undefined) this.build = message.build;
+        else if (message.build !== this.build) {
+          const web = page();
+          if (web) reloadWhenLeft(web);
+        }
+        return;
+      case "reload":
+        page()?.location.reload();
+        return;
+    }
+  }
+
+  private request(type: "mutate" | "call", name: string, args: Args): Promise<unknown> {
+    if (this.socket?.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error(`cannot run ${name}: not connected to the server`));
+    }
+    const id = this.nextId++;
+    this.send({ type, id, name, args });
+    return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
+  }
+
+  private settle(id: number) {
+    const mutation = this.pending.get(id);
+    this.pending.delete(id);
+    return mutation;
+  }
+
+  private setQueryState(id: number, state: QueryState) {
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.id !== id) continue;
+      subscription.state = state;
+      for (const listener of subscription.listeners) listener();
+    }
+  }
+
+  private sendSubscribe({ id, name, args }: Subscription) {
+    this.send({ type: "subscribe", id, name, args });
+  }
+
+  private send(message: object) {
+    if (this.socket?.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(message));
+  }
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@tourik/yeet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.2",
+  "description": "Small apps with a database, sign-in and live updates: the yeet command and its SDK",
+  "license": "MIT",
+  "exports": {
+    "./server": {
+      "types": "./server.d.ts"
+    },
+    "./react": "./react.ts",
+    "./sign-in": "./sign-in.ts"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "bin": {
+    "yeet": "bin/yeet.js"
+  },
+  "optionalDependencies": {
+    "@tourik/yeet-linux-x64": "0.1.0-rc.2",
+    "@tourik/yeet-linux-arm64": "0.1.0-rc.2",
+    "@tourik/yeet-darwin-arm64": "0.1.0-rc.2",
+    "@tourik/yeet-darwin-x64": "0.1.0-rc.2"
+  }
+}

package/react.ts

@@ -0,0 +1,107 @@
+import { createContext, createElement, useCallback, useContext, useMemo, useSyncExternalStore, type ReactNode } from "react";
+import { page, queryKey, YeetClient, type Args } from "./client";
+import type { RegisteredFunction } from "./server";
+
+/**
+ * Declare your server module here to type every query and mutation by name:
+ * `declare module "yeet/react" { interface Register { server: typeof import("../server") } }`
+ */
+export interface Register {}
+
+type Unregistered = Record<string, RegisteredFunction<never, Args, unknown, false>>;
+
+type Server = Register extends { server: infer S } ? S : Unregistered;
+
+type Names<Kind extends "query" | "mutation" | "action"> = {
+  [Name in keyof Server]: Server[Name] extends RegisteredFunction<Kind, unknown, unknown, false> ? Name : never;
+}[keyof Server] &
+  string;
+
+type Shape<Name> = Name extends keyof Server
+  ? Server[Name] extends RegisteredFunction<"query" | "mutation" | "action", infer A, infer R, boolean>
+    ? { args: A; result: R }
+    : never
+  : never;
+
+type ArgsOf<Name> = Shape<Name>["args"];
+
+type OptionalArgs<Name> = {} extends ArgsOf<Name> ? [args?: ArgsOf<Name>] : [args: ArgsOf<Name>];
+
+const YeetContext = createContext<YeetClient | null>(null);
+
+/** The app's WebSocket: at `url`, `/sync` on it when it is the app's address, or else on the page's host. */
+function socketUrl(url: string | undefined) {
+  if (url === undefined) {
+    const location = page()?.location;
+    if (!location) throw new Error("pass YeetProvider the app's address as url, such as https://wovies.yeet.tourik.dev");
+    const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+    return `${protocol}//${location.host}/sync`;
+  }
+  if (!/^https?:\/\//.test(url)) return url;
+  return `${url.replace(/^http/, "ws").replace(/\/+$/, "")}/sync`;
+}
+
+/**
+ * Keeps one WebSocket to the app open while mounted, at `/sync` on the page's own host unless
+ * `url` is given. A phone app gives the app's address as `url`, and the `token` from
+ * `yeet/sign-in`; a new token opens a new connection.
+ */
+export function YeetProvider({ url, token, children }: { url?: string; token?: string; children?: ReactNode }) {
+  const client = useMemo(() => new YeetClient(socketUrl(url), token), [url, token]);
+  useAuthState(client);
+  return createElement(YeetContext.Provider, { value: client }, children);
+}
+
+function useAuthState(client: YeetClient) {
+  const subscribe = useCallback((onChange: () => void) => client.onAuthChange(onChange), [client]);
+  return useSyncExternalStore(subscribe, () => client.authState());
+}
+
+function useClient() {
+  const client = useContext(YeetContext);
+  if (client === null) throw new Error("wrap your app in <YeetProvider>");
+  return client;
+}
+
+/** The query's current result, kept up to date; `undefined` until the first result arrives. */
+export function useQuery<Name extends Names<"query">>(name: Name, ...[args]: OptionalArgs<Name>) {
+  const client = useClient();
+  const queryArgs = (args ?? {}) as Args;
+  const key = queryKey(name, queryArgs);
+  // Re-subscribes only when the key changes, not when the caller passes a new but equal args object.
+  const subscribe = useCallback((onChange: () => void) => client.subscribe(name, queryArgs, onChange), [client, key]);
+  const state = useSyncExternalStore(subscribe, () => client.queryState(name, queryArgs));
+  if (state === undefined) return undefined;
+  if ("error" in state) throw state.error;
+  return state.value as Shape<Name>["result"];
+}
+
+export function useMutation<Name extends Names<"mutation">>(name: Name) {
+  const client = useClient();
+  return useCallback(
+    (...[args]: OptionalArgs<Name>) => client.mutation(name, (args ?? {}) as Args) as Promise<Shape<Name>["result"]>,
+    [client, name],
+  );
+}
+
+export function useAction<Name extends Names<"action">>(name: Name) {
+  const client = useClient();
+  return useCallback(
+    (...[args]: OptionalArgs<Name>) => client.action(name, (args ?? {}) as Args) as Promise<Shape<Name>["result"]>,
+    [client, name],
+  );
+}
+
+/**
+ * A function that replaces the page's WebSocket with a new one, for a page that resumes after the
+ * device slept, when the old connection may be dead without knowing it.
+ */
+export function useReconnect() {
+  const client = useClient();
+  return useCallback(() => client.reconnect(), [client]);
+}
+
+/** Who the server signs this page in as; `isLoading` until the server says. */
+export function useAuth() {
+  return useAuthState(useClient());
+}

package/server.d.ts

@@ -0,0 +1,244 @@
+export type Value = null | boolean | number | string | Value[] | { [field: string]: Value | undefined };
+
+export type Id<Table extends string> = string & { readonly __table: Table };
+
+export interface Validator<T> {
+  readonly kind: string;
+  readonly __type?: T;
+}
+
+export interface OptionalValidator<T> extends Validator<T | undefined> {
+  readonly kind: "optional";
+}
+
+export type Infer<V> = V extends Validator<infer T> ? T : never;
+
+type Fields = Record<string, Validator<unknown>>;
+
+type OptionalKeys<F extends Fields> = { [K in keyof F]: F[K] extends OptionalValidator<unknown> ? K : never }[keyof F];
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+export type ObjectType<F extends Fields> = Simplify<
+  { [K in Exclude<keyof F, OptionalKeys<F>>]: Infer<F[K]> } & { [K in OptionalKeys<F>]?: Infer<F[K]> }
+>;
+
+export declare const v: {
+  string(): Validator<string>;
+  number(): Validator<number>;
+  boolean(): Validator<boolean>;
+  null(): Validator<null>;
+  id<Table extends string>(table: Table): Validator<Id<Table>>;
+  literal<const T extends string | number | boolean>(value: T): Validator<T>;
+  array<T>(item: Validator<T>): Validator<T[]>;
+  object<F extends Fields>(fields: F): Validator<ObjectType<F>>;
+  optional<T>(inner: Validator<T>): OptionalValidator<T>;
+  union<Members extends Validator<unknown>[]>(...members: Members): Validator<Infer<Members[number]>>;
+};
+
+export interface TableDefinition {
+  index(name: string, fields: string[]): TableDefinition;
+  searchIndex(name: string, options: { searchField: string; filterFields?: string[] }): TableDefinition;
+}
+
+export declare function defineTable(fields: Fields): TableDefinition;
+
+export interface SchemaDefinition {
+  readonly tables: Record<string, TableDefinition>;
+}
+
+export declare function defineSchema(tables: Record<string, TableDefinition>): SchemaDefinition;
+
+export interface Document {
+  readonly _id: Id<string>;
+  readonly _creationTime: number;
+  readonly [field: string]: Value | undefined;
+}
+
+type RangeValue = string | number | boolean | null;
+
+export interface IndexRange {
+  eq(field: string, value: RangeValue): IndexRange;
+  gt(field: string, value: RangeValue): IndexRange;
+  gte(field: string, value: RangeValue): IndexRange;
+  lt(field: string, value: RangeValue): IndexRange;
+  lte(field: string, value: RangeValue): IndexRange;
+}
+
+export interface SearchFilter {
+  search(field: string, text: string): SearchFilter;
+  eq(field: string, value: RangeValue): SearchFilter;
+}
+
+/** Documents with a word starting with each word of the search text, best match first. */
+export interface SearchQuery {
+  collect(): Promise<Document[]>;
+  take(n: number): Promise<Document[]>;
+  first(): Promise<Document | null>;
+  unique(): Promise<Document | null>;
+}
+
+export interface Query {
+  withIndex(index: string, range?: (q: IndexRange) => IndexRange): Query;
+  withSearchIndex(index: string, search: (q: SearchFilter) => SearchFilter): SearchQuery;
+  order(order: "asc" | "desc"): Query;
+  collect(): Promise<Document[]>;
+  take(n: number): Promise<Document[]>;
+  first(): Promise<Document | null>;
+  unique(): Promise<Document | null>;
+}
+
+export interface DatabaseReader {
+  query(table: string): Query;
+  get(id: Id<string>): Promise<Document | null>;
+}
+
+export interface DatabaseWriter extends DatabaseReader {
+  insert(table: string, value: Record<string, Value>): Promise<Id<string>>;
+  patch(id: Id<string>, fields: Record<string, Value | undefined>): Promise<void>;
+  replace(id: Id<string>, value: Record<string, Value>): Promise<void>;
+  delete(id: Id<string>): Promise<void>;
+}
+
+export interface Auth {
+  readonly userId: string | null;
+}
+
+export interface QueryCtx {
+  readonly db: DatabaseReader;
+  readonly auth: Auth;
+  readonly now: number;
+}
+
+export interface MutationCtx {
+  readonly db: DatabaseWriter;
+  readonly auth: Auth;
+  readonly now: number;
+  /** Jobs scheduled here exist only if the mutation commits. */
+  readonly scheduler: Scheduler;
+}
+
+declare const registered: unique symbol;
+
+type Kind = "query" | "mutation" | "action";
+
+/** A function the server code exports; an internal one only actions and `yeet run` can call. */
+export interface RegisteredFunction<K extends Kind, Args, Result, Internal extends boolean = boolean> {
+  readonly [registered]: { kind: K; args: Args; result: Result; internal: Internal };
+}
+
+type Handler<Ctx, Args, Result> = (ctx: Ctx, args: Args) => Result | Promise<Result>;
+
+type Run<K extends Kind> = <Args, Result>(
+  fn: RegisteredFunction<K, Args, Result>,
+  ...args: {} extends Args ? [args?: Args] : [args: Args]
+) => Promise<Awaited<Result>>;
+
+type Schedule = <Args, Result>(
+  time: number,
+  fn: RegisteredFunction<"mutation" | "action", Args, Result>,
+  ...args: {} extends Args ? [args?: Args] : [args: Args]
+) => Promise<string>;
+
+/**
+ * Runs an exported mutation or action later, as nobody (`ctx.auth.userId` is null), on `yeet dev`
+ * and on the live app; previews keep their jobs without running them.
+ */
+export interface Scheduler {
+  /** Runs `fn` in `ms` milliseconds and returns the job's id. */
+  readonly runAfter: Schedule;
+  /** Runs `fn` at `time`, in milliseconds since 1970, and returns the job's id. */
+  readonly runAt: Schedule;
+  cancel(id: string): Promise<void>;
+}
+
+/**
+ * An action's context: it reads and writes only through queries and mutations. Inside actions,
+ * `Date` and `Math.random` are the real ones, and `setTimeout` exists.
+ */
+export interface ActionCtx {
+  readonly auth: Auth;
+  readonly runQuery: Run<"query">;
+  readonly runMutation: Run<"mutation">;
+  readonly scheduler: Scheduler;
+}
+
+type CronArgs<Args> = {} extends Args ? [args?: Args] : [args: Args];
+
+type DayOfWeek = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+
+/**
+ * Mutations and actions that repeat on a timetable, as nobody. Export the object that `cronJobs()`
+ * returns from `server/index.ts`. A cron missed while the app was stopped runs once when it starts.
+ */
+export interface Crons {
+  interval<Args>(
+    name: string,
+    every: { seconds?: number; minutes?: number; hours?: number },
+    fn: RegisteredFunction<"mutation" | "action", Args, unknown>,
+    ...args: CronArgs<Args>
+  ): Crons;
+  hourly<Args>(
+    name: string,
+    at: { minuteUTC: number },
+    fn: RegisteredFunction<"mutation" | "action", Args, unknown>,
+    ...args: CronArgs<Args>
+  ): Crons;
+  daily<Args>(
+    name: string,
+    at: { hourUTC: number; minuteUTC: number },
+    fn: RegisteredFunction<"mutation" | "action", Args, unknown>,
+    ...args: CronArgs<Args>
+  ): Crons;
+  weekly<Args>(
+    name: string,
+    at: { dayOfWeek: DayOfWeek; hourUTC: number; minuteUTC: number },
+    fn: RegisteredFunction<"mutation" | "action", Args, unknown>,
+    ...args: CronArgs<Args>
+  ): Crons;
+}
+
+export declare function cronJobs(): Crons;
+
+interface Define<K extends Kind, Ctx, Internal extends boolean> {
+  <A extends Fields, Result>(definition: {
+    args: A;
+    handler: Handler<Ctx, ObjectType<A>, Result>;
+  }): RegisteredFunction<K, ObjectType<A>, Result, Internal>;
+  <Result>(definition: {
+    handler: Handler<Ctx, Record<string, never>, Result>;
+  }): RegisteredFunction<K, Record<string, never>, Result, Internal>;
+}
+
+export declare const query: Define<"query", QueryCtx, false>;
+export declare const mutation: Define<"mutation", MutationCtx, false>;
+/** Like a mutation, but may wait on the network; it is not one transaction. */
+export declare const action: Define<"action", ActionCtx, false>;
+export declare const internalQuery: Define<"query", QueryCtx, true>;
+export declare const internalMutation: Define<"mutation", MutationCtx, true>;
+export declare const internalAction: Define<"action", ActionCtx, true>;
+
+declare const endpoint: unique symbol;
+
+/** An endpoint's handler: it runs like an action and answers with a `Response`. */
+export interface HttpAction {
+  readonly [endpoint]: true;
+}
+
+export declare function httpAction(handler: (ctx: ActionCtx, request: Request) => Response | Promise<Response>): HttpAction;
+
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+type Route = ({ path: `/api/${string}` } | { pathPrefix: `/api/${string}` }) & { method: HttpMethod; handler: HttpAction };
+
+/** The app's endpoints; export it, as in `export const http = httpRouter()`. */
+export interface HttpRouter {
+  route(route: Route): void;
+}
+
+export declare function httpRouter(): HttpRouter;
+
+declare global {
+  /** Inside actions only: the app's secrets, from `yeet secret set`, or `.env` on `yeet dev`. */
+  const process: { readonly env: Readonly<Record<string, string | undefined>> };
+}

package/sign-in.ts

@@ -0,0 +1,103 @@
+/**
+ * Signs a phone app in through the system browser. Open `url` from `startSignIn` in the browser,
+ * for example with Expo's `WebBrowser.openAuthSessionAsync(url, redirect)`, then pass the address
+ * the browser came back to to `finish`. List `redirect` in `yeet.json`'s `"redirects"`.
+ */
+export interface SignIn {
+  readonly url: string;
+  finish(redirectedUrl: string): Promise<{ token: string; userId: string }>;
+}
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+  0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+  0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+  0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+  0xc67178f2,
+]);
+
+/** SHA-256 of ASCII text, since Hermes, React Native's engine, has no Web Crypto. */
+function sha256(text: string) {
+  const length = text.length;
+  const padded = new Uint8Array(Math.ceil((length + 9) / 64) * 64);
+  for (let i = 0; i < length; i++) padded[i] = text.charCodeAt(i);
+  padded[length] = 0x80;
+  new DataView(padded.buffer).setUint32(padded.length - 4, length * 8);
+  const hash = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const words = new Uint32Array(64);
+  const view = new DataView(padded.buffer);
+  const rotate = (x: number, n: number) => (x >>> n) | (x << (32 - n));
+  for (let block = 0; block < padded.length; block += 64) {
+    for (let i = 0; i < 16; i++) words[i] = view.getUint32(block + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotate(words[i - 15], 7) ^ rotate(words[i - 15], 18) ^ (words[i - 15] >>> 3);
+      const s1 = rotate(words[i - 2], 17) ^ rotate(words[i - 2], 19) ^ (words[i - 2] >>> 10);
+      words[i] = words[i - 16] + s0 + words[i - 7] + s1;
+    }
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let i = 0; i < 64; i++) {
+      const t1 = h + (rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + words[i];
+      const t2 = (rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22)) + ((a & b) ^ (a & c) ^ (b & c));
+      [h, g, f, e, d, c, b, a] = [g, f, e, (d + t1) >>> 0, c, b, a, (t1 + t2) >>> 0];
+    }
+    [a, b, c, d, e, f, g, h].forEach((value, i) => (hash[i] = hash[i] + value));
+  }
+  const bytes = new Uint8Array(32);
+  hash.forEach((word, i) => new DataView(bytes.buffer).setUint32(i * 4, word));
+  return bytes;
+}
+
+const BASE64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+function base64url(bytes: Uint8Array) {
+  let text = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const chunk = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    const characters = Math.ceil(((Math.min(3, bytes.length - i)) * 8) / 6);
+    for (let j = 0; j < characters; j++) text += BASE64URL[(chunk >> (18 - 6 * j)) & 63];
+  }
+  return text;
+}
+
+function randomVerifier() {
+  const crypto = (globalThis as { crypto?: { getRandomValues?(array: Uint8Array): Uint8Array } }).crypto;
+  if (typeof crypto?.getRandomValues !== "function") {
+    throw new Error("crypto.getRandomValues is missing; in React Native, import \"react-native-get-random-values\" first");
+  }
+  return base64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+/** Starts a sign-in to the app at `appUrl`, such as `https://wovies.yeet.tourik.dev`, that ends at `redirect`. */
+export function startSignIn(appUrl: string, redirect: string): SignIn {
+  const app = appUrl.replace(/\/+$/, "");
+  const verifier = randomVerifier();
+  const challenge = base64url(sha256(verifier));
+  return {
+    url: `${app}/_yeet/login?redirect=${encodeURIComponent(redirect)}&challenge=${challenge}`,
+    async finish(redirectedUrl) {
+      const code = /[?&]code=([^&#]+)/.exec(redirectedUrl)?.[1];
+      if (code === undefined) throw new Error(`${redirectedUrl} has no code; the sign-in did not finish`);
+      const response = await fetch(`${app}/_yeet/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code: decodeURIComponent(code), verifier }),
+      });
+      if (!response.ok) throw new Error(await response.text());
+      return (await response.json()) as { token: string; userId: string };
+    },
+  };
+}
+
+/** Ends the token's session, so it signs nobody in any more. */
+export async function signOut(appUrl: string, token: string) {
+  const response = await fetch(`${appUrl.replace(/\/+$/, "")}/_yeet/logout`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}` },
+  });
+  if (!response.ok) throw new Error(await response.text());
+}