@irtio/cli 0.5.1 → 0.6.0

package/dist/leaderboard-SYPSBPS3.js

@@ -0,0 +1,352 @@
+import {
+  readProjectConfig
+} from "./chunk-DKWG7MGO.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-RNAH5T4W.js";
+import {
+  resolveControlUrlForUser
+} from "./chunk-UPHQM6NZ.js";
+
+// src/leaderboard.ts
+import pc from "picocolors";
+var USAGE = `usage: irtio leaderboard <board> [options]
+       irtio leaderboard list [options]
+       irtio leaderboard delete <board> [--player <id>] --yes [options]
+
+Prints a project's leaderboard. Reads are public: no login is needed, and this works against
+any project's board, exactly as that project's own website would read it.
+
+There is no submit command. Scores reach a board only from room code
+(room.leaderboard.submit), which is what makes them server-authoritative.
+
+list     every board on the project, with its row count and direction. Needs your login,
+         because it is a view of a project rather than of one public ranking.
+delete   remove a whole board, or one player's row with --player. Needs your login and
+         --yes; without --yes it prints what would go and changes nothing.
+
+options:
+  --limit <n>        how many rows (default 10, max 100)
+  --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
+  --player <id>      with delete: remove one player's row instead of the whole board
+  --yes              with delete: actually delete
+  --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)
+  -h, --help         print this
+`;
+function parseLeaderboardArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
+  const parsed = {};
+  if (args[0] === "list" || args[0] === "delete") {
+    parsed.action = args[0];
+  }
+  for (let i = parsed.action === void 0 ? 0 : 1; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--cursor": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio leaderboard: --cursor needs a value");
+        }
+        parsed.cursor = value;
+        break;
+      }
+      case "--all":
+        parsed.all = true;
+        break;
+      case "--yes":
+        parsed.yes = true;
+        break;
+      case "--player": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio leaderboard: --player needs a player id");
+        }
+        parsed.player = value;
+        break;
+      }
+      case "--limit": {
+        const value = Number(args[++i]);
+        if (!Number.isInteger(value) || value < 1) {
+          throw new Error("irtio leaderboard: --limit needs a whole number of at least 1");
+        }
+        parsed.limit = value;
+        break;
+      }
+      case "--around": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio leaderboard: --around needs a player id");
+        }
+        parsed.around = value;
+        break;
+      }
+      case "--project": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio leaderboard: --project needs a value");
+        parsed.project = value;
+        break;
+      }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio leaderboard: --config needs a value");
+        }
+        parsed.config = value;
+        break;
+      }
+      case "--url": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio leaderboard: --url needs a value");
+        parsed.url = value;
+        break;
+      }
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`irtio leaderboard: unknown option ${JSON.stringify(arg)}`);
+        }
+        if (parsed.board !== void 0) {
+          throw new Error("irtio leaderboard: give exactly one board name");
+        }
+        parsed.board = arg;
+    }
+  }
+  return parsed;
+}
+function formatLeaderboard(body, around) {
+  const direction = body.direction === "lower" ? "lower is better" : "higher is better";
+  const out = [pc.dim(`board ${body.board}  \xB7  ${direction}`), ""];
+  if (body.entries.length === 0) {
+    out.push(
+      pc.dim(
+        around !== void 0 ? `${around} has no score on this board` : "no scores on this board yet"
+      )
+    );
+    return out;
+  }
+  const rankWidth = Math.max(4, ...body.entries.map((e) => String(e.rank).length));
+  const idWidth = Math.max(6, ...body.entries.map((e) => e.playerId.length));
+  out.push(pc.dim(`${"RANK".padEnd(rankWidth)}  ${"PLAYER".padEnd(idWidth)}  SCORE`));
+  for (const entry of body.entries) {
+    const line = `${String(entry.rank).padEnd(rankWidth)}  ${entry.playerId.padEnd(idWidth)}  ${entry.score}`;
+    out.push(entry.playerId === around ? pc.bold(line) : line);
+  }
+  return out;
+}
+async function runLeaderboard(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = (await resolveControlUrlForUser(options.controlUrl)).replace(/\/+$/, "");
+  const fetchImpl = options.fetch ?? fetch;
+  const base = `${controlUrl}/v1/leaderboard/${encodeURIComponent(
+    options.project
+  )}/${encodeURIComponent(options.board)}`;
+  if (options.around !== void 0) {
+    const body2 = await readPublicJson(
+      fetchImpl,
+      `${base}/around/${encodeURIComponent(options.around)}`
+    );
+    for (const line of formatLeaderboard(body2, options.around)) log(line);
+    return body2;
+  }
+  const pageUrl = (cursor) => {
+    const query = new URLSearchParams();
+    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}`}`;
+  };
+  let body = await readPublicJson(fetchImpl, pageUrl(options.cursor));
+  const entries = [...body.entries];
+  if (options.all === true) {
+    let next = body.nextCursor;
+    for (let page = 1; next !== void 0 && page < 100; page++) {
+      body = await readPublicJson(fetchImpl, pageUrl(next));
+      entries.push(...body.entries);
+      next = body.nextCursor;
+    }
+    if (next !== void 0) {
+      throw new Error(
+        "irtio leaderboard: --all stopped after a hundred pages. Read it in pieces with --cursor"
+      );
+    }
+  }
+  const combined = { ...body, entries };
+  for (const line of formatLeaderboard(combined)) log(line);
+  if (options.all !== true && body.nextCursor !== void 0) {
+    log("");
+    log(pc.dim(`more rows: --cursor ${body.nextCursor}`));
+  }
+  return combined;
+}
+async function readPublicJson(fetchImpl, url) {
+  const res = await fetchImpl(url);
+  const text = await res.text().catch(() => "");
+  if (!res.ok) {
+    let message = `leaderboard read failed with status ${res.status}`;
+    try {
+      const parsed = JSON.parse(text);
+      if (typeof parsed.message === "string") message = parsed.message;
+    } catch {
+    }
+    throw new Error(message);
+  }
+  return JSON.parse(text);
+}
+function formatBoardList(boards) {
+  if (boards.length === 0) {
+    return [
+      pc.dim("no boards on this project yet"),
+      pc.dim("scores reach a board from room code: room.leaderboard.submit")
+    ];
+  }
+  const nameWidth = Math.max(5, ...boards.map((b) => b.board.length));
+  const out = [pc.dim(`${"BOARD".padEnd(nameWidth)}  ${"ROWS".padStart(7)}  DIRECTION`)];
+  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}`);
+  }
+  return out;
+}
+async function runBoardList(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const body = await client.get(
+    `/v1/projects/${encodeURIComponent(options.project)}/leaderboards`
+  );
+  for (const line of formatBoardList(body.boards)) log(line);
+  return body.boards;
+}
+async function runBoardDelete(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const path = `/v1/projects/${encodeURIComponent(options.project)}/leaderboard/${encodeURIComponent(
+    options.board
+  )}`;
+  if (!options.yes) {
+    if (options.player !== void 0) {
+      log(
+        `this would delete ${pc.bold(options.player)} from board ${pc.bold(options.board)} in project ${options.project}`
+      );
+    } else {
+      const { boards } = await client.get(
+        `/v1/projects/${encodeURIComponent(options.project)}/leaderboards`
+      );
+      const rows = boards.find((b) => b.board === options.board)?.rows ?? 0;
+      log(
+        `this would delete every row on board ${pc.bold(options.board)} in project ${options.project}: ${pc.bold(String(rows))} row(s)`
+      );
+    }
+    log(pc.dim("nothing was deleted. This cannot be undone once it runs"));
+    log(
+      `to proceed: irtio leaderboard delete ${options.board}${options.player !== void 0 ? ` --player ${options.player}` : ""} --yes`
+    );
+    return false;
+  }
+  if (options.player !== void 0) {
+    const body2 = await client.del(
+      `${path}/${encodeURIComponent(options.player)}`
+    );
+    log(
+      body2.deleted ? pc.green(`deleted ${options.player} from board ${options.board}`) : pc.dim(`${options.player} had no row on board ${options.board}; nothing to delete`)
+    );
+    return true;
+  }
+  const body = await client.del(path);
+  log(pc.green(`deleted ${body.deleted} row(s) from board ${options.board}`));
+  return true;
+}
+async function leaderboard(args, deps = {}) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  try {
+    const parsed = parseLeaderboardArgs(args);
+    const config = await readProjectConfig(process.cwd(), "irtio leaderboard", parsed.config);
+    const project = parsed.project ?? config.project;
+    if (project === void 0) {
+      throw new Error(
+        "irtio leaderboard: no project id. Pass --project or run this from a project with irtio.json"
+      );
+    }
+    const common = {
+      project,
+      log,
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
+      ...deps.client !== void 0 ? { client: deps.client } : {}
+    };
+    if (parsed.action === "list") {
+      if (parsed.board !== void 0) {
+        throw new Error("irtio leaderboard list: takes no board name");
+      }
+      await runBoardList(common);
+      return;
+    }
+    if (parsed.action === "delete") {
+      if (parsed.board === void 0) {
+        throw new Error(
+          "irtio leaderboard delete: which board? e.g. irtio leaderboard delete scores --yes"
+        );
+      }
+      await runBoardDelete({
+        ...common,
+        board: parsed.board,
+        yes: parsed.yes === true,
+        ...parsed.player !== void 0 ? { player: parsed.player } : {}
+      });
+      return;
+    }
+    if (parsed.board === void 0) {
+      throw new Error("irtio leaderboard: which board? e.g. irtio leaderboard scores");
+    }
+    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.around !== void 0 && (parsed.cursor !== void 0 || parsed.all === true)) {
+      throw new Error("irtio leaderboard: --around does not page; it is already a window");
+    }
+    await runLeaderboard({
+      project,
+      board: parsed.board,
+      log,
+      ...parsed.limit !== void 0 ? { limit: parsed.limit } : {},
+      ...parsed.around !== void 0 ? { around: parsed.around } : {},
+      ...parsed.cursor !== void 0 ? { cursor: parsed.cursor } : {},
+      ...parsed.all === true ? { all: true } : {},
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {}
+    });
+  } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      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 {
+  USAGE,
+  formatBoardList,
+  formatLeaderboard,
+  leaderboard,
+  parseLeaderboardArgs,
+  runBoardDelete,
+  runBoardList,
+  runLeaderboard
+};

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

@@ -1,8 +1,14 @@
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import "./chunk-RNAH5T4W.js";
 import {
   credentialsPath,
   resolveControlUrl,
   writeCredential
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-UPHQM6NZ.js";
 
 // src/login.ts
 import { spawn } from "child_process";
@@ -10,7 +16,20 @@ import { randomBytes } from "crypto";
 import { createServer } from "http";
 import pc from "picocolors";
 var LOGIN_TIMEOUT_MS = 3 * 60 * 1e3;
+var USAGE = `usage: irtio login [--url <control>]
+
+Signs in to a control plane through your browser and stores the credential it hands back.
+
+options:
+  --url <control>       the control plane to sign in to (default: the last one you used)
+  --token-file <file>   store the credential in this file instead of the default location
+                        (a global flag: pass it to later commands too, or set
+                        IRT_CREDENTIALS_FILE). For agents and sandboxes that cannot
+                        reach the home directory
+  -h, --help            print this
+`;
 function parseLoginArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -145,11 +164,16 @@ async function login(args) {
     console.log(pc.dim(`control plane: ${result.controlUrl}`));
     console.log(pc.dim(`credentials stored at ${result.file ?? credentialsPath()}`));
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      console.log(err.usage);
+      return;
+    }
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
     process.exitCode = 1;
   }
 }
 export {
+  USAGE,
   defaultOpenBrowser,
   login,
   parseLoginArgs,

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

@@ -1,18 +1,40 @@
+import {
+  readProjectConfig
+} from "./chunk-DKWG7MGO.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-I37DLT7K.js";
+} from "./chunk-RNAH5T4W.js";
 import {
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-UPHQM6NZ.js";
 
 // src/logs.ts
-import { existsSync } from "fs";
-import { readFile } from "fs/promises";
-import * as path from "path";
+import "fs";
+import "fs/promises";
+import "path";
 import pc from "picocolors";
 var POLL_MS = 2e3;
+var USAGE = `usage: irtio logs [options]
+
+Tails a project's logs, oldest line first.
+
+options:
+  --follow           poll every 2s, threading the cursor so nothing repeats
+  --since <cursor>   start after this cursor (a previous row's timestamp)
+  --room <id>        narrow to one room's stream. __tenant is the tenant's own events
+  --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)
+  -h, --help         print this
+`;
 function parseLogsArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = {
     follow: false
   };
@@ -40,6 +62,14 @@ function parseLogsArgs(args) {
         parsed.project = value;
         break;
       }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "")
+          throw new Error("irtio logs: --config needs a value");
+        parsed.config = value;
+        break;
+      }
       case "--url": {
         const value = args[++i];
         if (value === void 0) throw new Error("irtio logs: --url needs a value");
@@ -81,23 +111,13 @@ async function runLogs(options) {
     await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? POLL_MS));
   }
 }
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    throw new Error(`irtio logs: ${file} is not valid JSON`);
-  }
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 async function logs(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
   try {
     const parsed = parseLogsArgs(args);
-    const project = parsed.project ?? await readIrtioJsonProject(process.cwd());
+    const config = await readProjectConfig(process.cwd(), "irtio logs", parsed.config);
+    const project = parsed.project ?? config.project;
     if (project === void 0) {
       throw new Error(
         "irtio logs: no project id \u2014 pass --project or run this from a project with irtio.json"
@@ -113,6 +133,10 @@ async function logs(args, deps = {}) {
       ...deps.client !== void 0 ? { client: deps.client } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
     if (isLoginRequired(err)) {
       errorLog(pc.red("not logged in"));
       errorLog("run: irtio login");
@@ -124,6 +148,7 @@ async function logs(args, deps = {}) {
   }
 }
 export {
+  USAGE,
   logs,
   parseLogsArgs,
   runLogs

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

@@ -1,17 +1,25 @@
+import {
+  readProjectConfig
+} from "./chunk-DKWG7MGO.js";
 import {
   bundleRoom
-} from "./chunk-KRQUAEN2.js";
+} from "./chunk-OTSFRVJN.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-I37DLT7K.js";
+} from "./chunk-RNAH5T4W.js";
 import {
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-UPHQM6NZ.js";
 
 // src/migrate.ts
 import { existsSync } from "fs";
-import { mkdir, mkdtemp, readFile, readdir, writeFile } from "fs/promises";
+import { mkdir, mkdtemp, readdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import * as path from "path";
 import { pathToFileURL } from "url";
@@ -23,7 +31,18 @@ import {
 import pc from "picocolors";
 var MIGRATIONS_DIR = "irtio/migrations";
 var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
+var USAGE = `usage: irtio migrate create <name> [-c <file>]
+
+Scaffolds irtio/migrations/<n>_<name>.ts, with the breaking changes against the live deployment
+quoted in its header so the transform has something to answer.
+
+options:
+  <name>             a short name for the migration, e.g. rename-hp
+  -c, --config <f>   the project file to read (default irtio.json)
+  -h, --help         print this
+`;
 function parseMigrateArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const [sub, name, ...rest] = args;
   if (sub !== "create") {
     throw new Error(
@@ -35,9 +54,20 @@ function parseMigrateArgs(args) {
       "irtio migrate create: a name is required, e.g. irtio migrate create rename-hp"
     );
   }
-  if (rest.length > 0)
-    throw new Error(`irtio migrate create: unexpected extra argument ${JSON.stringify(rest[0])}`);
-  return { command: "create", args: { name } };
+  let config;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "-c" || arg === "--config") {
+      const value = rest[++i];
+      if (value === void 0 || value === "") {
+        throw new Error("irtio migrate create: --config needs a value");
+      }
+      config = value;
+      continue;
+    }
+    throw new Error(`irtio migrate create: unexpected extra argument ${JSON.stringify(arg)}`);
+  }
+  return { command: "create", args: config === void 0 ? { name } : { name, config } };
 }
 function resolveEntry(cwd, room) {
   if (room !== void 0) {
@@ -53,17 +83,6 @@ function resolveEntry(cwd, room) {
     `irtio migrate create: no room file found in ${cwd} (looked for: ${ROOM_CANDIDATES.join(", ")})`
   );
 }
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    throw new Error(`irtio migrate: ${file} is not valid JSON`);
-  }
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 async function scanDirectoryVersion(cwd) {
   const dir = path.join(cwd, MIGRATIONS_DIR);
   if (!existsSync(dir)) return 1;
@@ -120,7 +139,8 @@ async function runMigrateCreate(options) {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const log = options.log ?? ((line) => console.log(line));
   const controlUrl = await resolveControlUrlForUser(options.controlUrl);
-  const projectId = options.project ?? await readIrtioJsonProject(cwd);
+  const config = await readProjectConfig(cwd, "irtio migrate", options.config);
+  const projectId = options.project ?? config.project;
   let version;
   let versionSource;
   let previousSchemaJson;
@@ -196,6 +216,10 @@ async function migrate(args, deps = {}) {
       ...deps.client !== void 0 ? { client: deps.client } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
     if (isLoginRequired(err)) {
       errorLog(pc.red("not logged in"));
       errorLog("run: irtio login");
@@ -207,6 +231,7 @@ async function migrate(args, deps = {}) {
   }
 }
 export {
+  USAGE,
   migrate,
   parseMigrateArgs,
   runMigrateCreate