@zaisma/cli 0.15.0 → 0.16.0

package/package.json

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

package/zaisma.mjs

@@ -63,6 +63,7 @@ const COMMAND_ERROR_CODES = {
   not_a_folder: "The folder to check or upload isn't a folder.",
   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.",
+  folder_not_empty: "export saves only into a new or empty folder.",
   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.",
   unknown_link: "links remove: the game has no link by that name.",
@@ -220,6 +221,11 @@ const COMMANDS = {
   "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: {} },
+  export: {
+    about: "Save everything about a game in a folder: every version that passed review, the cover and screenshots, the database (as SQL and a ready .sqlite file), every player's save, stats, reports and history",
+    arguments: [{ name: "slug" }],
+    flags: { folder: { hasValue: true, placeholder: "<folder>", about: "Where to save it: a new or empty folder; ./<slug>-export if left out" } },
+  },
   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. */
@@ -1027,6 +1033,142 @@ async function exportDatabase({ slug, file }) {
   console.log(`Saved ${slug}'s database to ${file} (${partCount} part${partCount === 1 ? "" : "s"}, ${readRowCount.toLocaleString("en-US")} rows read).${sqlite ? ` Run your game server on it with: node bin/node.js <server> --game ${slug} --database ${file}` : ""}`);
 }
 
+/** The biggest database.sql export turns into a .sqlite file itself; past it, sqlite3 does it (Node's text tops out near this). */
+const MAXIMUM_SQLITE_DUMP_SIZE_BYTES = 400 * 1024 * 1024;
+
+/**
+ * export: the .zip of everything about a game (GET …/export/download), downloaded and saved as a folder,
+ * with database.sql also made into database.sqlite, ready for the Node runner's --database.
+ */
+async function exportGame({ slug }, flags) {
+  const folder = flags.folder ?? `${slug}-export`;
+  const there = await readdir(folder).catch(() => null);
+  if (there?.length) refuse("folder_not_empty", { message: `${folder} isn't empty.`, field: "folder", fix: "Give a new or empty folder with --folder, or move what's in it." });
+  if (!KEY) refuse("no_key", { message: "ZAISMA_KEY isn't set.", field: "ZAISMA_KEY", fix: "Make an API key at https://zaisma.com/account (under Game developers) and set it: export ZAISMA_KEY=zsk_…" }, EXIT_CODES.failed);
+  let response;
+  try {
+    response = await fetch(`${API}/api/dev/games/${encodeURIComponent(slug)}/export/download`, { headers: { authorization: `Bearer ${KEY}`, "x-zaisma-client": "cli", "user-agent": `zaisma-cli/${CLI_VERSION}` } });
+  } catch (error) {
+    refuse("server_unreachable", { message: `Couldn't reach ${API}: ${error.cause?.message ?? error.message}.`, field: process.env.ZAISMA_API ? "ZAISMA_API" : null, fix: "Check the internet connection (and ZAISMA_API, if it's set), then run it again." }, EXIT_CODES.failed);
+  }
+  if (!response.ok || response.headers.get("content-type") !== "application/zip") {
+    const answer = await response.json().catch(() => null);
+    if (answer?.error) throw new CommandError(answer.error, EXIT_CODES.failed.exitCode);
+    refuse("unexpected_answer", { message: `Zaisma answered ${response.status} without the export.`, fix: "Run it again in a minute. If it keeps happening, tell Zaisma: zaisma forum message --kind bug --category cli.", retryAfterSec: 60 }, EXIT_CODES.failed);
+  }
+
+  await mkdir(folder, { recursive: true });
+  const zipFile = join(folder, `.${slug}-export.${process.pid}.zip`);
+  try {
+    let sizeBytes = 0;
+    const counted = async function* () {
+      for await (const chunk of response.body) {
+        sizeBytes += chunk.length;
+        showProgress(`${(sizeBytes / 1024 / 1024).toFixed(1)} MB downloaded`);
+        yield chunk;
+      }
+    };
+    await pipeline(counted, createWriteStream(zipFile));
+    if (!isJson) process.stdout.write("\n");
+    const entries = await unpackZip(zipFile, folder);
+    let databaseFile = null;
+    const dumpFile = join(folder, "database.sql");
+    const dumpSizeBytes = (await stat(dumpFile).catch(() => null))?.size ?? 0;
+    if (dumpSizeBytes && dumpSizeBytes <= MAXIMUM_SQLITE_DUMP_SIZE_BYTES) {
+      const sqliteModule = await import("node:sqlite").catch(() => null);
+      if (sqliteModule) {
+        databaseFile = join(folder, "database.sqlite");
+        const sqlite = new sqliteModule.DatabaseSync(databaseFile);
+        try {
+          sqlite.exec(await readFile(dumpFile, "utf8"));
+        } finally {
+          sqlite.close();
+        }
+      }
+    }
+    const answer = { folder, file_count: entries.length, size_bytes: sizeBytes, database_file: databaseFile };
+    if (isJson) {
+      printJson(answer);
+      return EXIT_CODES.done;
+    }
+    console.log(`Saved everything about ${slug} in ${folder}: ${entries.length.toLocaleString("en-US")} files, ${(sizeBytes / 1024 / 1024).toFixed(1)} MB. README.txt says what's where.`);
+    if (databaseFile) console.log(`Run your game server on its database with: node bin/node.js <server> --game ${slug} --database ${databaseFile}`);
+    else if (dumpSizeBytes) console.log(`Make its database a .sqlite file with: sqlite3 ${join(folder, "database.sqlite")} < ${dumpFile}`);
+    return EXIT_CODES.done;
+  } finally {
+    await rm(zipFile, { force: true });
+  }
+}
+
+/**
+ * The files of a .zip Zaisma wrote (stored, not compressed, zip64 where it needs it), into a folder, by
+ * its central directory. Answers the paths. A path that would land outside the folder stops it.
+ */
+async function unpackZip(zipFile, folder) {
+  const handle = await open(zipFile, "r");
+  try {
+    const { size: zipSizeBytes } = await handle.stat();
+    const read = async (atByte, sizeBytes) => {
+      const buffer = Buffer.alloc(sizeBytes);
+      await handle.read(buffer, 0, sizeBytes, atByte);
+      return buffer;
+    };
+    const tailSizeBytes = Math.min(zipSizeBytes, 22 + 0xffff + 20 + 56);
+    const tail = await read(zipSizeBytes - tailSizeBytes, tailSizeBytes);
+    const endIndex = tail.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+    const broken = () => refuse("unexpected_answer", { message: "The export that came isn't a whole .zip: the download was cut short.", fix: "Run it again." }, EXIT_CODES.failed);
+    if (endIndex < 0) broken();
+    let entryCount = tail.readUInt16LE(endIndex + 10);
+    let directorySizeBytes = tail.readUInt32LE(endIndex + 12);
+    let directoryAtByte = tail.readUInt32LE(endIndex + 16);
+    if (entryCount === 0xffff || directorySizeBytes === 0xffffffff || directoryAtByte === 0xffffffff) {
+      if (endIndex < 20 || tail.readUInt32LE(endIndex - 20) !== 0x07064b50) broken();
+      const zip64End = await read(Number(tail.readBigUInt64LE(endIndex - 12)), 56);
+      entryCount = Number(zip64End.readBigUInt64LE(32));
+      directorySizeBytes = Number(zip64End.readBigUInt64LE(40));
+      directoryAtByte = Number(zip64End.readBigUInt64LE(48));
+    }
+    const directory = await read(directoryAtByte, directorySizeBytes);
+    const paths = [];
+    let atByte = 0;
+    for (let i = 0; i < entryCount; i++) {
+      if (directory.readUInt32LE(atByte) !== 0x02014b50) broken();
+      let sizeBytes = directory.readUInt32LE(atByte + 24);
+      const nameSizeBytes = directory.readUInt16LE(atByte + 28);
+      const extraSizeBytes = directory.readUInt16LE(atByte + 30);
+      const commentSizeBytes = directory.readUInt16LE(atByte + 32);
+      let headerAtByte = directory.readUInt32LE(atByte + 42);
+      const path = directory.toString("utf8", atByte + 46, atByte + 46 + nameSizeBytes);
+      // Zip64: the full size and offset, each only where its 32-bit field is full.
+      for (let extraAtByte = atByte + 46 + nameSizeBytes; extraAtByte < atByte + 46 + nameSizeBytes + extraSizeBytes; ) {
+        const id = directory.readUInt16LE(extraAtByte);
+        const fieldSizeBytes = directory.readUInt16LE(extraAtByte + 2);
+        if (id === 0x0001) {
+          let fieldAtByte = extraAtByte + 4;
+          if (sizeBytes === 0xffffffff) {
+            sizeBytes = Number(directory.readBigUInt64LE(fieldAtByte));
+            fieldAtByte += 16;
+          }
+          if (headerAtByte === 0xffffffff) headerAtByte = Number(directory.readBigUInt64LE(fieldAtByte));
+        }
+        extraAtByte += 4 + fieldSizeBytes;
+      }
+      atByte += 46 + nameSizeBytes + extraSizeBytes + commentSizeBytes;
+      const target = join(folder, ...path.split("/"));
+      if (path.startsWith("/") || path.split("/").includes("..") || relative(folder, target).startsWith("..")) broken();
+      const header = await read(headerAtByte, 30);
+      const dataAtByte = headerAtByte + 30 + header.readUInt16LE(26) + header.readUInt16LE(28);
+      await mkdir(dirname(target), { recursive: true });
+      if (sizeBytes) await pipeline(createReadStream(zipFile, { start: dataAtByte, end: dataAtByte + sizeBytes - 1 }), createWriteStream(target));
+      else await writeFile(target, "");
+      paths.push(path);
+    }
+    return paths;
+  } finally {
+    await handle.close();
+  }
+}
+
 /** database import: a dump, from a .sql file, stdin or a .sqlite file, sent in parts (POST …/database/import). */
 async function importDatabase({ slug, file }) {
   let statements;
@@ -1429,6 +1571,7 @@ async function run({ command, values, flags, globalFlags, rest }) {
     return EXIT_CODES.done;
   }
   if (command === "check") return checkFolder(values, flags);
+  if (command === "export") return exportGame(values, flags);
   if (command === "upload") return upload(values, flags);
   if (command === "versions") {
     const answer = await api("GET", `/games/${values.slug}`);