@irtio/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+// src/index.ts
+var [, , command, ...args] = process.argv;
+var HELP = `irtio \u2014 multiplayer rooms for web games
+
+usage: irtio <command>
+
+commands:
+  init [dir] [--tick|--event]                     scaffold irtio/schema.ts, rpc.ts, room.ts,
+                                                  room.test.ts and irtio.json (--tick/--event
+                                                  skip the one question it otherwise asks)
+  dev [--room <file>] [--port <n>] [--no-watch]   bundle the room file and run it locally
+  simulate [--bots <n>] [--seconds <n>]           drive N real clients at a running room and
+          [--room <code>] [--url <ws://\u2026>]        check the built-in invariants
+          [--cheat] [--key <projectKey>]          --cheat sends illegal writes and expects
+          [--trace <path>]                        corrections; --trace dumps every frame
+
+  login [--url <control>]                         sign in to a control plane via the browser
+  whoami [--url <control>]                         print the identity the stored credential
+                                                  resolves to, and the control URL asked
+  deploy [--allow-breaking] [--project <id>]      bundle, classify the schema change against the
+         [--url <control>] [--room <file>]        last deployment, and upload \u2014 refuses breaking
+                                                  changes unless a migration covers them
+  migrate create <name>                           scaffold irtio/migrations/<n>_<name>.ts with the
+                                                  live breaking changes quoted in its header
+  logs [--follow] [--since <cursor>]              tail a project's logs
+       [--project <id>] [--url <control>]
+  rooms [--project <id>] [--url <control>]        list a project's rooms (rows not reported for
+                                                  longer than the control plane's retention
+                                                  window, 30 days by default, are pruned)
+`;
+switch (command) {
+  case "init": {
+    const { init } = await import("./init.js");
+    await init(args);
+    break;
+  }
+  case "dev": {
+    const { dev } = await import("./dev-BFWFWJ4J.js");
+    await dev(args);
+    break;
+  }
+  case "simulate": {
+    const { simulate } = await import("./simulate.js");
+    await simulate(args);
+    break;
+  }
+  case "login": {
+    const { login } = await import("./login-US2YT5ZB.js");
+    await login(args);
+    break;
+  }
+  case "whoami": {
+    const { whoami } = await import("./whoami-5Q32SXFX.js");
+    await whoami(args);
+    break;
+  }
+  case "deploy": {
+    const { deploy } = await import("./deploy-4W6AYYEW.js");
+    await deploy(args);
+    break;
+  }
+  case "migrate": {
+    const { migrate } = await import("./migrate-FQIDF747.js");
+    await migrate(args);
+    break;
+  }
+  case "logs": {
+    const { logs } = await import("./logs-6GLBO3TP.js");
+    await logs(args);
+    break;
+  }
+  case "rooms": {
+    const { rooms } = await import("./rooms-JXT3PRHN.js");
+    await rooms(args);
+    break;
+  }
+  case void 0:
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(HELP);
+    break;
+  default:
+    console.error(`irtio: unknown command ${JSON.stringify(command)}
+`);
+    console.log(HELP);
+    process.exitCode = 1;
+}

package/dist/init.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `irtio init`: the four files a room needs, plus a passing smoke test.
+ *
+ * It asks exactly one question, because the only thing `init` cannot infer is whether the world
+ * moves on its own: tick mode runs a fixed loop, event mode only reacts. Everything else — the
+ * `players` entity, the `onJoin`/`onLeave` spawn block, the project id — is a convention the
+ * templates carry so an agent copies the pattern instead of inventing one.
+ *
+ * Two rules shape the code. Nothing is ever overwritten (a second `init` reports what it skipped
+ * and leaves your room alone), and the printed output is the whole onboarding document: it has to
+ * take a human from an empty directory to two tabs sharing a `?room=` link with nothing else open.
+ */
+/** The two ways a room can change state. `init` picks one and writes it into `room.ts`. */
+type RoomMode = 'tick' | 'event';
+/** The packages a scaffolded project needs; added to `package.json` when there is one. */
+declare const INIT_DEPENDENCIES: readonly ["@irtio/schema", "@irtio/server", "@irtio/client", "@irtio/testing"];
+interface InitArgs {
+    /** Target directory, relative to the cwd. Defaults to `.`. */
+    readonly dir?: string;
+    /** Set by `--tick` / `--event`; absent means "ask". */
+    readonly mode?: RoomMode;
+}
+interface RunInitOptions {
+    /** Where the project lives. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    readonly dir?: string;
+    readonly mode?: RoomMode;
+    /**
+     * Asks the one question. Injected so tests never touch a TTY; the default reads stdin when it
+     * is a TTY and otherwise takes the default answer rather than hanging in a pipeline.
+     */
+    readonly ask?: (question: string) => Promise<string>;
+    readonly log?: (line: string) => void;
+    /** @internal Pins the generated project id so tests can assert it end to end. */
+    readonly projectId?: string;
+}
+interface InitResult {
+    /** Absolute path of the scaffolded project. */
+    readonly dir: string;
+    readonly project: string;
+    readonly mode: RoomMode;
+    /** Files written, relative to `dir`, in emit order. */
+    readonly created: readonly string[];
+    /** Files that already existed and were left untouched. */
+    readonly skipped: readonly string[];
+    /** Whether a `package.json` was found, and whether it needed changing. */
+    readonly packageJson: 'updated' | 'unchanged' | 'absent';
+}
+/**
+ * `irtio init [dir] [--tick|--event]`. Hand-rolled like `parseDevArgs`: the CLI has no
+ * argument-parsing dependency and four flags do not earn one.
+ */
+declare function parseInitArgs(args: readonly string[]): InitArgs;
+/** `p_` + 16 hex characters: the project id *is* the public key, so it is not a secret. */
+declare function generateProjectId(): string;
+/**
+ * Scaffolds a project. Pure enough to test: every effect is a file write under `dir`, every
+ * question goes through `ask`, and every line of output goes through `log`.
+ */
+declare function runInit(options?: RunInitOptions): Promise<InitResult>;
+/** Thin on purpose: parse, run, and turn a thrown message into an exit code. */
+declare function init(args: readonly string[]): Promise<void>;
+
+export { INIT_DEPENDENCIES, type InitArgs, type InitResult, type RoomMode, type RunInitOptions, generateProjectId, init, parseInitArgs, runInit };

package/dist/init.js

@@ -0,0 +1,307 @@
+// src/init.ts
+import { randomBytes } from "crypto";
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import * as path from "path";
+import { createInterface } from "readline/promises";
+import pc from "picocolors";
+var INIT_DEPENDENCIES = [
+  "@irtio/schema",
+  "@irtio/server",
+  "@irtio/client",
+  "@irtio/testing"
+];
+var DEFAULT_TICK_RATE = 20;
+var DEFAULT_IDLE_MS = 3e4;
+function parseInitArgs(args) {
+  const parsed = {};
+  for (const arg of args) {
+    switch (arg) {
+      case "--tick":
+      case "--event": {
+        const mode = arg === "--tick" ? "tick" : "event";
+        if (parsed.mode !== void 0 && parsed.mode !== mode) {
+          throw new Error("irtio init: --tick and --event are mutually exclusive");
+        }
+        parsed.mode = mode;
+        break;
+      }
+      default: {
+        if (arg.startsWith("-"))
+          throw new Error(`irtio init: unknown option ${JSON.stringify(arg)}`);
+        if (parsed.dir !== void 0) {
+          throw new Error(`irtio init: unexpected extra argument ${JSON.stringify(arg)}`);
+        }
+        parsed.dir = arg;
+      }
+    }
+  }
+  return parsed;
+}
+function generateProjectId() {
+  return `p_${randomBytes(8).toString("hex")}`;
+}
+function schemaTemplate(project) {
+  return `/**
+ * Shared facts about the data. Both sides import this file \u2014 the room to run on, your game
+ * to draw from \u2014 so it also carries the project id, which is the public key: domain-locked, never
+ * secret, safe in client code.
+ */
+
+import { defineSchema, entity, f32, str, u8 } from '@irtio/schema';
+
+import { rpc } from './rpc.js';
+
+export const schema = defineSchema(
+  {
+    // One instance per connected client, owned by that client (see onJoin in room.ts). Owned
+    // means writable: \`room.state.players[room.me].x = 10\` on the client is a local write that
+    // syncs, and the server validates it.
+    players: entity({ x: f32, y: f32, name: str(24), color: u8 }),
+  },
+  {
+    project: '${project}',
+    roles: ['player', 'spectator'] as const,
+    rpc,
+  },
+);
+`;
+}
+var RPC_TEMPLATE = `/**
+ * Typed calls in both directions, declared once and implemented exhaustively. Both sides
+ * import this file and the names are part of the schema hash, so a signature change is caught as
+ * version skew instead of at runtime.
+ *
+ * Nothing here yet \u2014 the retrofit path needs owned writes, not RPCs. Uncomment as you need them:
+ *
+ *   import { server, client, u8, str, f32, list } from '@irtio/schema';
+ *
+ *   export const rpc = {
+ *     // client \u2192 server, void (what other engines call an "input"):
+ *     answer:    server({ params: { choice: u8 } }),
+ *     // client \u2192 server with a typed return; await it as room.call.dealCards({ count: 5 }):
+ *     dealCards: server({ params: { count: u8 }, returns: { cards: list(str(8), 52) } }),
+ *     // server \u2192 client, void; the room calls room.broadcast.shake({ intensity: 1 }):
+ *     shake:     client({ params: { intensity: f32 } }),
+ *   };
+ */
+
+export const rpc = {};
+`;
+function roomTemplate(mode) {
+  const config = mode === "tick" ? `  // Tick mode: a fixed-rate loop runs even when nobody is doing anything.
+  mode: 'tick',
+  tickRate: ${DEFAULT_TICK_RATE},` : `  // Event mode: nothing runs between frames, so the room hibernates when it goes quiet.
+  mode: 'event',
+  idleMs: ${DEFAULT_IDLE_MS / 1e3}_000,`;
+  const tick = mode === "tick" ? `
+  // Fixed-rate; \`dt\` is seconds since the last tick. Move whatever the players do not move
+  // themselves \u2014 everything you write here is tracked and goes out in this tick's delta.
+  tick(_state, _dt, _room) {},
+` : "";
+  return `/**
+ * Behavior. Server-only: \`irtio dev\` and \`irtio deploy\` bundle this file, and it never
+ * reaches the browser. Everything is synchronous \u2014 a handler returns, the runtime encodes.
+ */
+
+import { defineRoom } from '@irtio/server';
+
+import { schema } from './schema.js';
+
+export default defineRoom(schema, {
+${config}
+
+  // Lifecycle is code, not config. The per-client entity is created here and owned by the
+  // client that caused the join, which is exactly what makes \`room.state.players[room.me]\`
+  // writable on that client and read-only on everyone else's.
+  onJoin(state, ctx) {
+    if (ctx.reconnecting) return;
+    state.players.add(
+      ctx.clientId,
+      { x: 0, y: 0, name: ctx.name || 'anon', color: (ctx.tick * 37) % 256 },
+      { owner: ctx.clientId },
+    );
+  },
+
+  onLeave(state, ctx) {
+    state.players.remove(ctx.clientId);
+  },
+
+  // Owner writes pass through here before they are accepted: return \`next\` to accept, \`prev\` to
+  // reject, or a clamped object. This is where cheating stops; delete it and anything in range
+  // is accepted.
+  validate: {
+    players(_prev, next) {
+      return next;
+    },
+  },
+${tick}});
+`;
+}
+var ROOM_TEST_TEMPLATE = `/**
+ * The smoke test \`irtio init\` scaffolds: two clients join, one writes a field it owns, and every
+ * view agrees with the server. \`testRoom\` runs the real room and real client semantics in
+ * process \u2014 no sockets, no server, fake clock \u2014 so this is a unit test in every way that matters.
+ *
+ * Extend it: that is what it is for.
+ */
+
+import { expect, test } from 'vitest';
+
+import { testRoom } from '@irtio/testing';
+import '@irtio/testing/matchers';
+
+import room from './room.js';
+
+test('two players join, and a write to my own player reaches everyone', async () => {
+  const t = await testRoom(room);
+  const [a, b] = await t.join(2, { role: 'player' });
+
+  const mine = a.state.players.get(a.me);
+  expect(mine).toBeDefined();
+  mine!.x = 10;
+  a.flush();
+  await t.tick(2);
+
+  expect(t.state.players.get(a.me)?.x).toBe(10);
+  expect(b.state.players.get(a.me)?.x).toBe(10);
+  expect(t).toHaveConverged();
+});
+`;
+function nextSteps(installCommand) {
+  return [
+    "",
+    pc.bold("next:"),
+    "",
+    "  1. install the packages",
+    pc.cyan(`       ${installCommand}`),
+    "",
+    "  2. start the room",
+    pc.cyan("       npx irtio dev"),
+    "     it prints a ws:// URL and an inspector page.",
+    "",
+    "  3. join from your game \u2014 three lines:",
+    "",
+    pc.cyan("       import { joinRoom } from '@irtio/client';"),
+    pc.cyan("       import { schema } from './irtio/schema.js';"),
+    "",
+    pc.cyan("       const room = await joinRoom(schema);        // reads ?room=, or creates one"),
+    pc.cyan("       const me = room.state.players[room.me];     // yours: write it like a local"),
+    pc.cyan("       me.x = 10;                                  // object, and it syncs"),
+    "",
+    "     draw everyone else the same way you drew one player:",
+    pc.cyan("       for (const [id, p] of room.state.players) draw(p);"),
+    "",
+    "  4. open your page, then look at the address bar: it now ends in ?room=CODE.",
+    "     copy that whole URL into a second tab. Both tabs are in the same room, and",
+    "     each sees the other move. (Drop in <irt-lobby> from @irtio/lobby and it",
+    "     shows the code, the link and a QR for you.)",
+    "",
+    "  5. check it under load before you believe it",
+    pc.cyan("       npx irtio simulate --bots 5 --seconds 10"),
+    ""
+  ];
+}
+async function defaultAsk(question) {
+  if (!process.stdin.isTTY) return "";
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+async function updatePackageJson(file) {
+  const source = await readFile(file, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (err) {
+    throw new Error(`irtio init: ${file} is not valid JSON: ${String(err)}`);
+  }
+  const deps = { ...parsed.dependencies ?? {} };
+  let changed = false;
+  for (const name of INIT_DEPENDENCIES) {
+    if (deps[name] === void 0) {
+      deps[name] = "^0.0.0";
+      changed = true;
+    }
+  }
+  if (!changed) return "unchanged";
+  parsed.dependencies = Object.fromEntries(
+    Object.entries(deps).sort(([a], [b]) => a < b ? -1 : 1)
+  );
+  await writeFile(file, `${JSON.stringify(parsed, null, 2)}
+`, "utf8");
+  return "updated";
+}
+async function runInit(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const dir = path.resolve(cwd, options.dir ?? ".");
+  const log = options.log ?? ((line) => console.log(line));
+  const ask = options.ask ?? defaultAsk;
+  let mode = options.mode;
+  if (mode === void 0) {
+    const answer = (await ask("does anything move without a player doing something? (y/n) ")).trim().toLowerCase();
+    mode = answer.startsWith("n") ? "event" : "tick";
+  }
+  const configFile = path.join(dir, "irtio.json");
+  let project = options.projectId ?? generateProjectId();
+  if (existsSync(configFile)) {
+    try {
+      const existing = JSON.parse(await readFile(configFile, "utf8"));
+      if (typeof existing.project === "string" && existing.project !== "")
+        project = existing.project;
+    } catch {
+    }
+  }
+  const files = [
+    ["irtio/schema.ts", schemaTemplate(project)],
+    ["irtio/rpc.ts", RPC_TEMPLATE],
+    ["irtio/room.ts", roomTemplate(mode)],
+    ["irtio/room.test.ts", ROOM_TEST_TEMPLATE],
+    ["irtio.json", `${JSON.stringify({ project }, null, 2)}
+`]
+  ];
+  const created = [];
+  const skipped = [];
+  await mkdir(path.join(dir, "irtio"), { recursive: true });
+  for (const [relative, contents] of files) {
+    const file = path.join(dir, relative);
+    if (existsSync(file)) {
+      skipped.push(relative);
+      continue;
+    }
+    await writeFile(file, contents, "utf8");
+    created.push(relative);
+  }
+  const packageFile = path.join(dir, "package.json");
+  const packageJson = existsSync(packageFile) ? await updatePackageJson(packageFile) : "absent";
+  if (created.length > 0) log(pc.green(`created ${created.join(", ")}`));
+  if (skipped.length > 0) {
+    log(pc.yellow(`kept ${skipped.join(", ")} (already there \u2014 nothing was overwritten)`));
+  }
+  log(pc.dim(`project ${project} \xB7 ${mode} mode`));
+  const installCommand = packageJson === "absent" ? `npm i ${INIT_DEPENDENCIES.join(" ")}` : "npm install   # the four irtio packages were added to your package.json";
+  for (const line of nextSteps(installCommand)) log(line);
+  return { dir, project, mode, created, skipped, packageJson };
+}
+async function init(args) {
+  try {
+    const parsed = parseInitArgs(args);
+    await runInit({
+      ...parsed.dir !== void 0 ? { dir: parsed.dir } : {},
+      ...parsed.mode !== void 0 ? { mode: parsed.mode } : {}
+    });
+  } catch (err) {
+    console.error(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+  }
+}
+export {
+  INIT_DEPENDENCIES,
+  generateProjectId,
+  init,
+  parseInitArgs,
+  runInit
+};

package/dist/login-US2YT5ZB.js

@@ -0,0 +1,136 @@
+import {
+  credentialsPath,
+  resolveControlUrl,
+  writeCredential
+} from "./chunk-UYN5PWLT.js";
+
+// src/login.ts
+import { spawn } from "child_process";
+import { randomBytes } from "crypto";
+import { createServer } from "http";
+import pc from "picocolors";
+var LOGIN_TIMEOUT_MS = 3 * 60 * 1e3;
+function parseLoginArgs(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--url") {
+      const value = args[++i];
+      if (value === void 0) throw new Error("irtio login: --url needs a value");
+      parsed.url = value;
+    } else {
+      throw new Error(`irtio login: unknown option ${JSON.stringify(arg)}`);
+    }
+  }
+  return parsed;
+}
+function isLoopback(req) {
+  const addr = req.socket.remoteAddress?.replace(/^::ffff:/, "");
+  return addr === "127.0.0.1" || addr === "::1";
+}
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function defaultOpenBrowser(url) {
+  const platform = process.platform;
+  if (platform === "win32") {
+    spawn("cmd", ["/c", "start", '""', url], { stdio: "ignore", detached: true }).unref();
+  } else if (platform === "darwin") {
+    spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+  } else {
+    spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+  }
+}
+async function runLogin(options = {}) {
+  const controlUrl = resolveControlUrl(options.controlUrl);
+  const log = options.log ?? ((line) => console.log(line));
+  const openBrowser = options.openBrowser ?? defaultOpenBrowser;
+  const timeoutMs = options.timeoutMs ?? LOGIN_TIMEOUT_MS;
+  const state = randomBytes(8).toString("hex");
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      server.close();
+      fn();
+    };
+    const server = createServer((req, res) => {
+      void (async () => {
+        if (!isLoopback(req)) {
+          res.writeHead(403).end();
+          return;
+        }
+        if (req.method !== "POST" || req.url?.split("?")[0] !== "/token") {
+          res.writeHead(404).end();
+          return;
+        }
+        try {
+          const body = await readBody(req);
+          const parsed = JSON.parse(body);
+          if (typeof parsed.token !== "string" || typeof parsed.expiresAt !== "string") {
+            res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: "expected { token, expiresAt }" }));
+            return;
+          }
+          const credential = {
+            token: parsed.token,
+            expiresAt: parsed.expiresAt,
+            ...typeof parsed.email === "string" && parsed.email !== "" ? { email: parsed.email } : {}
+          };
+          const file = await writeCredential(controlUrl, credential);
+          res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true }));
+          finish(() => resolve({ controlUrl, email: credential.email, file }));
+        } catch (err) {
+          res.writeHead(500).end();
+          finish(() => reject(err instanceof Error ? err : new Error(String(err))));
+        }
+      })();
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      const authUrl = `${controlUrl}/cli-auth?port=${port}&state=${state}`;
+      log(`opening ${authUrl}`);
+      try {
+        openBrowser(authUrl);
+      } catch {
+        log("could not open a browser \u2014 open this:");
+        log(pc.cyan(`  ${authUrl}`));
+      }
+      log("waiting for the browser to finish signing in\u2026");
+    });
+    server.on("error", (err) => finish(() => reject(err)));
+    const timer = setTimeout(() => {
+      finish(
+        () => reject(
+          new Error(
+            "irtio login: timed out waiting for the browser after 3 minutes \u2014 run `irtio login` again"
+          )
+        )
+      );
+    }, timeoutMs);
+  });
+}
+async function login(args) {
+  try {
+    const parsed = parseLoginArgs(args);
+    const result = await runLogin({
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {}
+    });
+    console.log(pc.green(`logged in as ${result.email ?? "(email not provided by the server)"}`));
+    console.log(pc.dim(`control plane: ${result.controlUrl}`));
+    console.log(pc.dim(`credentials stored at ${result.file ?? credentialsPath()}`));
+  } catch (err) {
+    console.error(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+  }
+}
+export {
+  defaultOpenBrowser,
+  login,
+  parseLoginArgs,
+  runLogin
+};