@irtio/cli 0.5.1 → 0.6.0

package/dist/deploy.js

@@ -0,0 +1,567 @@
+import {
+  logEnsured,
+  runStaticDeploy
+} from "./chunk-3HQMVCYA.js";
+import {
+  clientImportsRoom
+} from "./chunk-TQU6345E.js";
+import "./chunk-RQSJZWQC.js";
+import {
+  ensureProject,
+  readProjectConfig
+} from "./chunk-DKWG7MGO.js";
+import {
+  bundleRoom
+} from "./chunk-OTSFRVJN.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import {
+  ApiClientError,
+  createApiClient,
+  isLoginRequired
+} from "./chunk-RNAH5T4W.js";
+import {
+  resolveControlUrlForUser
+} from "./chunk-UPHQM6NZ.js";
+
+// src/deploy.ts
+import { existsSync, readdirSync } from "fs";
+import { mkdir, readFile, readdir, rm } from "fs/promises";
+import * as path from "path";
+import { createInterface } from "readline/promises";
+import { pathToFileURL } from "url";
+import { DEFAULT_ROOM_TYPE, ROOM_TYPE_RE } from "@irtio/protocol";
+import { diffSchemas, schemaFromCanonical } from "@irtio/schema";
+import pc from "picocolors";
+var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
+var MIGRATIONS_DIR = "irtio/migrations";
+var ROOM_TYPES_DIR = "irtio/rooms";
+var USAGE = `usage: irtio deploy [options]
+       irtio deploy --static [<dir>] [options]
+
+Bundles the room, classifies the schema change against the last deployment, and uploads. A
+breaking change is refused unless a migration covers it. With "static" in the project file the
+client directory ships too, after the room.
+
+options:
+  --allow-breaking          accept a breaking schema change that a migration covers
+  --strategy drain|migrate  drain (the default) lets running rooms finish on the old version;
+                            migrate moves live rooms onto the new one now
+  --room <file>             the room entry
+  --project <id>            project id (default: the project file)
+  --name <name>             the name a first deploy registers the project under
+  --no-static               deploy the room alone, even with "static" configured
+  -c, --config <f>          the project file to read (default irtio.json)
+  --url <control>           control plane (default: your stored login)
+  -h, --help                print this
+
+irtio deploy --static uploads a BUILT client directory and nothing else. It takes --label <label>
+plus --project, --name, --config and --url; the directory and label default to the project file.
+`;
+function parseDeployArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
+  const parsed = {
+    allowBreaking: false
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--allow-breaking":
+        parsed.allowBreaking = true;
+        break;
+      case "--no-static":
+        parsed.noStatic = true;
+        break;
+      case "--project": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio deploy: --project needs a value");
+        parsed.project = value;
+        break;
+      }
+      case "--name": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio deploy: --name needs a value");
+        }
+        parsed.name = value;
+        break;
+      }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio deploy: --config needs a value");
+        }
+        parsed.config = value;
+        break;
+      }
+      case "--url": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio deploy: --url needs a value");
+        parsed.url = value;
+        break;
+      }
+      case "--room": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio deploy: --room needs a value");
+        parsed.room = value;
+        break;
+      }
+      case "--strategy": {
+        const value = args[++i];
+        if (value !== "drain" && value !== "migrate") {
+          throw new Error('irtio deploy: --strategy must be "drain" or "migrate"');
+        }
+        parsed.strategy = value;
+        break;
+      }
+      default:
+        throw new Error(`irtio deploy: unknown option ${JSON.stringify(arg)}`);
+    }
+  }
+  return parsed;
+}
+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();
+  }
+}
+function findRoomEntry(cwd, room) {
+  if (room !== void 0) {
+    const file = path.resolve(cwd, room);
+    if (!existsSync(file)) throw new Error(`irtio deploy: no room file at ${file}`);
+    return file;
+  }
+  for (const candidate of ROOM_CANDIDATES) {
+    const file = path.resolve(cwd, candidate);
+    if (existsSync(file)) return file;
+  }
+  return void 0;
+}
+function resolveEntry(cwd, room) {
+  const entry = findRoomEntry(cwd, room);
+  if (entry !== void 0) return entry;
+  throw new Error(
+    `irtio deploy: no room file found in ${cwd}
+  looked for: ${ROOM_CANDIDATES.join(", ")}
+  pass --room <file> if it lives elsewhere`
+  );
+}
+function findRoomTypes(cwd, room) {
+  const dir = path.resolve(cwd, ROOM_TYPES_DIR);
+  const types = {};
+  if (existsSync(dir)) {
+    for (const name of readdirSync(dir).sort()) {
+      const ext = path.extname(name);
+      if (ext !== ".ts" && ext !== ".js") continue;
+      const type = name.slice(0, -ext.length);
+      if (!ROOM_TYPE_RE.test(type)) {
+        throw new Error(
+          `irtio deploy: ${path.join(ROOM_TYPES_DIR, name)} is not a usable room type name
+  a type name is lowercase letters, digits, "_" or "-", starting with a letter or digit, at most 24 characters
+  rename the file, or move it out of ${ROOM_TYPES_DIR}/ if it is not a room entry`
+        );
+      }
+      types[type] = path.join(dir, name);
+    }
+  }
+  const explicit = findRoomEntry(cwd, room);
+  if (explicit !== void 0) {
+    if (room === void 0 && types[DEFAULT_ROOM_TYPE] !== void 0) {
+      throw new Error(
+        `irtio deploy: this project names its default room type twice, in ${ROOM_CANDIDATES[0]} and in ${ROOM_TYPES_DIR}/default.ts
+  keep one of them: a plain roomId resolves to exactly one definition`
+      );
+    }
+    return { default: explicit, types: { ...types, [DEFAULT_ROOM_TYPE]: explicit } };
+  }
+  const fallback = types[DEFAULT_ROOM_TYPE];
+  if (fallback !== void 0) return { default: fallback, types };
+  if (Object.keys(types).length > 0) {
+    throw new Error(
+      `irtio deploy: ${ROOM_TYPES_DIR}/ declares ${Object.keys(types).join(", ")} but no default room type, and a roomId with no type prefix has to resolve to one
+  add ${ROOM_TYPES_DIR}/default.ts, or keep the single entry at ${ROOM_CANDIDATES[0]}`
+    );
+  }
+  const entry = resolveEntry(cwd, room);
+  return { default: entry, types: { [DEFAULT_ROOM_TYPE]: entry } };
+}
+async function warnIfClientImportsRoom(cwd, entry, config, log) {
+  const client = config.client;
+  if (client === void 0) return;
+  const clientFile = path.resolve(cwd, client);
+  if (await clientImportsRoom(clientFile, entry)) {
+    log(
+      pc.yellow(
+        `irtio: WARNING: the client entry ${client} imports the room file ${path.relative(cwd, entry)} \u2014 room code must never ship to clients; move shared code (e.g. the physics world builder) into its own module both sides import`
+      )
+    );
+  }
+}
+async function loadBundledSchema(file) {
+  const mod = await import(pathToFileURL(file).href);
+  const config = mod.default.config;
+  return {
+    project: mod.default.schema.project,
+    canonical: mod.default.schema.canonical,
+    schema: mod.default.schema,
+    memoryMb: typeof config?.memoryMb === "number" ? config.memoryMb : void 0,
+    maxAwake: typeof config?.maxAwake === "number" ? config.maxAwake : void 0,
+    // The declared string, verbatim and unparsed. `defineRoom` already refused anything the
+    // grammar does not accept, and control refuses it again; the CLI's job is to carry what the
+    // bundle says rather than to have an opinion of its own about a duration.
+    retention: typeof config?.retention === "string" ? config.retention : void 0
+  };
+}
+function printBreaking(log, breaking, hint) {
+  const n = breaking.length;
+  log(pc.red(`deploy refused: ${n} breaking change${n === 1 ? "" : "s"}`));
+  for (const change of breaking) log(`  ${change.message}`);
+  log("");
+  log(pc.yellow(hint));
+}
+async function findMigrationFile(cwd, version) {
+  const dir = path.join(cwd, MIGRATIONS_DIR);
+  if (!existsSync(dir)) return void 0;
+  const entries = await readdir(dir);
+  const match = entries.find((f) => f.startsWith(`${version}_`) && f.endsWith(".ts"));
+  return match ? path.join(dir, match) : void 0;
+}
+var DEPLOY_BUILD_DIR = path.join(".irtio", "deploy");
+async function runDeploy(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const log = options.log ?? ((line) => console.log(line));
+  const ask = options.ask ?? defaultAsk;
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const config = await readProjectConfig(cwd, "irtio deploy", options.config);
+  const roomTypes = findRoomTypes(cwd, options.room);
+  const entry = roomTypes.default;
+  await warnIfClientImportsRoom(cwd, entry, config, log);
+  const outDir = path.join(cwd, DEPLOY_BUILD_DIR);
+  await mkdir(outDir, { recursive: true });
+  let result;
+  try {
+    result = await bundleRoom({
+      entry,
+      outDir,
+      ...options.irtioPackages !== void 0 ? { irtioPackages: options.irtioPackages } : {}
+    });
+  } catch (err) {
+    throw new Error(`irtio deploy: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  log(pc.green(`bundled ${path.basename(result.file)} (${result.hash.slice(0, 12)})`));
+  const bundled = await loadBundledSchema(result.file);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const projectId = options.project ?? config.project ?? bundled.project;
+  if (projectId === void 0) {
+    throw new Error(
+      'irtio deploy: no project id \u2014 pass --project, add "project" to irtio.json, or set it in defineSchema(...)'
+    );
+  }
+  const ensured = await ensureProject(client, projectId, {
+    cwd,
+    config,
+    command: "irtio deploy",
+    ...options.name !== void 0 ? { name: options.name } : {}
+  });
+  logEnsured(log, projectId, ensured);
+  const deployments = await client.get(`/v1/projects/${projectId}/deployments`);
+  const newestOf = (list) => list.reduce(
+    (best, d) => best === void 0 || d.version > best.version ? d : best,
+    void 0
+  );
+  const previous = newestOf(deployments.filter((d) => d.rolledBackAt == null));
+  const newest = newestOf(deployments);
+  let allowBreaking = options.allowBreaking ?? false;
+  let migrationFile;
+  let schemaChange = "none";
+  const nextVersion = (newest?.version ?? 0) + 1;
+  if (previous !== void 0) {
+    const oldSchema = schemaFromCanonical(previous.schemaJson);
+    const changes = diffSchemas(oldSchema, bundled.schema);
+    const breaking = changes.filter((c) => c.kind === "breaking");
+    const additive = changes.filter((c) => c.kind === "additive");
+    schemaChange = breaking.length > 0 ? "breaking" : additive.length > 0 ? "additive" : "none";
+    if (breaking.length > 0) {
+      if (!allowBreaking) {
+        const hint = "run: irtio migrate create <name>";
+        printBreaking(log, breaking, hint);
+        throw new DeployRefusedError({ changes: breaking, hint });
+      }
+      migrationFile = await findMigrationFile(cwd, nextVersion);
+      if (migrationFile === void 0) {
+        const hint = `--allow-breaking needs a migration for v${nextVersion}. Run: irtio migrate create <name>`;
+        printBreaking(log, breaking, hint);
+        throw new DeployRefusedError({ changes: breaking, hint });
+      }
+      log(pc.yellow(`${breaking.length} breaking change(s), proceeding with --allow-breaking:`));
+      for (const change of breaking) log(`  ${change.message}`);
+    } else {
+      allowBreaking = false;
+    }
+    if (additive.length > 0) {
+      log(pc.cyan(`${additive.length} additive change(s):`));
+      for (const change of additive) log(`  ${change.message}`);
+    }
+    if (changes.length === 0) log(pc.dim("no schema changes"));
+  } else {
+    log(pc.dim("no previous deployment, so this is the first deploy for this project"));
+  }
+  let migrationKey;
+  if (migrationFile !== void 0) {
+    const migrationBundle = await bundleRoom({
+      entry: migrationFile,
+      outDir,
+      verify: false,
+      ...options.irtioPackages !== void 0 ? { irtioPackages: options.irtioPackages } : {}
+    });
+    const bytes = new Uint8Array(await readFile(migrationBundle.file));
+    const uploaded = await client.postBytes(
+      `/v1/projects/${projectId}/artifacts`,
+      bytes
+    );
+    migrationKey = uploaded.key;
+    log(pc.green(`bundled and uploaded migration ${path.basename(migrationFile)}`));
+  }
+  const roomBytes = new Uint8Array(await readFile(result.file));
+  const uploadedRoom = await client.postBytes(
+    `/v1/projects/${projectId}/artifacts`,
+    roomBytes
+  );
+  log(pc.green("uploaded bundle"));
+  const extraRooms = {};
+  for (const [type, typeEntry] of Object.entries(roomTypes.types)) {
+    if (type === DEFAULT_ROOM_TYPE) continue;
+    let typeResult;
+    try {
+      typeResult = await bundleRoom({
+        entry: typeEntry,
+        outDir,
+        ...options.irtioPackages !== void 0 ? { irtioPackages: options.irtioPackages } : {}
+      });
+    } catch (err) {
+      throw new Error(
+        `irtio deploy: room type "${type}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (typeResult.schemaHash === void 0) {
+      throw new Error(`irtio deploy: room type "${type}" bundled without a schema hash`);
+    }
+    const typeSchema = await loadBundledSchema(typeResult.file);
+    const uploaded = await client.postBytes(
+      `/v1/projects/${projectId}/artifacts`,
+      new Uint8Array(await readFile(typeResult.file))
+    );
+    extraRooms[type] = {
+      bundleHash: typeResult.hash,
+      bundleKey: uploaded.key,
+      schemaJson: typeSchema.canonical,
+      schemaHash: typeResult.schemaHash,
+      // M5 part 3.5: this type's sizing declarations travel with its bundle, so control and the
+      // host agent can size the VM before it boots. Spread, never null: a type that declares
+      // neither sends neither, and the env generation of a project that has never declared
+      // anything is unchanged.
+      ...typeSchema.memoryMb !== void 0 ? { memoryMb: typeSchema.memoryMb } : {},
+      ...typeSchema.maxAwake !== void 0 ? { maxAwake: typeSchema.maxAwake } : {},
+      ...typeSchema.retention !== void 0 ? { retention: typeSchema.retention } : {}
+    };
+    log(pc.green(`bundled and uploaded room type ${type} (${typeResult.hash.slice(0, 12)})`));
+  }
+  const hasExtraTypes = Object.keys(extraRooms).length > 0;
+  let origin;
+  if (previous === void 0) {
+    const answer = (await ask("production origin (localhost is always allowed) \u2014 leave blank to skip: ")).trim();
+    if (answer.length > 0) origin = answer;
+  }
+  const strategy = options.strategy ?? "drain";
+  if (strategy === "migrate") {
+    log(pc.yellow("strategy: migrate. Live rooms move onto the new version now."));
+    const physics = bundled.schema.collections.some(
+      (c) => c.physics !== void 0
+    );
+    if (schemaChange === "breaking") {
+      log(
+        pc.yellow(
+          "Breaking schema change: EVERY connected client is disconnected with E_SCHEMA_MISMATCH and must reload."
+        )
+      );
+    } else {
+      log(
+        pc.yellow(
+          schemaChange === "none" ? "Schema unchanged: connected clients see a short gap and a resync on the same socket." : "Additive schema change: connected clients see a short gap and a resync on the same socket, on the new schema."
+        )
+      );
+      if (physics) {
+        log(
+          pc.yellow(
+            "This schema has physics collections. A change touching one of those is treated as breaking for now, so those clients reload."
+          )
+        );
+      }
+      log(
+        pc.dim(
+          "Clients built before irtio 0.6 are still disconnected with E_SCHEMA_MISMATCH on any schema change."
+        )
+      );
+    }
+  }
+  let response;
+  try {
+    const created = await client.post(`/v1/projects/${projectId}/deployments`, {
+      bundleHash: result.hash,
+      bundleKey: uploadedRoom.key,
+      schemaJson: bundled.canonical,
+      schemaHash: result.schemaHash,
+      // M5 part 3.5: the default type's declarations, top-level beside its schema for the reason
+      // `DeploymentSpec` states — the default type is not in the `rooms` map, and putting it there
+      // would give every single-room project a `rooms` key and cold-boot the fleet.
+      ...bundled.memoryMb !== void 0 ? { memoryMb: bundled.memoryMb } : {},
+      ...bundled.maxAwake !== void 0 ? { maxAwake: bundled.maxAwake } : {},
+      ...bundled.retention !== void 0 ? { retention: bundled.retention } : {},
+      ...hasExtraTypes ? { rooms: extraRooms } : {},
+      ...migrationKey !== void 0 ? { migrationKey } : {},
+      ...allowBreaking ? { allowBreaking: true } : {},
+      ...origin !== void 0 ? { origin } : {},
+      ...strategy !== "drain" ? { strategy } : {}
+    });
+    response = {
+      project: projectId,
+      version: created.version,
+      url: created.url,
+      draining: created.draining,
+      ...created.applied !== void 0 ? { applied: created.applied } : {},
+      ...created.rooms !== void 0 ? { rooms: created.rooms } : {}
+    };
+  } catch (err) {
+    if (err instanceof ApiClientError && err.code === "E_BREAKING_SCHEMA" && err.changes) {
+      const changes = err.changes;
+      const hint = err.hint ?? "run: irtio migrate create <name>";
+      printBreaking(log, changes, hint);
+      throw new DeployRefusedError({ changes, hint });
+    }
+    throw err;
+  }
+  await rm(outDir, { recursive: true, force: true }).catch(() => {
+  });
+  log(pc.green(`deployed v${response.version}`));
+  log(pc.dim(`reachable at ${response.url}`));
+  if (strategy === "migrate") {
+    if (response.applied === "live") {
+      const rooms = response.rooms ?? [];
+      if (rooms.length === 0) log(pc.dim("no live rooms to migrate"));
+      for (const r of rooms) {
+        const line = `  ${r.roomId}: ${r.outcome}${r.reason ? ` \u2014 ${r.reason}` : ""}`;
+        log(r.outcome === "failed" ? pc.red(line) : pc.dim(line));
+      }
+    } else {
+      log(pc.dim("no tenant is running; rooms migrate on their next wake"));
+    }
+  } else if (previous !== void 0) {
+    if (response.applied === "live") {
+      log(
+        pc.dim(
+          `rooms already running finish on v${previous.version}; new rooms start on v${response.version}`
+        )
+      );
+    } else {
+      log(pc.dim(`rooms already running finish on v${previous.version}`));
+    }
+  }
+  if (config.static !== void 0 && options.noStatic !== true) {
+    const site = await runStaticDeploy({
+      cwd,
+      project: projectId,
+      log,
+      client,
+      controlUrl,
+      dir: config.static.dir,
+      ...config.static.label !== void 0 ? { label: config.static.label } : {},
+      ...options.config !== void 0 ? { config: options.config } : {}
+    });
+    return { ...response, site };
+  }
+  return response;
+}
+var DeployRefusedError = class extends Error {
+  name = "DeployRefusedError";
+  /** The breaking changes that caused the refusal, as the classifier reported them. */
+  changes;
+  /** The remedy, verbatim: normally `run: irtio migrate create <name>`. */
+  hint;
+  constructor(reason = {}) {
+    super("deploy refused");
+    this.changes = reason.changes ?? [];
+    this.hint = reason.hint;
+  }
+};
+async function deploy(args, deps = {}) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  try {
+    const parsed = parseDeployArgs(args);
+    const cwd = path.resolve(deps.cwd ?? process.cwd());
+    const config = await readProjectConfig(cwd, "irtio deploy", parsed.config);
+    if (parsed.room === void 0 && parsed.noStatic !== true && config.static !== void 0 && findRoomEntry(cwd, void 0) === void 0) {
+      log(pc.dim("no room file, so deploying the static site only"));
+      await runStaticDeploy({
+        cwd,
+        log,
+        dir: config.static.dir,
+        ...config.static.label !== void 0 ? { label: config.static.label } : {},
+        ...parsed.project !== void 0 ? { project: parsed.project } : {},
+        ...parsed.name !== void 0 ? { name: parsed.name } : {},
+        ...parsed.config !== void 0 ? { config: parsed.config } : {},
+        ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
+        ...deps.client !== void 0 ? { client: deps.client } : {}
+      });
+      return;
+    }
+    await runDeploy({
+      allowBreaking: parsed.allowBreaking,
+      log,
+      ...parsed.project !== void 0 ? { project: parsed.project } : {},
+      ...parsed.name !== void 0 ? { name: parsed.name } : {},
+      ...parsed.config !== void 0 ? { config: parsed.config } : {},
+      ...parsed.noStatic !== void 0 ? { noStatic: parsed.noStatic } : {},
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
+      ...parsed.room !== void 0 ? { room: parsed.room } : {},
+      ...parsed.strategy !== void 0 ? { strategy: parsed.strategy } : {},
+      ...deps.client !== void 0 ? { client: deps.client } : {},
+      ...deps.cwd !== void 0 ? { cwd: deps.cwd } : {},
+      ...deps.irtioPackages !== void 0 ? { irtioPackages: deps.irtioPackages } : {}
+    });
+  } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
+    if (err instanceof DeployRefusedError) {
+      process.exitCode = 1;
+      return;
+    }
+    if (isLoginRequired(err)) {
+      errorLog(pc.red("not logged in"));
+      errorLog("run: irtio login");
+      process.exitCode = 1;
+      return;
+    }
+    errorLog(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+  }
+}
+export {
+  DeployRefusedError,
+  USAGE,
+  deploy,
+  findRoomEntry,
+  findRoomTypes,
+  parseDeployArgs,
+  runDeploy
+};