@tourik/yeet 0.1.0-rc.1 → 0.1.0-rc.2

package/README.md

@@ -0,0 +1,144 @@
+# yeet
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tourik/yeet",
-  "version": "0.1.0-rc.1",
+  "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": {
@@ -20,9 +20,9 @@
     "yeet": "bin/yeet.js"
   },
   "optionalDependencies": {
-    "@tourik/yeet-linux-x64": "0.1.0-rc.1",
-    "@tourik/yeet-linux-arm64": "0.1.0-rc.1",
-    "@tourik/yeet-darwin-arm64": "0.1.0-rc.1",
-    "@tourik/yeet-darwin-x64": "0.1.0-rc.1"
+    "@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"
   }
 }