@zaisma/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaisma contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @zaisma/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Upload and publish browser games on [Zaisma](https://zaisma.com) from the command line. No dependencies; Node 18 or newer.
+
+Run it with `npx @zaisma/cli <command>`, or install it once with `npm install -g @zaisma/cli` and run `zaisma <command>`.
+
+1. Make an API key at https://zaisma.com/account, under Game developers, and set it: `export ZAISMA_KEY=zsk_…`
+2. Make a game: `zaisma new "Sky Hopper"`
+3. Upload your build folder (the one with `index.html`): `zaisma upload ./build --game sky-hopper --notes "First version"`. Only new or changed files are sent. Once the scan passes you get a private preview link.
+4. Publish it: `zaisma publish sky-hopper <version>`, then show it to everyone: `zaisma show sky-hopper --visibility listed`
+
+`zaisma versions <slug>` lists versions and their preview links; `zaisma publish` with an older version rolls back, and `--at "2026-11-01 17:00"` publishes later (`zaisma unschedule` cancels). Files over 95 MB are sent in parts automatically, up to 500 MB each. Everything here uses the [developer API](https://github.com/zaisma/zaisma/blob/main/docs/DEVELOPER-API.md).

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@zaisma/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Upload and publish browser games on Zaisma from the command line.",
+  "license": "MIT",
+  "homepage": "https://zaisma.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zaisma/zaisma.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/zaisma/zaisma/issues",
+  "keywords": [
+    "zaisma",
+    "games",
+    "browser-games",
+    "web-games",
+    "publish",
+    "upload",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "zaisma": "zaisma.mjs"
+  },
+  "files": [
+    "zaisma.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/zaisma.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// The Zaisma upload command. No dependencies; Node 18 or newer.
+// Docs: https://github.com/zaisma/zaisma/blob/main/docs/DEVELOPER-API.md
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { open, readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+const API = (process.env.ZAISMA_API || "https://zaisma.com").replace(/\/+$/, "");
+const KEY = process.env.ZAISMA_KEY || "";
+/** Files bigger than this go in parts; the server says how big each part is. */
+const DIRECT_BYTES = 95 * 1024 * 1024;
+const JUNK = new Set([".DS_Store", "Thumbs.db", "desktop.ini", "__MACOSX", ".git", "node_modules"]);
+
+const HELP = `Usage:
+  zaisma games                              List your games
+  zaisma new <title> [--slug link-name]     Make a game (it starts as a draft)
+  zaisma upload <folder> --game <slug>      Upload a version; only changed files are sent
+        [--notes "What changed"]            Patch notes, shown with the update
+        [--publish]                         Go live as soon as it passes review
+  zaisma versions <slug>                    List versions and preview links
+  zaisma publish <slug> <version>           Publish a draft, or roll back to an older version
+        [--at "2026-11-01 17:00"]           Publish later, at this time (your computer's time zone)
+  zaisma unschedule <slug> <version>        Cancel a publish-later
+  zaisma show <slug> [--visibility listed|unlisted|private|draft]
+
+Set ZAISMA_KEY to an API key from https://zaisma.com/account (under Game developers).
+Without installing: npx @zaisma/cli <command>. Installed (npm i -g @zaisma/cli): zaisma <command>.`;
+
+function fail(message) {
+  console.error(`zaisma: ${message}`);
+  process.exit(1);
+}
+
+function args(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) out[a.slice(2)] = true;
+      else out[a.slice(2)] = argv[++i];
+    } else out._.push(a);
+  }
+  return out;
+}
+
+async function api(method, path, body) {
+  if (!KEY) fail("set ZAISMA_KEY to an API key from https://zaisma.com/account first.");
+  const res = await fetch(`${API}/api/dev${path}`, {
+    method,
+    headers: { authorization: `Bearer ${KEY}`, ...(body && !(body instanceof Uint8Array) ? { "content-type": "application/json" } : {}) },
+    body: body instanceof Uint8Array ? body : body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) fail(data.error?.message ?? `the server answered ${res.status}.`);
+  return data;
+}
+
+async function walk(root) {
+  const files = [];
+  const skipped = new Set();
+  async function visit(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (JUNK.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.name.startsWith(".")) {
+        skipped.add(relative(root, full));
+        continue;
+      }
+      if (entry.isDirectory()) await visit(full);
+      else if (entry.isFile()) files.push(full);
+    }
+  }
+  await visit(root);
+  if (skipped.size) console.log(`Skipping hidden files: ${[...skipped].slice(0, 5).join(", ")}${skipped.size > 5 ? "…" : ""}`);
+  return files;
+}
+
+function sha256(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    createReadStream(file).on("data", (d) => hash.update(d)).on("end", () => resolve(hash.digest("hex"))).on("error", reject);
+  });
+}
+
+async function sendInParts(f, progress) {
+  const start = await api("POST", `/files/${f.sha256}/parts`, { bytes: f.bytes });
+  if (start.stored === "already") return;
+  const file = await open(f.full);
+  const parts = [];
+  try {
+    for (let n = 1, offset = 0; offset < f.bytes; n++, offset += start.part_bytes) {
+      const chunk = new Uint8Array(Math.min(start.part_bytes, f.bytes - offset));
+      await file.read(chunk, 0, chunk.length, offset);
+      const part = await api("PUT", `/files/${f.sha256}/parts/${n}?upload=${encodeURIComponent(start.upload)}`, chunk);
+      parts.push({ part: part.part, etag: part.etag });
+      progress(offset + chunk.length);
+    }
+  } finally {
+    await file.close();
+  }
+  await api("POST", `/files/${f.sha256}/parts/done`, { upload: start.upload, parts });
+}
+
+const size = (n) => (n >= 1048576 ? `${(n / 1048576).toFixed(1)} MB` : `${Math.ceil(n / 1024)} KB`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function upload(folder, opts) {
+  const slug = opts.game;
+  if (!folder || typeof slug !== "string") fail("usage: zaisma upload <folder> --game <slug>");
+  if (!(await stat(folder).catch(() => null))?.isDirectory()) fail(`${folder} isn't a folder.`);
+
+  const paths = await walk(folder);
+  console.log(`Checking ${paths.length} files…`);
+  const files = [];
+  for (const full of paths) {
+    files.push({ path: relative(folder, full).split(sep).join("/"), sha256: await sha256(full), bytes: (await stat(full)).size, full });
+  }
+  const list = files.map(({ full: _, ...f }) => f);
+  const plan = await api("POST", `/games/${slug}/uploads`, { files: list });
+  const todo = files.filter((f, i) => plan.missing.includes(f.sha256) && files.findIndex((g) => g.sha256 === f.sha256) === i);
+  const total = todo.reduce((n, f) => n + f.bytes, 0);
+  console.log(todo.length ? `Sending ${todo.length} new or changed files (${size(total)})…` : "Nothing changed since your last upload; making a version from the stored files.");
+
+  let sent = 0;
+  const queue = [...todo];
+  await Promise.all(
+    Array.from({ length: 4 }, async () => {
+      for (let f = queue.shift(); f; f = queue.shift()) {
+        if (f.bytes > DIRECT_BYTES) await sendInParts(f, (n) => process.stdout.write(`\r  ${size(sent + n)} of ${size(total)}   `));
+        else await api("PUT", `/files/${f.sha256}`, new Uint8Array(await readFile(f.full)));
+        sent += f.bytes;
+        process.stdout.write(`\r  ${size(sent)} of ${size(total)}   `);
+      }
+    }),
+  );
+  if (todo.length) process.stdout.write("\n");
+
+  const { version } = await api("POST", `/games/${slug}/versions`, { files: list, notes: typeof opts.notes === "string" ? opts.notes : "", publish: opts.publish ? "when-approved" : undefined });
+  console.log(`Version ${version.id} is being scanned. This usually takes under a minute…`);
+
+  for (let i = 0; i < 200; i++) {
+    await sleep(3000);
+    const { version: v } = await api("GET", `/games/${slug}/versions/${version.id}`);
+    if (v.scan === "scanning") continue;
+    if (v.scan === "approved") {
+      if (v.live) console.log(`Passed and live: ${API}/g/${slug}`);
+      else {
+        console.log(`Passed. Your private preview: ${v.preview_url}`);
+        console.log(`Publish it with: zaisma publish ${slug} ${v.id}`);
+      }
+    } else {
+      console.log(v.scan === "held" ? "Held: a person will look at it, usually within a day. What the scan found:" : "Rejected. What the scan found:");
+      for (const f of v.findings ?? []) console.log(`  - ${f.detail}${f.path ? ` (${f.path})` : ""}`);
+      if (v.scan === "rejected") process.exit(1);
+    }
+    return;
+  }
+  console.log(`Still scanning. Check later with: zaisma versions ${slug}`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const opts = args(rest);
+  if (!command || command === "help" || command === "--help" || command === "-h") return console.log(HELP);
+
+  if (command === "games") {
+    const { games } = await api("GET", "/games");
+    if (!games.length) return console.log('No games yet. Make one with: zaisma new "My Game"');
+    for (const g of games) console.log(`${g.slug.padEnd(28)} ${g.visibility.padEnd(9)} ${g.review.padEnd(8)} ${g.title}`);
+    return;
+  }
+  if (command === "new") {
+    const title = opts._.join(" ");
+    if (!title) fail('usage: zaisma new "My Game" [--slug my-game]');
+    const { game } = await api("POST", "/games", { title, ...(typeof opts.slug === "string" ? { slug: opts.slug } : {}) });
+    return console.log(`Made ${game.url} (a draft). Upload it with: zaisma upload <folder> --game ${game.slug}`);
+  }
+  if (command === "upload") return upload(opts._[0], opts);
+  if (command === "versions") {
+    const slug = opts._[0];
+    if (!slug) fail("usage: zaisma versions <slug>");
+    const { versions } = await api("GET", `/games/${slug}`);
+    for (const v of versions) console.log(`${v.id}  ${new Date(v.created_at).toISOString().slice(0, 16).replace("T", " ")}  ${(v.live ? "live" : v.scan).padEnd(9)} ${v.preview_url ?? ""}${v.publish_at ? `  goes live ${new Date(v.publish_at).toLocaleString()}` : ""}`);
+    return;
+  }
+  if (command === "publish") {
+    const [slug, id] = opts._;
+    if (!slug || !id) fail("usage: zaisma publish <slug> <version>");
+    if (typeof opts.at === "string") {
+      const at = new Date(opts.at.includes("T") || /z$|[+-]\d\d:?\d\d$/i.test(opts.at) ? opts.at : opts.at.replace(" ", "T"));
+      if (Number.isNaN(at.getTime())) fail('give --at as a date and time, like "2026-11-01 17:00".');
+      const { version } = await api("POST", `/games/${slug}/versions/${id}/publish`, { at: at.getTime() });
+      console.log(`Version ${id} will go live at ${new Date(version.publish_at).toLocaleString()}${version.scan === "scanning" ? ", if it has passed the scan by then" : ""}.`);
+      return;
+    }
+    const { game } = await api("POST", `/games/${slug}/versions/${id}/publish`);
+    console.log(`Version ${id} is live at ${game.url}`);
+    if (game.visibility === "draft") console.log(`The game is still a draft, so only you can see it. Show it with: zaisma show ${slug} --visibility listed`);
+    return;
+  }
+  if (command === "unschedule") {
+    const [slug, id] = opts._;
+    if (!slug || !id) fail("usage: zaisma unschedule <slug> <version>");
+    await api("DELETE", `/games/${slug}/versions/${id}/publish`);
+    return console.log(`Version ${id} won't be published by itself.`);
+  }
+  if (command === "show") {
+    const slug = opts._[0];
+    if (!slug || typeof opts.visibility !== "string") fail("usage: zaisma show <slug> --visibility listed|unlisted|private|draft");
+    const { game } = await api("PATCH", `/games/${slug}`, { visibility: opts.visibility });
+    return console.log(`${game.title} is now ${game.visibility}.`);
+  }
+  fail(`unknown command "${command}". Run zaisma help.`);
+}
+
+main().catch((err) => fail(err.message));