@zaisma/cli 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Upload and publish browser games on Zaisma from the command line.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/zaisma.mjs

@@ -45,7 +45,7 @@ const COMMAND_ERROR_CODES = {
   missing_value: "A flag that takes a value was given none.",
   takes_no_value: "A flag that takes no value was given one.",
   not_a_folder: "The folder to upload isn't a folder.",
-  not_a_file: "The file of statements, or the dump to import, can't be read.",
+  not_a_file: "The file given (of statements, a dump to import, or a save) can't be read.",
   file_exists: "database export won't write over a file that's already there.",
   needs_newer_node: "Reading or writing a .sqlite file needs Node 22.13 or newer.",
   not_a_database: "The .sqlite file to import isn't a SQLite database.",
@@ -55,6 +55,7 @@ const COMMAND_ERROR_CODES = {
 
 const BY_ME = { hasValue: false, about: "Mark it as written by you; otherwise it says your AI wrote it" };
 const TEXT = { hasValue: true, placeholder: '"…"', about: "The text, in markdown; or pipe it in" };
+const KEYS = { hasValue: true, placeholder: "'[…]'", about: 'Only these localStorage keys, as a JSON list, like \'["coins", "level"]\'' };
 const KIND_ABOUT = "bug (something doesn't work), gap (a limit or missing piece blocks you), feature (an idea), question";
 
 /**
@@ -81,6 +82,14 @@ const COMMANDS = {
   },
   unschedule: { about: "Cancel a publish-later", arguments: [{ name: "slug" }, { name: "version_id" }], flags: {} },
   visibility: { about: "Set who can see a game: everyone (listed), people with the link (unlisted), or only you and tester links (private, draft)", arguments: [{ name: "slug" }, { name: "visibility", choices: VISIBILITIES }], flags: {} },
+  "allowed-hosts": {
+    about: "The hosts a game's server can call with fetch(), like discord.com or *.example.com; given hosts, set the whole list",
+    arguments: [{ name: "slug" }, { name: "hosts", isRest: true, isOptional: true }],
+    flags: { none: { hasValue: false, about: "Set the list to none: the game server calls no other servers" } },
+  },
+  secrets: { about: "A game's secrets, which its game server reads as server.secrets and room.secrets: their names and when each was set, never the values", arguments: [{ name: "slug" }], flags: {} },
+  "secrets set": { about: "Set a secret for a game's server, replacing one of the same name: the value piped in, or typed without showing; it's never shown again", arguments: [{ name: "slug" }, { name: "secret_name" }], flags: {} },
+  "secrets delete": { about: "Delete one of a game's secrets", arguments: [{ name: "slug" }, { name: "secret_name" }], flags: {} },
   forum: {
     about: "Your forum topics and messages to Zaisma; one topic with every post you can see; or a search",
     arguments: [{ name: "topic_id", isOptional: true }],
@@ -135,10 +144,30 @@ const COMMANDS = {
     arguments: [{ name: "slug" }, { name: "file", isOptional: true }],
     flags: {},
   },
+  saves: {
+    about: "The players with a cloud save in a game, by player ID, 100 a page",
+    arguments: [{ name: "slug" }],
+    flags: { cursor: { hasValue: true, placeholder: "<next_cursor>", about: "The page after an earlier one: the next_cursor it printed" } },
+  },
+  "saves get": { about: "One player's cloud save: its localStorage keys and IndexedDB databases", arguments: [{ name: "slug" }, { name: "player_id" }], flags: { keys: KEYS } },
+  "saves change": {
+    about: "Set or remove some localStorage keys in a player's save; a JSON object of keys and their text (null removes one), as an argument or piped in",
+    arguments: [{ name: "slug" }, { name: "player_id" }, { name: "items_json", isOptional: true }],
+    flags: {},
+  },
+  "saves replace": {
+    about: "Replace a player's whole save with a JSON file (or piped in) of local_storage_items and indexeddb_databases, like zaisma saves get --json printed",
+    arguments: [{ name: "slug" }, { name: "player_id" }, { name: "file", isOptional: true }],
+    flags: {},
+  },
+  "saves reset": { about: "Reset a player's save: it becomes empty, and the game starts fresh on every device", arguments: [{ name: "slug" }, { name: "player_id" }], flags: {} },
+  "saves copies": { about: "A player's earlier versions of their save, newest first, with why each was kept", arguments: [{ name: "slug" }, { name: "player_id" }], flags: {} },
+  "saves copy": { about: "One earlier version of a player's save", arguments: [{ name: "slug" }, { name: "player_id" }, { name: "save_copy_id" }], flags: { keys: KEYS } },
+  "saves restore": { about: "Make an earlier version a player's save again", arguments: [{ name: "slug" }, { name: "player_id" }, { name: "save_copy_id" }], flags: {} },
   help: { about: "This help; with --json, every command, flag, exit code and error code", arguments: [], flags: {} },
 };
 /** Commands with a second word, like zaisma forum post. */
-const SUBCOMMANDS = { forum: ["post", "message", "reply"], database: ["query", "batch", "export", "import"] };
+const SUBCOMMANDS = { forum: ["post", "message", "reply"], database: ["query", "batch", "export", "import"], saves: ["get", "change", "replace", "reset", "copies", "copy", "restore"], secrets: ["set", "delete"] };
 /** Flags every command takes. */
 const GLOBAL_FLAGS = {
   json: { hasValue: false, about: "Print the API's answer as JSON, as-is (on failure its { error }), and nothing else" },
@@ -817,6 +846,143 @@ function* sqliteDumpStatements(sqlite) {
   yield "COMMIT;\n";
 }
 
+/** The hosts a game's server can call (game_server_allowed_hosts on the game), as the MCP's get_game and update_game. */
+async function allowedHosts(values, flags) {
+  const given = (values.hosts ?? "").split(/[\s,]+/).filter(Boolean);
+  if (given.length && flags.none) refuse("unknown_field", { message: "Hosts and --none were both given.", field: "--none", fix: `Give the whole list, like zaisma allowed-hosts ${values.slug} discord.com api.github.com, or --none for none.` });
+  const answer = given.length || flags.none ? await api("PATCH", `/games/${values.slug}`, { game_server_allowed_hosts: given }) : await api("GET", `/games/${values.slug}`);
+  if (isJson) return printJson(answer);
+  const hosts = answer.game.game_server_allowed_hosts;
+  console.log(hosts.length ? `${values.slug}'s game server can call: ${hosts.join(", ")}` : `${values.slug}'s game server calls no other servers. List some with: zaisma allowed-hosts ${values.slug} discord.com`);
+  if (given.length || flags.none) console.log("It works within a minute.");
+}
+
+/** A game's secrets (…/games/<slug>/secrets…), as the MCP's list_secrets, set_secret and delete_secret. */
+async function secrets(command, values) {
+  if (command === "secrets") {
+    const answer = await api("GET", `/games/${values.slug}/secrets`);
+    if (isJson) return printJson(answer);
+    if (!answer.secrets.length) console.log(`No secrets yet. Set one with: zaisma secrets set ${values.slug} DISCORD_WEBHOOK_URL`);
+    for (const secret of answer.secrets) console.log(`${secret.name.padEnd(32)} set ${when(secret.set_at)}`);
+    return;
+  }
+  const path = `/games/${values.slug}/secrets/${encodeURIComponent(values.secret_name)}`;
+  if (command === "secrets delete") {
+    const answer = await api("DELETE", path);
+    if (isJson) return printJson(answer);
+    return console.log(`Deleted ${values.secret_name} from ${values.slug}. Running rooms lose it within a minute.`);
+  }
+  const secretValue = await readSecretValue(values.secret_name);
+  if (!secretValue) refuse("missing_field", { message: `No value was given for ${values.secret_name}.`, field: "secret_value", fix: `Pipe it in, like printf %s "$TOKEN" | zaisma secrets set ${values.slug} ${values.secret_name}, or run it in a terminal and type it.` });
+  const answer = await api("PUT", path, { secret_value: secretValue });
+  if (isJson) return printJson(answer);
+  console.log(`Set ${values.secret_name} for ${values.slug}. Its game server reads it as server.secrets.${values.secret_name}; running rooms get it within a minute.`);
+  if (answer.next_steps.some((step) => step.tool === "update_game")) console.log(`It calls no other servers yet: list the hosts it uses this with, like zaisma allowed-hosts ${values.slug} discord.com`);
+}
+
+/** A secret's value: piped in (without the line break at its end), or typed in a terminal without showing it. */
+async function readSecretValue(secretName) {
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+  }
+  process.stderr.write(`${secretName} (it isn't shown; Enter when done): `);
+  process.stdin.setRawMode(true);
+  process.stdin.setEncoding("utf8");
+  let typed = "";
+  try {
+    for await (const chunk of process.stdin) {
+      for (const character of chunk) {
+        if (character === "\r" || character === "\n") return typed;
+        if (character === "\u0003") process.exit(130);
+        if (character === "\u007f" || character === "\b") typed = typed.slice(0, -1);
+        else typed += character;
+      }
+    }
+    return typed;
+  } finally {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+    process.stderr.write("\n");
+  }
+}
+
+/** A game's cloud saves (…/games/<slug>/saves…), as the MCP's list_saves, get_save, change_save, replace_save, reset_save, list_save_copies, get_save_copy and restore_save_copy. */
+async function saves(command, values, flags) {
+  const savePath = () => `/games/${values.slug}/saves/${encodeURIComponent(values.player_id)}`;
+  if (command === "saves") {
+    const answer = await api("GET", `/games/${values.slug}/saves${flags.cursor ? `?cursor=${encodeURIComponent(flags.cursor)}` : ""}`);
+    if (isJson) return printJson(answer);
+    if (!answer.saves.length) console.log("No saves yet. Players' progress shows up here once they play signed in with cloud saves on.");
+    for (const save of answer.saves) console.log(`${save.player_id}  ${save.updated_at.slice(0, 16).replace("T", " ")}  ${sizeText(save.size_bytes).padStart(8)}  ${save.changed_by_kind === "developer" ? "changed by you" : "saved by the game"}${save.save_copy_count ? `, ${save.save_copy_count} earlier` : ""}`);
+    if (answer.next_cursor) console.log(`\nMore: zaisma saves ${values.slug} --cursor ${answer.next_cursor}`);
+    return;
+  }
+  if (command === "saves get" || command === "saves copy") {
+    const keys = readKeys(flags.keys);
+    const query = keys ? `?${keys.map((key) => `keys=${encodeURIComponent(key)}`).join("&")}` : "";
+    const answer = await api("GET", command === "saves get" ? `${savePath()}${query}` : `${savePath()}/copies/${encodeURIComponent(values.save_copy_id)}${query}`);
+    if (isJson) return printJson(answer);
+    const save = answer.save ?? answer.save_copy;
+    console.log(answer.save ? `${sizeText(save.size_bytes)}, ${save.changed_by_kind === "developer" ? "changed by you" : "saved by the game"} ${when(save.updated_at)}.` : `Saved ${when(save.saved_at)} (${save.copy_reason})${save.is_current_save ? ", the same as the save now" : ""}.`);
+    for (const [key, itemText] of Object.entries(save.local_storage_items)) console.log(`${key} = ${itemText}`);
+    for (const key of save.missing_keys) console.log(`${key}: not in the save`);
+    if (save.indexeddb_databases?.length) console.log(`IndexedDB: ${save.indexeddb_databases.map((database) => database.name).join(", ")} (--json shows them)`);
+    return;
+  }
+  if (command === "saves copies") {
+    const answer = await api("GET", `${savePath()}/copies`);
+    if (isJson) return printJson(answer);
+    if (!answer.save_copies.length) console.log("No earlier versions yet.");
+    for (const copy of answer.save_copies) console.log(`${copy.id}  ${copy.saved_at.slice(0, 16).replace("T", " ")}  ${sizeText(copy.size_bytes).padStart(8)}  ${copy.copy_reason}${copy.is_current_save ? "  (the save now)" : ""}`);
+    return;
+  }
+  let answer;
+  if (command === "saves reset") answer = await api("DELETE", savePath());
+  else if (command === "saves restore") answer = await api("POST", `${savePath()}/copies/${encodeURIComponent(values.save_copy_id)}/restore`);
+  else if (command === "saves change") {
+    const text = values.items_json ?? (await readInput());
+    let items;
+    try {
+      items = JSON.parse(text);
+    } catch {}
+    if (!items || typeof items !== "object" || Array.isArray(items)) {
+      refuse("bad_local_storage_items", { message: "The keys to change aren't a JSON object.", field: "items_json", fix: `Give them in single quotes, like '{"coins": "500", "tutorial_seen": null}' (text values; null removes a key), or pipe them in.` });
+    }
+    answer = await api("PATCH", savePath(), { local_storage_items: items });
+  } else {
+    const text = values.file ? await readFile(values.file, "utf8").catch(() => refuse("not_a_file", { message: `Couldn't read ${values.file}.`, field: "file", fix: "Give the path of a JSON file of the save, or pipe it in." })) : await readInput();
+    let given;
+    try {
+      given = JSON.parse(text);
+    } catch {}
+    // What zaisma saves get --json printed works as it is.
+    const save = given?.save ?? given;
+    if (!save || typeof save !== "object" || save.local_storage_items === undefined || save.indexeddb_databases === undefined) {
+      refuse("bad_local_storage_items", { message: `${values.file ?? "What was piped in"} isn't a JSON save with local_storage_items and indexeddb_databases.`, field: "file", fix: 'Give a JSON object like {"local_storage_items": {"coins": "0"}, "indexeddb_databases": []}, or what zaisma saves get <slug> <player_id> --json printed, changed.' });
+    }
+    answer = await api("PUT", savePath(), { local_storage_items: save.local_storage_items, indexeddb_databases: save.indexeddb_databases });
+  }
+  if (isJson) return printJson(answer);
+  const done = { "saves reset": "Reset", "saves restore": "Restored", "saves change": "Changed", "saves replace": "Replaced" }[command];
+  console.log(`${done} ${values.player_id}'s save in ${values.slug}. An open game reloads with it.`);
+  if (answer.kept_save_copy_id) console.log(`The save it replaced is kept: undo with zaisma saves restore ${values.slug} ${values.player_id} ${answer.kept_save_copy_id}`);
+}
+
+/** --keys: a JSON list of localStorage keys, or null without it. */
+function readKeys(given) {
+  if (given === undefined) return null;
+  let keys;
+  try {
+    keys = JSON.parse(given);
+  } catch {}
+  if (!Array.isArray(keys) || !keys.length || !keys.every((key) => typeof key === "string" && key)) refuse("bad_keys", { message: "--keys isn't a JSON list of localStorage keys.", field: "--keys", fix: `Give them as a JSON list in single quotes, like --keys '["coins", "level"]'.` });
+  return keys;
+}
+
+const sizeText = (sizeBytes) => (sizeBytes < 1024 ? `${sizeBytes} B` : sizeBytes < 1048576 ? `${(sizeBytes / 1024).toFixed(1)} KB` : `${(sizeBytes / 1048576).toFixed(1)} MB`);
+
 /** A statement's rows as a table, then what it read and wrote. Blobs show their size. */
 function printRows({ rows, read_row_count: readRowCount, written_row_count: writtenRowCount }) {
   const shown = (cell) => (cell === null ? "NULL" : typeof cell === "object" ? `<blob, ${Math.floor((cell.blob_base64.replace(/=+$/, "").length * 3) / 4)} bytes>` : String(cell));
@@ -845,7 +1011,11 @@ async function run({ command, values, flags, globalFlags, rest }) {
     if (isJson) return printAnswer(answer);
     const { games, unread_topic_count: unreadTopicCount } = answer;
     if (!games.length) console.log('No games yet. Make one with: zaisma new "My Game"');
-    for (const game of games) console.log(`${game.slug.padEnd(28)} ${game.visibility.padEnd(9)} ${game.review_status.padEnd(8)} ${game.title}${game.review_reason ? `  [${reasonCode(game)}]` : ""}`);
+    for (const game of games) {
+      console.log(`${game.slug.padEnd(28)} ${game.visibility.padEnd(9)} ${game.review_status.padEnd(8)} ${game.title}${game.review_reason ? `  [${reasonCode(game)}]` : ""}`);
+      // What needs attention in it, most urgent first.
+      for (const alert of game.alerts ?? []) console.log(`  ! ${alert.message}`);
+    }
     if (unreadTopicCount) console.log(`\nZaisma replied to ${unreadTopicCount} of your forum topics. See them with: zaisma forum`);
     return EXIT_CODES.done;
   }
@@ -891,7 +1061,10 @@ async function run({ command, values, flags, globalFlags, rest }) {
     console.log(`${answer.game.title} is now ${answer.game.visibility}.`);
     return EXIT_CODES.done;
   }
-  if (command === "database" || command.startsWith("database ")) await database(command, values, flags);
+  if (command === "allowed-hosts") await allowedHosts(values, flags);
+  else if (command === "secrets" || command.startsWith("secrets ")) await secrets(command, values);
+  else if (command === "database" || command.startsWith("database ")) await database(command, values, flags);
+  else if (command === "saves" || command.startsWith("saves ")) await saves(command, values, flags);
   else await forum(command, values, flags);
   return EXIT_CODES.done;
 }