eraspace 0.3.0 → 0.4.0

package/README.md

@@ -25,6 +25,8 @@ sign in and claim it (`eraspace auth login`, then `eraspace claim`).
 | `typecheck` | Typecheck `server/`, `client/` and `shared/` |
 | `deploy` | Build the client, compile the server and deploy (`--delete-table <table>=<rows>` confirms deleting a removed table; `--shadow` first reruns the app's live queries on the new code and reports which results change or start throwing, and `--fail-on-query-errors` refuses the deploy if any would throw) |
 | `dev` | Deploy, then redeploy whenever `server/`, `client/`, `shared/` or `.env.eraspace.server` change |
+| `deploys [app]` | List the latest 50 kept versions, newest first, marking the one serving; older kept versions still roll back by number |
+| `rollback [version]` | Deploy an earlier version's server code, client files and server env again as a new version; without a version, the one before the serving version. Takes `--delete-table`, `--shadow` and `--fail-on-query-errors` like `deploy` |
 | `call <fn> '<json>'...` | Call a query, mutation or action, each argument a JSON value |
 | `profile [app] --seconds <n>` | Sample the app's server CPU time and write a `.cpuprofile` (TypeScript positions) for Chrome DevTools, printing the top functions by self time (`--out <file>`) |
 | `explain <fn> '<json>'...` | Run a query once and print the rows it scanned and kept, with an index for each scan it filtered in JavaScript (`--json` for the full report) |

package/bin.js

@@ -32879,15 +32879,15 @@ var TomlParser = class {
   }
   parseDate(token) {
     const date = "\\d{4}-\\d{2}-\\d{2}";
-    const time3 = "\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?";
-    if (new RegExp(`^${date}[Tt]${time3}(?:[Zz]|[+-]\\d{2}:\\d{2})$`).test(token)) {
+    const time4 = "\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?";
+    if (new RegExp(`^${date}[Tt]${time4}(?:[Zz]|[+-]\\d{2}:\\d{2})$`).test(token)) {
       const value4 = new Date(token.replace("t", "T").replace("z", "Z"));
       if (Number.isNaN(value4.getTime())) {
         this.fail(`Invalid date-time '${token}'`);
       }
       return value4;
     }
-    if (new RegExp(`^${date}[Tt]${time3}$`).test(token) || new RegExp(`^${date}$`).test(token) || new RegExp(`^${time3}$`).test(token)) {
+    if (new RegExp(`^${date}[Tt]${time4}$`).test(token) || new RegExp(`^${date}$`).test(token) || new RegExp(`^${time4}$`).test(token)) {
       return token.replace("t", "T");
     }
     return void 0;
@@ -38994,7 +38994,7 @@ var runWith2 = (command2, config2) => {
 // cli/package.json
 var package_default = {
   name: "eraspace-cli",
-  version: "0.3.0",
+  version: "0.4.0",
   private: true,
   license: "MIT",
   type: "module",
@@ -39314,12 +39314,12 @@ function findSpecifier(source, spec) {
 }
 function formatLog(l) {
   const d = l.ts === void 0 ? /* @__PURE__ */ new Date() : new Date(typeof l.ts === "number" ? l.ts : Date.parse(l.ts));
-  const time3 = isNaN(d.getTime()) ? String(l.ts) : d.toISOString().slice(11, 23);
+  const time4 = isNaN(d.getTime()) ? String(l.ts) : d.toISOString().slice(11, 23);
   const level = (l.level ?? "info").toLowerCase();
   const color = level === "error" ? c.red : level === "warn" ? c.yellow : level === "debug" ? c.gray : c.blue;
   const fn3 = l.fn ? c.magenta(l.fn) + " " : "";
   const data = l.data === void 0 || l.data === null ? "" : " " + c.gray(JSON.stringify(l.data));
-  return `${c.gray(time3)} ${color(level.padEnd(5))} ${fn3}${l.msg ?? ""}${data}`;
+  return `${c.gray(time4)} ${color(level.padEnd(5))} ${fn3}${l.msg ?? ""}${data}`;
 }
 var SKIPPED = {
   fetch: "uses fetch",
@@ -39404,7 +39404,13 @@ var Deployed = Schema_exports.Struct({
   ...App.fields,
   version: Schema_exports.optional(Schema_exports.Number),
   claimToken: Schema_exports.optional(Schema_exports.String),
-  shadow: Schema_exports.optional(ShadowReport)
+  shadow: Schema_exports.optional(ShadowReport),
+  /** For a rollback: the kept version whose files were deployed again. */
+  rolledBackTo: Schema_exports.optional(Schema_exports.Number)
+});
+var DeployHistory = Schema_exports.Struct({
+  version: Schema_exports.optional(Schema_exports.Number),
+  deploys: Schema_exports.optional(Schema_exports.Array(Schema_exports.Struct({ version: Schema_exports.Number, createdAt: Schema_exports.optional(Schema_exports.Number) })))
 });
 var AppList = Schema_exports.Struct({ apps: Schema_exports.Array(App) });
 var StateChange = Schema_exports.Struct({ state: Schema_exports.String });
@@ -39421,7 +39427,7 @@ var Token2 = Schema_exports.Struct({
   lastUsedAt: Schema_exports.optional(Timestamp)
 });
 var TokenList = Schema_exports.Struct({ tokens: Schema_exports.Array(Token2) });
-var CreatedToken = Schema_exports.Struct({ token: Schema_exports.String });
+var CreatedToken = Schema_exports.Struct({ token: Schema_exports.String, id: Schema_exports.String });
 var DeviceStart = Schema_exports.Struct({
   deviceCode: Schema_exports.String,
   userCode: Schema_exports.String,
@@ -39961,6 +39967,11 @@ var createApp = Effect_exports.fnUntraced(function* (config2, payload, extra, op
   return { result: result4, name: naming.name };
 });
 var deploy = Effect_exports.fnUntraced(function* (config2, opts = {}) {
+  const t = yield* target(config2);
+  if (t.ref && opts.name !== void 0)
+    return yield* fail12(
+      t.claim ? `--name only names a new app, and this checkout already deploys to ${t.ref}. Name it when you claim it: eraspace claim --name ${opts.name}` : `--name only names a new app, and this checkout already deploys to ${t.ref}. Add the name with eraspace names add ${opts.name}`
+    );
   const build3 = yield* buildCapsule(config2.root);
   if (!build3.ok || !build3.payload)
     return yield* fail12(yield* formatErrors(build3.errors, config2.root));
@@ -39972,7 +39983,6 @@ var deploy = Effect_exports.fnUntraced(function* (config2, opts = {}) {
     ...opts.failOnQueryErrors ? { failOnQueryErrors: true } : {}
   };
   const signedIn = (yield* bearerFor(config2.origin)) !== void 0;
-  const t = yield* target(config2);
   let result4;
   if (t.ref) {
     const payload = t.claim ? yield* withoutEnv(build3.payload) : build3.payload;
@@ -40035,6 +40045,40 @@ var deploy = Effect_exports.fnUntraced(function* (config2, opts = {}) {
   }
   return result4;
 });
+var time2 = (ms) => ms === void 0 ? "" : new Date(ms).toISOString();
+var deploys = Effect_exports.fnUntraced(function* (config2, explicit) {
+  const t = yield* requireTarget(config2, explicit);
+  const history = yield* ok(DeployHistory)(config2, "GET", `/_api/apps/${enc(t.ref)}`, { claim: t.claim });
+  const kept = history.deploys ?? [];
+  if (!kept.length) return yield* Console_exports.log(`${t.ref} has no deploys.`);
+  for (const d of kept) {
+    const serving = d.version === history.version ? `  ${c.green("serving")}` : "";
+    yield* Console_exports.log(`v${d.version}  ${c.dim(time2(d.createdAt))}${serving}`);
+  }
+  if (kept.length >= 50) yield* Console_exports.log(c.dim(`Showing the latest ${kept.length}; any older kept versions still roll back by number: eraspace rollback <version>`));
+});
+var rollback = Effect_exports.fnUntraced(function* (config2, version, opts = {}) {
+  const t = yield* requireTarget(config2);
+  const deleteTables = yield* confirmedDeletes(opts.deleteTables);
+  const body = {
+    ...version === void 0 ? {} : { version },
+    ...Object.keys(deleteTables).length ? { deleteTables } : {},
+    ...opts.shadow ? { shadow: true } : {},
+    ...opts.failOnQueryErrors ? { failOnQueryErrors: true } : {}
+  };
+  const path = `/_api/apps/${enc(t.ref)}/rollback`;
+  const response = yield* api(config2, "POST", path, { body, claim: t.claim, timeout: DEPLOY_TIMEOUT });
+  if (response.status >= 400 || response.json.ok === false) {
+    const refused = Schema_exports.decodeUnknownOption(ShadowReport)(response.json.shadow);
+    if (Option_exports.isSome(refused)) yield* Console_exports.log(formatShadow(refused.value));
+    return yield* Effect_exports.fail(yield* failure(response, config2.root));
+  }
+  const result4 = yield* decode5(Deployed, response.json, `POST ${path}`);
+  if (result4.shadow) yield* Console_exports.log(formatShadow(result4.shadow));
+  const label = result4.names?.[0] ?? result4.id;
+  yield* Console_exports.log(`${label} v${String(result4.version)}: rolled back to v${String(result4.rolledBackTo)}: ${result4.url ?? config2.url}`);
+  return result4;
+});
 var claimRequest = (config2, path, body, claim2) => api(config2, "POST", path, { body, claim: claim2 });
 var claim = Effect_exports.fnUntraced(function* (config2, name) {
   const local = yield* localDeploy(config2.root, config2.origin);
@@ -40082,10 +40126,14 @@ var IGNORED = /(^|[/\\])(node_modules|\.git|\.eraspace)([/\\]|$)/;
 var isWatched = (file2) => !IGNORED.test(file2) && WATCHED.test(file2);
 var dev = Effect_exports.fnUntraced(function* (config2, opts) {
   const fs = yield* FileSystem_exports.FileSystem;
+  let current = opts;
   const redeploy = Effect_exports.suspend(
     () => loadConfig({ dir: config2.root, app: config2.app, url: config2.url })
   ).pipe(
-    Effect_exports.flatMap((current) => deploy(current, opts)),
+    Effect_exports.flatMap((loaded) => deploy(loaded, current)),
+    Effect_exports.tap(() => Effect_exports.sync(() => {
+      current = { ...current, name: void 0 };
+    })),
     Effect_exports.catch((error2) => Console_exports.error(messageOf(error2)))
   );
   yield* redeploy;
@@ -40193,7 +40241,7 @@ var logs = Effect_exports.fnUntraced(function* (config2, explicit, follow, limit
 var okApp = ok(App);
 var okJson = ok(JsonObject2);
 var okState = ok(StateChange);
-var time2 = (value4) => {
+var time3 = (value4) => {
   if (value4 === null || value4 === void 0) return void 0;
   const date = new Date(typeof value4 === "number" ? value4 : Date.parse(value4));
   return Number.isNaN(date.getTime()) ? String(value4) : date.toISOString();
@@ -40300,7 +40348,7 @@ var listTokens = Effect_exports.fnUntraced(function* (config2) {
   if (!tokens.length) yield* Console_exports.log("No tokens.");
   for (const t of tokens) {
     const scope3 = t.scope === "personal" ? "personal (all your apps)" : `${t.app ?? "?"} (${t.access ?? "?"})`;
-    const used = time2(t.lastUsedAt);
+    const used = time3(t.lastUsedAt);
     yield* Console_exports.log(`${t.id}  ${t.name}  ${scope3}  ${c.dim(used ? `last used ${used}` : "never used")}`);
   }
 });
@@ -40311,9 +40359,10 @@ var revokeToken = Effect_exports.fnUntraced(function* (config2, id2) {
 var createToken = Effect_exports.fnUntraced(function* (config2, name, opts) {
   if (opts.personal && opts.read) return yield* fail12("--read only applies to app tokens; personal tokens have full access to your apps.");
   const spec = opts.personal ? { name, personal: true } : { name, app: (yield* requireTarget(config2)).ref, access: opts.read ? "read" : "deploy" };
-  const { token } = yield* ok(CreatedToken)(config2, "POST", "/_api/tokens", { body: spec });
+  const { token, id: id2 } = yield* ok(CreatedToken)(config2, "POST", "/_api/tokens", { body: spec });
   yield* Console_exports.log(token);
   yield* Console_exports.error(c.dim(`Shown once. Use it as ERASPACE_TOKEN with ERASPACE_TOKEN_API=${config2.origin}.`));
+  yield* Console_exports.error(c.dim(`Token id ${id2}; revoke it with eraspace token revoke ${id2}.`));
 });
 function parseCallArgs(inputs) {
   const args2 = [];
@@ -40350,138 +40399,74 @@ import { basename as basename2, join as join7, relative as relative3, resolve as
 var TEMPLATES = ["chat", "todo", "poll"];
 var agents = (cli) => `# eraspace capsule: agent instructions
 
-This directory is one eraspace app ("capsule"): a TypeScript server running in V8, a Preact client, a
-Postgres-backed database with live queries, and hosting, all through the \`eraspace\` CLI. Treat this directory as the
-whole app. Build the requested app by editing the starter files, deploy it, verify it, and report the URL.
-
-## Commands
-
-Run these from this directory. There is nothing to install: the CLI bundles the SDK, Preact and TypeScript.
-
-- \`${cli} typecheck\`: tsc over \`server/\`, \`client/\` and \`shared/\`. Deploy does not typecheck.
-- \`${cli} deploy\`: build the client, compile the server and print the app URL.
-- \`${cli} call <fn> '<json arg>'...\`: call a query, mutation or action, e.g. \`call add '"milk"'\`.
-- \`${cli} logs\`: handler logs, \`ctx.log\` and \`console.log\` output.
-- \`${cli} inspect\`: deployed functions, schema and metadata.
-- \`${cli} dev\`: redeploy on every save (long-running; keep it open).
-
-The platform URL comes from \`ERASPACE_URL\`, then \`eraspace.json\`, then \`${DEFAULT_URL}\`.
+This directory is an eraspace app ("capsule"): a TypeScript server in V8 and a Preact client over a database with
+live queries, hosted and driven by \`${cli}\`, which supplies TypeScript, Preact and \`eraspace/*\`, so there is
+nothing to install.
 
 ## Workflow
 
-1. Read \`server/index.ts\` and \`client/index.tsx\`, then replace them with the requested app.
-2. Run \`${cli} typecheck\` and fix every error.
-3. Run \`${cli} deploy\`. Fix any compile errors it prints (they include file:line:column).
-4. Exercise every query and mutation with \`${cli} call ...\`, including one invalid input. Check
-   \`${cli} logs\` for errors.
-5. Report the URL printed by deploy. Open it in two tabs to see live updates.
-
-## Files
-
-- \`server/index.ts\` default-exports \`capsule({...})\` from \`eraspace/server\`. Other server files go in \`server/\`.
-- \`client/index.tsx\` default-exports \`function App()\`. The CLI mounts it. Other client files go in \`client/\`.
-- \`shared/\` holds pure TypeScript used by both sides (no DOM, no env, no eraspace runtime imports).
-- \`client/styles.css\` plus Tailwind utility classes in JSX. Write complete class names.
-- \`.env.eraspace.server\` holds server secrets, read as \`ctx.env.KEY\`. Never import it from client code.
-- There is no package.json, tsconfig.json or node_modules, and none is needed. Do not add them.
-
-## Server API (\`eraspace/server\`)
-
-\`\`\`ts
-import { capsule, table, query, mutation, action, endpoint, string, number, boolean, id, array, object, any, json, text } from "eraspace/server";
-
-export default capsule({
-  schema: {
-    items: table({ title: string(), done: boolean().default(false), listId: id("lists"), tags: array(string()).optional() })
-      .index("by_list", ["listId"]),
-    lists: table({ name: string() }),
-  },
-  queries: {
-    items: query(async (ctx, listId: string) =>
-      ctx.db.items.withIndex("by_list", (q) => q.eq("listId", listId)).order("desc").take(100)),
-  },
-  mutations: {
-    add: mutation(async (ctx, listId: string, title: string) => {
-      const clean = title.trim();
-      if (!clean) throw new Error("Title is required.");   // the message reaches the client
-      return ctx.db.items.insert({ listId, title: clean });
-    }),
-  },
-  actions: {
-    summary: action(async (ctx) => {
-      const rows = await ctx.runQuery("items", "some-list");
-      return rows.length;
-    }),
-  },
-  endpoints: {
-    health: endpoint({ method: "GET", path: "/health", readOnly: true }, async (ctx, req) => json({ ok: true })),
-  },
-});
-\`\`\`
-
-- Field validators: \`string() number() boolean() id("table") userId() any() array(v) object({...})\`, each with
-  \`.optional()\` or \`.default(value)\`. Rows always have \`id\` (string) and \`createdAt\` (epoch ms).
-- \`ctx.db.<table>\`: \`insert(doc)\` returns the id, \`get(id)\` returns the row or null, \`update(id, partial)\`
-  (\`null\` removes a field), \`replace(id, doc)\`, \`delete(id)\`. Reads chain \`withIndex(name, q => q.eq(f, v).gt(...))\`,
-  \`order("asc" | "desc")\`, then \`collect()\`, \`take(n)\`, \`first()\`, \`unique()\`, \`count()\` or
-  \`paginate({ cursor, numItems })\`. Every table has an implicit \`by_creation\` index. Await every db call.
-- Queries and actions have a read-only db. Write in mutations or writable endpoints. Actions can call
-  \`ctx.runQuery\`, \`ctx.runMutation\` and global \`fetch\`.
-- Mutations schedule later work with \`ctx.scheduler.runAfter(ms, "mutationName", ...args)\`, which returns a job id.
-  The job commits with the mutation and its run commits once; only mutations can be scheduled.
-- Handler arguments are positional and not validated. Check them in the handler.
-- \`ctx.auth.userId\` is a per-connection guest id that changes on reload. It is not a login: never use it for
-  ownership or access control. Every app is public.
-- \`ctx.log.info(msg, data?)\` (also debug/warn/error) writes to \`eraspace logs\`.
-- Endpoints receive \`req\` with \`method, path, url, headers.get(), query.get(), json(), text()\` and return
-  \`json(value)\`, \`text(string)\`, \`empty()\`, \`redirect(url)\` or a plain value (sent as JSON).
-- Removing a populated table needs its row count confirmed: \`${cli} deploy --delete-table <table>=<rows>\` (the
-  refused deploy prints the exact flag). Deletion runs in background batches.
-- Changing a field's type or making it required fails the deploy while stored rows do not match. Declare a
-  migration instead: \`table({ ... }).migrate(1, row => ({ ...row, done: false }))\` upgrades old rows when read
-  and rewrites them in the background. Number migrations 1, 2, 3, ... and keep each one until its rows are done.
-
-## Client API (\`eraspace/client\`)
-
-\`\`\`tsx
-import { createClient } from "eraspace/client";
-import { useState } from "preact/hooks";
-import type app from "../server/index";
-
-const client = createClient<typeof app>();
-
-export default function App() {
-  const items = client.useQuery("items", "some-list");   // undefined while loading, then live
-  const add = client.useMutation("add");
-  const [title, setTitle] = useState("");
-  if (items === undefined) return <p>Loading\u2026</p>;
-  return <main class="p-6">
-    <form onSubmit={async (e) => { e.preventDefault(); await add("some-list", title); setTitle(""); }}>
-      <input value={title} onInput={(e) => setTitle(e.currentTarget.value)} />
-    </form>
-    <ul>{items.map((item) => <li key={item.id}>{item.title}</li>)}</ul>
-  </main>;
-}
-\`\`\`
-
-- Query, mutation and action names, arguments and results are typed from the server. Import the server with
-  \`import type\` only.
-- Optimistic updates: \`client.useMutation("vote", { optimistic(store, id) { store.update("results", [],
-  (rows) => rows.map((r) => (r.id === id ? { ...r, votes: r.votes + 1 } : r))) } })\`. The second argument of
-  \`store.update\` is the query's argument list.
-- \`useAction(name)\`, \`usePaginatedQuery(name, args, { initialNumItems })\`, \`client.query/mutation/action(...)\`.
-- Realtime rooms, not stored: \`const room = client.useRoom(name, meta)\` gives \`room.presence\`,
-  \`room.broadcast(event, payload)\` and \`room.on(event, cb)\` (call \`on\` inside \`useEffect\` and return its
-  cleanup). \`client.usePresence(name, meta)\` returns just the members.
-- Files: see "File uploads" below.
-- Pages: \`Router\`, \`Route\`, \`Link\`, \`useLocation\`, \`useNavigate\`, \`useParams\` from \`eraspace/client\`.
-- Open tabs reload by themselves after each deploy. Pass \`createClient({ reloadOnDeploy: false })\` to keep the
-  page and react to \`client.onDeployed(version => ...)\` instead.
-- Client imports are limited to \`eraspace/client\`, \`preact\`, \`preact/hooks\`, \`@preact/signals\` and relative files.
+1. Read \`CODING_STANDARDS.md\`, \`server/index.ts\` and \`client/index.tsx\`.
+2. Write the requested app or change.
+3. Run \`${cli} typecheck\` until it prints "No type errors."
+4. Run \`${cli} deploy\` until it prints the app URL. Pass \`--delete-table\` only for rows the user agreed to lose.
+5. Run \`${cli} call <fn> '<json arg>'...\` on every query, mutation and action, and on an invalid input for each
+   mutation that takes arguments, until each returns what the code intends and each invalid input is refused with
+   its message; then \`${cli} logs\` shows no unexpected error.
+6. Once steps 3 to 5 pass after your last edit, report the URL. For an unclaimed app, also report the expiry deploy
+   printed and that \`${cli} auth login\` then \`${cli} claim\` keeps the app.
+`;
+var CODING_STANDARDS = `# eraspace capsule: coding standards
+
+Before using one of these features, read its section in \`FEATURES.md\`: file uploads, rooms and presence, routing,
+optimistic updates, pagination, scheduled mutations, HTTP endpoints, reload on deploy.
+
+## Security
+
+- Every caller is an anonymous guest and every app is public. \`ctx.auth.userId\` is a guest id that changes with
+  each connection, so it never grants ownership or access.
+- Keep secrets in \`.env.eraspace.server\` as \`KEY=value\` lines and read them in server code as \`ctx.env.KEY\`:
+  \`client/\` and \`shared/\` ship to the browser.
+
+## Server (\`eraspace/server\`)
+
+- Fields: \`string() number() boolean() id("table") userId() any() array(field) object({...})\`, each with
+  \`.optional()\` or \`.default(value)\`. Rows also have \`id\` and \`createdAt\` (epoch ms).
+- \`ctx.db.<table>\` has \`insert\`, \`get\`, \`update(id, partial)\` (\`null\` removes a field), \`replace\` and
+  \`delete\`. Reads chain \`withIndex\`, \`order("asc" | "desc")\`, then \`collect()\`, \`take(n)\`, \`first()\`,
+  \`unique()\`, \`count()\` or \`paginate(...)\`.
+- Declare an index with \`table({...}).index("by_list", ["listId"])\` and read it with
+  \`ctx.db.items.withIndex("by_list", (q) => q.eq("listId", id))\`, then \`.gt(...)\` or \`.lt(...)\` on the next
+  field. \`by_creation\` indexes every table by \`createdAt\`.
+- Validate every argument in the handler: arguments are positional, come from anyone and are not checked against
+  their TypeScript types.
+- A query is a live query: its cached result is reused until rows it read change, then rerun and pushed to
+  subscribers. Make it depend only on its arguments, its caller and the rows it reads: pass a time it needs as an
+  argument, rounded so it stays the same across renders, and draw random values in mutations.
+- Mutations run one at a time per app, so a read-then-write in one mutation never races another.
+- Actions call outbound \`fetch\`, \`ctx.runQuery\`, \`ctx.runMutation\` and \`ctx.runAction\`: fetch in an action
+  and save the result with \`ctx.runMutation\`.
+- Rows and results are JSON: keep times as epoch-ms numbers, as \`createdAt\` is.
+- Keep state in the database: module variables reset whenever the app unloads.
+- Handlers have CPU, wall-clock and heap limits: keep loops and reads bounded.
+- A \`.migrate\` upgrade is a pure function of the stored row.
+
+## Client (\`eraspace/client\`)
+
+- \`client.useQuery(name, ...args)\` subscribes to a live query: \`undefined\` while loading, then every new result,
+  so mutations need no refetch.
+- \`client.useAction(name)\` returns a function, as \`useMutation\` does. Outside components, call \`client.query\`,
+  \`client.mutation\` or \`client.action(name, ...args)\`.
+- Style with Tailwind utility classes, each written as a complete literal, and \`client/styles.css\`.
+
+## Shared code
+
+- Keep \`shared/\` to types, constants and pure functions, which both the browser and the server can run.
+`;
+var FEATURES = `# eraspace capsule: features
 
 ## File uploads
 
-Files go to the app's bucket, not the database. Save the returned \`FileRef\` in a row, then preview it.
+Files live in app storage, not the database: a row saves the \`FileRef\` an upload returns.
 
 \`\`\`tsx
 // server/index.ts: declare the file in the schema and copy its fields in the mutation (extra fields are refused).
@@ -40501,36 +40486,93 @@ const addPhoto = client.useMutation("addPhoto");
 - \`<FileUpload>\` is a drop zone and file picker with progress and error text. Props: \`accept\`, \`multiple\`,
   \`maxBytes\`, \`disabled\`, \`class\` (replaces its default style; \`data-dragging\` is set during a drag) and
   children for the label. \`onUpload(file)\` runs once per stored file; if it throws, the file is deleted again.
-- \`<FilePreview file={fileRef or key}>\` shows images, video and audio inline, plain text in a frame, and other
-  types (PDF, zip...) as a download card. \`caption={false}\` hides the name/size line; \`class\` replaces its style.
-  Pass the saved \`FileRef\`: a bare key costs a metadata request per preview. Images, video and audio uploaded
-  from the same page show at once from the browser's copy; \`<FileUpload>\` shows an image while it uploads.
+- \`<FilePreview file={fileRef}>\` shows images, video and audio inline, plain text in a frame, and other types as a
+  download card. Pass it the saved \`FileRef\`: a bare key costs a metadata request per preview. \`caption={false}\`
+  hides the name/size line; \`class\` replaces its style.
 - Custom UI: \`const { upload, uploading, progress, error, file } = client.useUpload({ accept, maxBytes, onUpload })\`,
   then \`upload(input.files)\`; \`file\` is the Blob uploading now. Lower level: \`client.storage.upload(blob, { onProgress })\`,
   \`.url(key)\`, \`.localUrl(key)\`, \`.info(key)\` and \`.delete(key)\`.
+- Up to 5 MiB per file and 100 MiB per app.
 - \`accept\` and \`maxBytes\` are checked in the browser only; the server stores any type up to its limit.
-- Up to 5 MiB per file and 100 MiB per app. Anyone with a key can read or delete that file; never upload secrets.
+- Anyone with a file's key can read that file, so upload only what may be public. The \`deleteToken\` that
+  \`client.storage.upload\` returns lets its holder delete the file: keep it out of rows.
+
+## Rooms and presence
+
+Rooms are realtime and never stored. \`const room = client.useRoom(name, meta)\` gives:
+
+- \`room.presence\`, the members with their \`meta\`, and \`room.self\`, this connection's id.
+- \`room.broadcast(event, payload)\` and \`room.on(event, (payload, from) => ...)\`. Call \`on\` inside \`useEffect\`
+  and return its cleanup.
+- \`room.state\`, shared by the members and set with \`room.setState(key, value)\`. It vanishes when the room
+  empties: save what must last with a mutation.
+
+\`client.usePresence(name, meta)\` returns just the members.
 
-## Server execution
+## Routing
 
-Server TypeScript is transformed with oxc and runs as ES modules in V8. JavaScript language features such as
-classes, closures, async/await, generators, getters, private fields, Proxy, Reflect and BigInt use V8 semantics.
-Values crossing the database or RPC boundary must be JSON-compatible.
+\`\`\`tsx
+import { Router, Route, Link, useParams, useNavigate } from "eraspace/client";
+
+<Router>
+  <Route path="/" component={Home} />
+  <Route path="/items/:id" component={Item} />   {/* Item reads useParams().id */}
+  <Route default component={NotFound} />
+</Router>
+\`\`\`
+
+Paths are app-relative: the app is served under \`/<app>/\`, and every path below it loads the app. Link with
+\`<Link to="/items/1">\` and navigate with \`useNavigate()("/items/1")\`, which add that base. \`useLocation()\`
+gives the current \`path\` and \`url\`.
+
+## Optimistic updates
 
-- Imports support relative deployed files and \`eraspace/server\`. npm packages, Node built-ins and dynamic
-  \`import()\` are unavailable. Apps need no installed server dependencies.
-- The host supplies \`fetch\`, \`URL\`, \`URLPattern\`, \`Headers\`, \`Request\`, \`Response\`, Web Streams,
-  \`Blob\`, \`File\`, \`FormData\`, \`crypto\` (including \`crypto.subtle\`), \`TextEncoder\`, \`TextDecoder\`,
-  \`CompressionStream\`, timers and \`console\`. Bodies arrive and leave whole rather than incrementally.
-- Persist state in the database. Module state is not durable and resets when an app unloads or a worker restarts.
-- Await database calls. Mutations run through one writer per app and reply after their Postgres commit.
-- Handlers have CPU, wall-clock and heap limits. Keep loops and reads bounded.
-- Outbound fetch is available to claimed apps in actions and read-only endpoints. Private addresses are blocked.
+\`client.useMutation("vote", { optimistic(store, id) { store.update("results", [], (rows) => rows.map((r) =>
+(r.id === id ? { ...r, votes: r.votes + 1 } : r))) } })\`. The second argument of \`store.update\` is the query's
+argument list.
+
+## Pagination
+
+\`\`\`ts
+// server: the query takes PaginationOptions last and returns paginate(); cap numItems, which the client chooses.
+feed: query(async (ctx, listId: string, page: PaginationOptions) =>
+  ctx.db.items.withIndex("by_list", (q) => q.eq("listId", listId)).order("desc")
+    .paginate({ cursor: page.cursor, numItems: Math.min(page.numItems, 50) })),
+
+// client
+const { results, status, loadMore } = client.usePaginatedQuery("feed", ["some-list"], { initialNumItems: 20 });
+\`\`\`
 
-## Deploys without an account
+\`PaginationOptions\` comes from \`eraspace/server\`. \`status\` is \`"LoadingFirstPage"\`, \`"CanLoadMore"\`,
+\`"LoadingMore"\` or \`"Exhausted"\`; \`loadMore(n?)\` fetches the next page.
 
-A deploy without sign-in creates a temporary app and saves its claim token in \`.eraspace/\` (git-ignored). It has no
-server env or outbound fetch and expires after about a week. \`eraspace auth login\` then \`eraspace claim\` keeps it.
+## Scheduled mutations
+
+Mutations and writable endpoints run a mutation later with \`ctx.scheduler.runAfter(ms, "mutationName", ...args)\`,
+which returns a job id. The job commits with the mutation that schedules it, and its run commits at most once. For
+recurring work, the scheduled mutation schedules its next run.
+
+## HTTP endpoints
+
+\`\`\`ts
+import { endpoint, json } from "eraspace/server";
+
+endpoints: {
+  health: endpoint({ method: "GET", path: "/health", readOnly: true }, async (ctx, req) => json({ ok: true })),
+},
+\`\`\`
+
+- An endpoint is served at \`/<app>/<path>\`. \`readOnly: true\` gives it a read-only db; otherwise it writes like a
+  mutation.
+- \`req\` has \`method, path, url, headers.get(), query.get(), json(), text(), bytes(), formData()\`. Return
+  \`json(value)\`, \`text(string)\`, \`empty()\`, \`redirect(url)\` (each takes \`{ status, headers }\` last) or a
+  plain value (sent as JSON).
+- Endpoints are public: authenticate a webhook by checking its signature with \`crypto.subtle\`.
+
+## Reload on deploy
+
+Open tabs reload by themselves after each deploy. Pass \`createClient({ reloadOnDeploy: false })\` to keep the page
+and react to \`client.onDeployed(version => ...)\` instead.
 `;
 var GITIGNORE = [".eraspace/", ".env.eraspace.server"];
 var keepsOnInit = (name) => name.startsWith(".") || /^(README|LICENSE)(\.|$)/i.test(name);
@@ -40560,6 +40602,8 @@ var createCapsule = Effect_exports.fnUntraced(function* (directory, template, mo
     const files = {
       "eraspace.json": JSON.stringify({ name: app }, null, 2) + "\n",
       "AGENTS.md": agents(command2),
+      "CODING_STANDARDS.md": CODING_STANDARDS,
+      "FEATURES.md": FEATURES,
       "CLAUDE.md": "@AGENTS.md\n"
     };
     const gitignore = join7(destination, ".gitignore");
@@ -40659,7 +40703,7 @@ var config = Effect_exports.gen(function* () {
   return yield* loadConfig({ dir: value3(flags.dir), app: value3(flags.app), url: value3(flags.url) });
 });
 var deployFlags = {
-  name: optionalString("name", "Exact name for a new app, failing if it is taken (default: the eraspace.json or directory name, or a free variant of it)"),
+  name: optionalString("name", "Exact name for a new app, failing if it is taken (default: the eraspace.json or directory name, or a free variant of it). A redeploy refuses it; use eraspace names add"),
   publicInspect: Flag_exports.Boolean("public-inspect").pipe(Flag_exports.withDefault(false), Flag_exports.withDescription("Let anyone read this app's inspection data and logs"))
 };
 var deployOptions = (input) => ({ name: value3(input.name), publicInspect: input.publicInspect });
@@ -40714,6 +40758,32 @@ var deployCommand = Command_exports.make(
     { command: "eraspace deploy --fail-on-query-errors", description: "Deploy only if no live query starts throwing on the new code" }
   ])
 );
+var deploysCommand = Command_exports.make(
+  "deploys",
+  { app: optionalArg("app", "App name or id (default: this checkout's app)") },
+  ({ app }) => Effect_exports.flatMap(config, (c2) => deploys(c2, value3(app)))
+).pipe(Command_exports.withDescription("List the latest 50 kept versions you can roll back to, newest first"));
+var rollbackCommand = Command_exports.make(
+  "rollback",
+  {
+    version: Argument_exports.Int("version").pipe(
+      Argument_exports.withDescription("Version to roll back to (default: the newest kept version below the one serving)"),
+      Argument_exports.optional
+    ),
+    ...deleteTableFlag,
+    ...shadowFlags
+  },
+  (input) => Effect_exports.flatMap(
+    config,
+    (c2) => rollback(c2, value3(input.version), { deleteTables: value3(input.deleteTable), shadow: input.shadow, failOnQueryErrors: input.failOnQueryErrors })
+  )
+).pipe(
+  Command_exports.withDescription("Deploy an earlier version's server code, client files and server env again, as a new version"),
+  Command_exports.withExamples([
+    { command: "eraspace rollback", description: "Go back to the version before the one serving" },
+    { command: "eraspace rollback 3", description: "Serve version 3's code again" }
+  ])
+);
 var devCommand = Command_exports.make("dev", deployFlags, (input) => Effect_exports.flatMap(config, (c2) => dev(c2, deployOptions(input)))).pipe(
   Command_exports.withDescription("Deploy, then redeploy whenever server/, client/, shared/ or .env.eraspace.server change")
 );
@@ -40861,6 +40931,8 @@ var command = eraspace.pipe(
     initCommand,
     typecheckCommand,
     deployCommand,
+    deploysCommand,
+    rollbackCommand,
     devCommand,
     callCommand,
     explainCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eraspace",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "eraspace: build, deploy and manage eraspace capsules",
   "type": "module",
   "keywords": [

package/sdk/src/client/client.ts

@@ -13,7 +13,7 @@ import { Pager } from "./pagination.ts";
 
 export { readConfig, type EraspaceConfig, type ClientOptions } from "./config.ts";
 export { subKey } from "./sub-key.ts";
-export type { EraspaceClient, Room, PresenceEntry, MutationOptions, OptimisticStore, PaginatedQueryName, PaginatedQueryResult } from "./types.ts";
+export type { EraspaceClient, Room, PresenceEntry, MutationOptions, OptimisticStore, PaginatedQueryName, PaginatedQueryResult, Status } from "./types.ts";
 
 type Fn = (...args: any[]) => any;
 
@@ -114,11 +114,8 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
 
   function useRoom(room: string, meta?: Record<string, unknown>): Room<any, any> {
     const r = useRoomConn(room, meta);
-    return {
-      presence: r.members.value,
-      self: r.self.value,
-      state: r.state.value,
-      error: r.error.value,
+    // Stable per room, so effects and memoized children that depend on them do not rerun every render.
+    const methods = useMemo(() => ({
       broadcast: (event: string, payload?: unknown) => {
         void r.channel.push("broadcast", { event, payload: payload ?? null }).catch(error => { r.error.value = EraspaceError.from(error); });
       },
@@ -131,6 +128,13 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
       setState: (key: string, value: unknown) => {
         r.setState(key, value);
       },
+    }), [r]);
+    return {
+      presence: r.members.value,
+      self: r.self.value,
+      state: r.state.value,
+      error: r.error.value,
+      ...methods,
     };
   }
 

package/sdk/src/client/files.ts

@@ -343,6 +343,8 @@ export function FilePreview(props: FilePreviewProps) {
   if (meta === undefined || meta === null || meta === "failed" || broken === key) {
     // A media error cannot tell a missing file from a failed request, so every failure offers a retry.
     const retry = () => {
+      // Found metadata stays cached, so a file deleted since would show as found again and fail the same way.
+      infoCache.delete(client.storage.url(key));
       setBroken(null);
       setFetched(undefined);
       setAttempt((n) => n + 1);

package/sdk/src/client/index.ts

@@ -10,6 +10,7 @@ export {
   type PaginatedQueryResult,
   type PresenceEntry,
   type Room,
+  type Status,
   type EraspaceClient,
   type EraspaceConfig,
 } from "./client.ts";

package/sdk/src/client/sub-key.ts

@@ -18,9 +18,12 @@ function canonical(v: unknown): unknown {
   // Own data properties, so a `__proto__` key stays a key rather than setting the prototype.
   return Object.fromEntries(Object.keys(o).sort().map((k) => [k, canonical(o[k])]));
 }
+/** Sorted-key JSON. Like `JSON.stringify` and `canonicalArgs`, it serializes what `toJSON` returns, so two Dates differ. */
 export function stableStringify(v: unknown): string {
   if (v === undefined) return "null";
   if (v === null || typeof v !== "object") return JSON.stringify(v);
+  const json = (v as { toJSON?: unknown }).toJSON;
+  if (typeof json === "function") return stableStringify(json.call(v));
   if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
   const o = v as Record<string, unknown>;
   const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();

package/templates/chat/client/index.tsx

@@ -1,5 +1,5 @@
 import { createClient, FilePreview, FileUpload, type FileRef } from "eraspace/client";
-import { useState, useEffect } from "preact/hooks";
+import { useState, useEffect, useRef } from "preact/hooks";
 import type app from "../server/index";
 const client = createClient<typeof app>();
 export default function App() {
@@ -12,7 +12,12 @@ export default function App() {
   const [file, setFile] = useState<FileRef | null>(null);
   const messages = client.useQuery("messages", room);
   const send = client.useMutation("send");
-  const channel = client.useRoom<{ name: string }> (room, { name: author });
+  // Room messages share the app's request budget, so presence takes the name once typing pauses and the typing
+  // notice goes out at most once a second; the 1.5 s display below bridges the gap.
+  const [shownName, setShownName] = useState(author);
+  useEffect(() => { const timer = setTimeout(() => setShownName(author), 500); return () => clearTimeout(timer); }, [author]);
+  const lastTyping = useRef(0);
+  const channel = client.useRoom<{ name: string }> (room, { name: shownName });
   useEffect(() => channel.on("typing", (payload: unknown) => {
     if (typeof payload === "string") setTyping(payload);
   }), [room]);
@@ -29,7 +34,10 @@ export default function App() {
       try { await send(room, author, body, file); setBody(""); setFile(null); } catch (err) { setError(err instanceof Error ? err.message : String(err)); } finally { setSending(false); }
     }}>
       <input aria-label="Your name" value={author} maxLength={40} onInput={e => setAuthor(e.currentTarget.value)}/>
-      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => { setBody(e.currentTarget.value); channel.broadcast("typing", author); }}/>
+      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => {
+        setBody(e.currentTarget.value);
+        if (Date.now() - lastTyping.current >= 1000) { lastTyping.current = Date.now(); channel.broadcast("typing", author); }
+      }}/>
       <button disabled={sending || (!body.trim() && !file)}>Send</button>
       {file
         ? <div class="pending"><FilePreview client={client} file={file} caption={false} class="attachment"/><span>{file.name}</span><button type="button" class="subtle" disabled={sending} onClick={() => { void client.storage.delete(file.key).catch(() => {}); setFile(null); }}>Remove</button></div>