@irtio/cli 0.6.0 → 0.7.0

package/dist/{leaderboard-SYPSBPS3.js → leaderboard-ZBJBKETM.js}

@@ -1,15 +1,15 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";
@@ -33,6 +33,9 @@ delete   remove a whole board, or one player's row with --player. Needs your log
 
 options:
   --limit <n>        how many rows (default 10, max 100)
+  --period <key>     read a past period (2026-09-03, 2026-W36, 2026-09, or a season
+                     name). Default: whichever period the board is in now
+  --bucket <name>    which cohort to read, on a board configured with buckets
   --cursor <c>       continue from a previous page's nextCursor
   --all              page through the whole board, following cursors
   --around <player>  show the rows around one player instead of the top, with their rank
@@ -63,6 +66,23 @@ function parseLeaderboardArgs(args) {
       case "--all":
         parsed.all = true;
         break;
+      // ---- M6 lane B: boards ----
+      case "--period": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio leaderboard: --period needs a period key, e.g. 2026-W36");
+        }
+        parsed.period = value;
+        break;
+      }
+      case "--bucket": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio leaderboard: --bucket needs a bucket name, e.g. eu");
+        }
+        parsed.bucket = value;
+        break;
+      }
       case "--yes":
         parsed.yes = true;
         break;
@@ -125,7 +145,12 @@ function parseLeaderboardArgs(args) {
 }
 function formatLeaderboard(body, around) {
   const direction = body.direction === "lower" ? "lower is better" : "higher is better";
-  const out = [pc.dim(`board ${body.board}  \xB7  ${direction}`), ""];
+  const scope = [
+    body.period === void 0 || body.period === "" ? void 0 : `period ${body.period}`,
+    body.bucket === void 0 || body.bucket === "" ? void 0 : `bucket ${body.bucket}`
+  ].filter((part) => part !== void 0);
+  const header = [`board ${body.board}`, ...scope, direction].join("  \xB7  ");
+  const out = [pc.dim(header), ""];
   if (body.entries.length === 0) {
     out.push(
       pc.dim(
@@ -150,20 +175,29 @@ async function runLeaderboard(options) {
   const base = `${controlUrl}/v1/leaderboard/${encodeURIComponent(
     options.project
   )}/${encodeURIComponent(options.board)}`;
+  const scoped = () => {
+    const query = new URLSearchParams();
+    if (options.period !== void 0) query.set("period", options.period);
+    if (options.bucket !== void 0) query.set("bucket", options.bucket);
+    return query;
+  };
+  const withQuery = (url, query) => {
+    const q = query.toString();
+    return `${url}${q === "" ? "" : `?${q}`}`;
+  };
   if (options.around !== void 0) {
     const body2 = await readPublicJson(
       fetchImpl,
-      `${base}/around/${encodeURIComponent(options.around)}`
+      withQuery(`${base}/around/${encodeURIComponent(options.around)}`, scoped())
     );
     for (const line of formatLeaderboard(body2, options.around)) log(line);
     return body2;
   }
   const pageUrl = (cursor) => {
-    const query = new URLSearchParams();
+    const query = scoped();
     if (options.limit !== void 0) query.set("limit", String(options.limit));
     if (cursor !== void 0) query.set("cursor", cursor);
-    const q = query.toString();
-    return `${base}/top${q === "" ? "" : `?${q}`}`;
+    return withQuery(`${base}/top`, query);
   };
   let body = await readPublicJson(fetchImpl, pageUrl(options.cursor));
   const entries = [...body.entries];
@@ -210,10 +244,22 @@ function formatBoardList(boards) {
     ];
   }
   const nameWidth = Math.max(5, ...boards.map((b) => b.board.length));
-  const out = [pc.dim(`${"BOARD".padEnd(nameWidth)}  ${"ROWS".padStart(7)}  DIRECTION`)];
+  const rotates = boards.some((b) => b.period !== void 0 || b.buckets === true);
+  const periodOf = (b) => b.period === void 0 ? "all-time" : `${b.period}${b.currentPeriod === void 0 ? "" : ` (${b.currentPeriod})`}`;
+  const periodWidth = rotates ? Math.max(6, ...boards.map((b) => periodOf(b).length)) : 0;
+  const head = rotates ? `${"BOARD".padEnd(nameWidth)}  ${"ROWS".padStart(7)}  ${"PERIOD".padEnd(periodWidth)}  DIRECTION` : `${"BOARD".padEnd(nameWidth)}  ${"ROWS".padStart(7)}  DIRECTION`;
+  const out = [pc.dim(head)];
   for (const b of boards) {
-    const note = b.configured && b.rows === 0 ? pc.dim("  (configured, no rows yet)") : "";
-    out.push(`${b.board.padEnd(nameWidth)}  ${String(b.rows).padStart(7)}  ${b.direction}${note}`);
+    const notes = [
+      b.buckets === true ? "buckets" : void 0,
+      b.keep === void 0 ? void 0 : `keeps ${b.keep}`,
+      b.configured && b.rows === 0 ? "configured, no rows yet" : void 0
+    ].filter((n) => n !== void 0);
+    const note = notes.length === 0 ? "" : pc.dim(`  (${notes.join(", ")})`);
+    const scope = rotates ? `${periodOf(b).padEnd(periodWidth)}  ` : "";
+    out.push(
+      `${b.board.padEnd(nameWidth)}  ${String(b.rows).padStart(7)}  ${scope}${b.direction}${note}`
+    );
   }
   return out;
 }
@@ -312,6 +358,12 @@ async function leaderboard(args, deps = {}) {
     if (parsed.cursor !== void 0 && parsed.all === true) {
       throw new Error("irtio leaderboard: --cursor and --all are two ways to do the same thing");
     }
+    if (parsed.period !== void 0 && parsed.action !== void 0) {
+      throw new Error("irtio leaderboard: --period is for a read, not for list or delete");
+    }
+    if (parsed.bucket !== void 0 && parsed.action !== void 0) {
+      throw new Error("irtio leaderboard: --bucket is for a read, not for list or delete");
+    }
     if (parsed.around !== void 0 && (parsed.cursor !== void 0 || parsed.all === true)) {
       throw new Error("irtio leaderboard: --around does not page; it is already a window");
     }
@@ -323,6 +375,8 @@ async function leaderboard(args, deps = {}) {
       ...parsed.around !== void 0 ? { around: parsed.around } : {},
       ...parsed.cursor !== void 0 ? { cursor: parsed.cursor } : {},
       ...parsed.all === true ? { all: true } : {},
+      ...parsed.period !== void 0 ? { period: parsed.period } : {},
+      ...parsed.bucket !== void 0 ? { bucket: parsed.bucket } : {},
       ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {}
     });
   } catch (err) {

package/dist/{login-2M73HBZT.js → login-3RVN5PPN.js}

@@ -2,8 +2,8 @@ import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
-import "./chunk-RNAH5T4W.js";
+} from "./chunk-OCVALOGK.js";
+import "./chunk-IDF46P7R.js";
 import {
   credentialsPath,
   resolveControlUrl,

package/dist/{logs-2W7CPZO5.js → logs-AT7G6YRH.js}

@@ -1,15 +1,15 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";

package/dist/{migrate-T3DZJREY.js → migrate-FMXTRVUV.js}

@@ -1,6 +1,6 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   bundleRoom
 } from "./chunk-OTSFRVJN.js";
@@ -8,11 +8,11 @@ import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";

package/dist/{ratings-VG32WFDG.js → ratings-XBLX2MUW.js}

@@ -1,15 +1,15 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";

package/dist/{rollback-SO74MVZV.js → rollback-LI4TDLQA.js}

@@ -1,15 +1,15 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";

package/dist/{rooms-VI33P4RA.js → rooms-52Q5KBUS.js}

@@ -1,15 +1,15 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";
@@ -19,27 +19,42 @@ import "fs";
 import "fs/promises";
 import "path";
 import pc from "picocolors";
-var USAGE = `usage: irtio rooms [options]
+var USAGE = `usage: irtio rooms [--active|--idle] [--idle-longer-than <d>] [options]
+       irtio rooms get <room> [options]
+       irtio rooms set <room> --retention <d|forever|clear> [options]
        irtio rooms saves <room> [options]
        irtio rooms restore <room> --save <id> [options]
-       irtio rooms delete <room> [options]
+       irtio rooms delete <room> [--force] [options]
 
-Lists a project's rooms, with the retention window each one's type declares. Rows not reported for
-longer than the control plane's row-pruning window (30 days by default) are pruned; that prunes the
-listing only and never a room's stored state.
+Lists a project's rooms, with the retention window in force for each one and when it will be
+deleted. Rows not reported for longer than the control plane's row-pruning window (30 days by
+default) are pruned; that prunes the listing only and never a room's stored state.
 
 subcommands:
+  get <room>                one room in full: its type and size class, how many save generations
+                            it holds, how big its stored state is, and the exact deletion time
+  set <room> --retention <d|forever|clear>
+                            override the retention window for THIS room. A duration like 30m, 6h
+                            or 7d keeps it that long past its last activity; forever keeps it
+                            indefinitely; clear goes back to what its type declares
   saves <room>              list a room's save generations, newest first
   restore <room> --save <id>
                             bring a room back from a save. This DISCARDS its current state, and
                             stops the tenant if it is live
   delete <room>             delete a room's stored state: its snapshot, its saves and its alarms.
-                            This is permanent. Refused while the room is awake
+                            This is permanent. Refused while the room is awake unless --force
+
+list filters:
+  --active           only rooms that are awake in a live tenant
+  --idle             only rooms that are not
+  --idle-longer-than <d>
+                     only rooms whose last report is older than a duration like 30m, 6h or 7d
 
 options:
+  --force            with delete: disconnect the room's clients first, then delete it
   --project <id>     project id (default: the project file)
   -c, --config <f>   the project file to read (default irtio.json)
-  --url <control>    control plane (default: your stored login)
+  --url <control>    control plane (default: your stored login, or IRT_API_KEY)
   -h, --help         print this
 `;
 function parseRoomsArgs(args) {
@@ -47,7 +62,7 @@ function parseRoomsArgs(args) {
   const parsed = { sub: "list" };
   let rest = args;
   const first = args[0];
-  if (first === "saves" || first === "restore" || first === "delete") {
+  if (first === "saves" || first === "restore" || first === "delete" || first === "get" || first === "set") {
     parsed.sub = first;
     const room = args[1];
     if (room === void 0 || room.startsWith("-")) {
@@ -65,6 +80,33 @@ function parseRoomsArgs(args) {
         parsed.save = value;
         break;
       }
+      // ---- M6 lane A: rooms API ----
+      case "--active":
+        parsed.active = true;
+        break;
+      case "--idle":
+        parsed.active = false;
+        break;
+      case "--idle-longer-than": {
+        const value = rest[++i];
+        if (value === void 0) {
+          throw new Error("irtio rooms: --idle-longer-than needs a duration like 30m, 6h or 7d");
+        }
+        parsed.idleLongerThan = value;
+        break;
+      }
+      case "--retention": {
+        const value = rest[++i];
+        if (value === void 0) {
+          throw new Error("irtio rooms: --retention needs a duration, forever, or clear");
+        }
+        parsed.retention = value;
+        break;
+      }
+      case "--force":
+        parsed.force = true;
+        break;
+      // ---- end M6 lane A ----
       case "--project": {
         const value = rest[++i];
         if (value === void 0) throw new Error("irtio rooms: --project needs a value");
@@ -94,6 +136,23 @@ function parseRoomsArgs(args) {
       "irtio rooms restore: --save <id> is required \u2014 run `irtio rooms saves <room>` to see them"
     );
   }
+  if (parsed.sub === "set" && parsed.retention === void 0) {
+    throw new Error(
+      "irtio rooms set: --retention <d|forever|clear> is required. A duration like 7d keeps this room that long past its last activity, forever keeps it indefinitely, and clear goes back to what its type declares"
+    );
+  }
+  if (parsed.active !== void 0 && parsed.sub !== "list") {
+    throw new Error("irtio rooms: --active and --idle are filters for the listing");
+  }
+  if (parsed.idleLongerThan !== void 0 && parsed.sub !== "list") {
+    throw new Error("irtio rooms: --idle-longer-than is a filter for the listing");
+  }
+  if (parsed.force === true && parsed.sub !== "delete") {
+    throw new Error("irtio rooms: --force belongs to `irtio rooms delete`");
+  }
+  if (parsed.retention !== void 0 && parsed.sub !== "set") {
+    throw new Error("irtio rooms: --retention belongs to `irtio rooms set`");
+  }
   return parsed;
 }
 function formatBytes(bytes) {
@@ -114,16 +173,60 @@ function formatAge(iso, now) {
 function statusColor(status) {
   return status === "active" || status === "running" ? pc.green(status) : status === "draining" ? pc.yellow(status) : pc.dim(status);
 }
-function formatTable(rows) {
+function formatTable(rows, now) {
   if (rows.length === 0) return [pc.dim("no rooms")];
   const idWidth = Math.max(4, ...rows.map((r) => r.roomId.length));
-  const out = [pc.dim(`${"ROOM".padEnd(idWidth)}  STATUS      RETAIN  LAST SEEN`)];
+  const sharded = rows.some((r) => (r.shard ?? 0) > 0);
+  const head = `${"ROOM".padEnd(idWidth)}  STATUS      RETAIN  DELETES        LAST SEEN` + (sharded ? "  SHARD" : "");
+  const out = [pc.dim(head)];
   for (const r of rows) {
     const retention = r.retention ?? "forever";
+    const mark = r.retentionOverride ? "*" : "";
     out.push(
-      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${retention.padEnd(6)}  ${pc.dim(r.lastSeen)}`
+      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${`${retention}${mark}`.padEnd(6)}  ${formatDeadline(r.deletesAt, now).padEnd(13)}  ${pc.dim(r.lastSeen)}` + (sharded ? `  ${String(r.shard ?? 0)}` : "")
     );
   }
+  if (rows.some((r) => r.retentionOverride)) {
+    out.push(pc.dim("* set on this room, not declared by its type"));
+  }
+  return out;
+}
+function formatDeadline(deletesAt, now) {
+  if (!deletesAt) return pc.dim("never");
+  const ms = Date.parse(deletesAt) - now;
+  if (!Number.isFinite(ms)) return pc.dim("never");
+  if (ms <= 0) return pc.yellow("next sweep");
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 60) return `in ${mins}m`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return `in ${hours}h`;
+  return `in ${Math.floor(hours / 24)}d`;
+}
+function formatDetail(room, now) {
+  const line = (label, value) => `${pc.dim(label.padEnd(12))}${value}`;
+  const out = [
+    line("room", pc.bold(room.roomId)),
+    line("status", statusColor(room.status)),
+    line("type", room.type ?? pc.dim("not a room id"))
+  ];
+  out.push(line("class", room.class ?? pc.dim("not declared (billed as small)")));
+  if (room.clients !== null && room.clients !== void 0) {
+    const max = room.maxClients ? `/${room.maxClients}` : "";
+    out.push(line("clients", `${room.clients}${max}`));
+  }
+  out.push(line("retention", room.retention ?? "forever"));
+  if (room.retentionOverride) {
+    out.push(line("", pc.dim(`set on this room (${room.retentionOverride}), not by its type`)));
+  }
+  out.push(line("deletes", formatDeadline(room.deletesAt, now)));
+  out.push(line("saves", String(room.saves)));
+  out.push(
+    line(
+      "state",
+      room.stateBytes === void 0 ? pc.dim("unknown while the room is awake; read it after it sleeps") : formatBytes(room.stateBytes)
+    )
+  );
+  out.push(line("last seen", pc.dim(room.lastSeen)));
   return out;
 }
 function formatSaves(rows, now) {
@@ -180,8 +283,16 @@ async function runDeleteRoom(options) {
   log(
     `${pc.yellow("deleting")} room ${pc.bold(options.room)}: its snapshot, its saves and its alarms`
   );
+  if (options.force === true) {
+    log(
+      pc.yellow(
+        "forced: if the room is awake, every client in it is disconnected first and sees E_ROOM_DELETED. They cannot rejoin the same room; a fresh one starts empty"
+      )
+    );
+  }
   const result = await client.del(
-    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`,
+    options.force === true ? { force: "true" } : {}
   );
   log(pc.green(`deleted ${options.room}: ${result.objects} stored object(s) removed`));
   log(pc.dim("player data and leaderboard scores are keyed to the player and are untouched"));
@@ -191,10 +302,40 @@ async function runRooms(options) {
   const log = options.log ?? ((line) => console.log(line));
   const controlUrl = await resolveControlUrlForUser(options.controlUrl);
   const client = options.client ?? await createApiClient(controlUrl);
-  const rows = await client.get(`/v1/projects/${options.project}/rooms`);
-  for (const line of formatTable(rows)) log(line);
+  const rows = await client.get(`/v1/projects/${options.project}/rooms`, {
+    ...options.active !== void 0 ? { active: String(options.active) } : {},
+    ...options.idleLongerThan !== void 0 ? { "idle-longer-than": options.idleLongerThan } : {}
+  });
+  for (const line of formatTable(rows, options.now ?? Date.now())) log(line);
   return rows;
 }
+async function runGetRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const room = await client.get(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`
+  );
+  for (const line of formatDetail(room, options.now ?? Date.now())) log(line);
+  return room;
+}
+async function runSetRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const retention = options.retention === "clear" ? null : options.retention;
+  const room = await client.patch(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`,
+    { retention }
+  );
+  log(
+    retention === null ? pc.green(
+      `${options.room}: override cleared, back to its type's window (${room.retention ?? "forever"})`
+    ) : pc.green(`${options.room}: retention set to ${retention}`)
+  );
+  for (const line of formatDetail(room, options.now ?? Date.now())) log(line);
+  return room;
+}
 async function rooms(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
@@ -216,15 +357,31 @@ async function rooms(args, deps = {}) {
     if (parsed.sub === "saves") {
       await runSaves({ ...common, room: parsed.room });
     } else if (parsed.sub === "delete") {
-      await runDeleteRoom({ ...common, room: parsed.room });
+      await runDeleteRoom({
+        ...common,
+        room: parsed.room,
+        ...parsed.force === true ? { force: true } : {}
+      });
     } else if (parsed.sub === "restore") {
       await runRestore({
         ...common,
         room: parsed.room,
         saveId: parsed.save
       });
+    } else if (parsed.sub === "get") {
+      await runGetRoom({ ...common, room: parsed.room });
+    } else if (parsed.sub === "set") {
+      await runSetRoom({
+        ...common,
+        room: parsed.room,
+        retention: parsed.retention
+      });
     } else {
-      await runRooms(common);
+      await runRooms({
+        ...common,
+        ...parsed.active !== void 0 ? { active: parsed.active } : {},
+        ...parsed.idleLongerThan !== void 0 ? { idleLongerThan: parsed.idleLongerThan } : {}
+      });
     }
   } catch (err) {
     if (err instanceof HelpRequested) {
@@ -246,7 +403,9 @@ export {
   parseRoomsArgs,
   rooms,
   runDeleteRoom,
+  runGetRoom,
   runRestore,
   runRooms,
-  runSaves
+  runSaves,
+  runSetRoom
 };