@caisual/cli 0.1.0

package/dist/caisual.mjs

@@ -0,0 +1,908 @@
+#!/usr/bin/env node
+
+// src/caisual.ts
+import { createHash } from "node:crypto";
+import { createReadStream, promises as fs } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+
+// ../contracts/src/slug.ts
+var NOMI_RISERVATI = [
+  "www",
+  "api",
+  "app",
+  "play",
+  "live",
+  "multi",
+  "cdn",
+  "assets",
+  "static",
+  "mail",
+  "mx",
+  "ns1",
+  "ns2",
+  "autodiscover",
+  "_dmarc",
+  "admin",
+  "login",
+  "account",
+  "auth",
+  "pay",
+  "secure",
+  "support",
+  "help",
+  "blog",
+  "status",
+  "dev",
+  "staging",
+  "test",
+  "caisual",
+  "shipz"
+];
+var RISERVATI = new Set(NOMI_RISERVATI);
+var SLUG_NUOVO = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var SLUG_STORICO = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function isValidSlug(value) {
+  return value.length >= 3 && value.length <= 32 && SLUG_NUOVO.test(value) || SLUG_STORICO.test(value);
+}
+function isReservedSlug(value) {
+  return RISERVATI.has(value);
+}
+
+// ../contracts/src/manifest.ts
+var CAMPI = /* @__PURE__ */ new Set([
+  "manifest",
+  "id",
+  "name",
+  "description",
+  "cover",
+  "screenshots",
+  "tags",
+  "language",
+  "platform",
+  "orientation",
+  "input",
+  "visibility",
+  "network",
+  "isolated",
+  "players",
+  "lobby",
+  "roles",
+  "teams",
+  "voice",
+  "modes"
+]);
+var INPUT = /* @__PURE__ */ new Set(["keyboard", "mouse", "touch", "gamepad"]);
+var PLATFORM = /* @__PURE__ */ new Set(["desktop", "mobile", "both"]);
+var ORIENTATION = /* @__PURE__ */ new Set(["landscape", "portrait"]);
+var VISIBILITY = /* @__PURE__ */ new Set(["public", "unlisted"]);
+var VOICE = /* @__PURE__ */ new Set(["none", "room", "team", "proximity"]);
+var TAG = /^[a-z0-9-]+$/;
+var ID_INTERNO = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function oggetto(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value;
+}
+function percorsoRelativo(value) {
+  if (value === "" || value.startsWith("/") || value.includes("\\") || value.includes("\0")) return false;
+  if (value.includes("?") || value.includes("#")) return false;
+  const parti = value.split("/");
+  if (parti.some((parte) => parte === "" || parte === "." || parte === "..")) return false;
+  try {
+    const decoded = parti.map((parte) => decodeURIComponent(parte));
+    return !decoded.some((parte) => parte === "" || parte === "." || parte === ".." || parte.includes("/"));
+  } catch {
+    return false;
+  }
+}
+function hostValido(value) {
+  if (value.length === 0 || value.length > 253) return false;
+  if (value.includes("://") || /[/:?#@]/.test(value)) return false;
+  const parti = value.split(".");
+  return parti.every(
+    (parte) => parte.length >= 1 && parte.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(parte)
+  );
+}
+function interoTra(value, min, max) {
+  return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+}
+function stringaDefault(dati, campo, valoreDefault, errori) {
+  const value = dati[campo];
+  if (value === void 0) return valoreDefault;
+  if (typeof value !== "string") {
+    errori.push(`${campo}: must be a string.`);
+    return valoreDefault;
+  }
+  return value;
+}
+function validaManifest(valore) {
+  const errori = [];
+  const dati = oggetto(valore);
+  if (dati === null) return { ok: false, errori: ["manifest: must be a JSON object."] };
+  for (const campo of Object.keys(dati)) {
+    if (!CAMPI.has(campo)) errori.push(`${campo}: unknown field.`);
+  }
+  if (dati.manifest === void 0) errori.push("manifest: is required and must be 1.");
+  else if (dati.manifest !== 1) errori.push("manifest: must be exactly 1.");
+  const id = stringaDefault(dati, "id", "", errori);
+  if (dati.id === void 0) errori.push("id: is required.");
+  else if (typeof dati.id === "string") {
+    if (!isValidSlug(id)) {
+      errori.push("id: must be 3-32 lowercase ASCII letters or digits with internal hyphens; historical UUID v4 slugs may be 36 characters.");
+    } else if (isReservedSlug(id)) errori.push("id: this slug is reserved.");
+  }
+  const name = stringaDefault(dati, "name", "", errori);
+  if (dati.name === void 0) errori.push("name: is required.");
+  else if (typeof dati.name === "string" && (name.trim() === "" || name.length > 60)) {
+    errori.push("name: must contain 1-60 characters.");
+  }
+  const description = stringaDefault(dati, "description", "", errori);
+  if (description.length > 500) errori.push("description: must be at most 500 characters.");
+  let cover = null;
+  if (dati.cover !== void 0 && dati.cover !== null) {
+    if (typeof dati.cover !== "string") errori.push("cover: must be a relative file path or null.");
+    else if (!percorsoRelativo(dati.cover)) errori.push("cover: must be a relative file path without query, fragment, or parent segments.");
+    else cover = dati.cover;
+  }
+  const screenshots = [];
+  if (dati.screenshots !== void 0) {
+    if (!Array.isArray(dati.screenshots)) errori.push("screenshots: must be an array of relative file paths.");
+    else {
+      if (dati.screenshots.length > 8) errori.push("screenshots: must contain at most 8 paths.");
+      for (const [indice, value] of dati.screenshots.entries()) {
+        if (typeof value !== "string" || !percorsoRelativo(value)) {
+          errori.push(`screenshots[${indice}]: must be a relative file path without query, fragment, or parent segments.`);
+        } else screenshots.push(value);
+      }
+    }
+  }
+  const tags = [];
+  if (dati.tags !== void 0) {
+    if (!Array.isArray(dati.tags)) errori.push("tags: must be an array.");
+    else {
+      if (dati.tags.length > 10) errori.push("tags: must contain at most 10 tags.");
+      for (const [indice, value] of dati.tags.entries()) {
+        if (typeof value !== "string" || value.length > 24 || !TAG.test(value)) {
+          errori.push(`tags[${indice}]: must be 1-24 lowercase letters, digits, or hyphens.`);
+        } else tags.push(value);
+      }
+    }
+  }
+  const language = stringaDefault(dati, "language", "en", errori);
+  if (!/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(language)) {
+    errori.push("language: must be a BCP 47 language tag such as en, it, or pt-BR.");
+  }
+  let platform = "both";
+  if (dati.platform === void 0) errori.push("platform: is required.");
+  else if (typeof dati.platform !== "string" || !PLATFORM.has(dati.platform)) {
+    errori.push("platform: must be desktop, mobile, or both.");
+  } else platform = dati.platform;
+  let orientation = "landscape";
+  if (dati.orientation !== void 0) {
+    if (typeof dati.orientation !== "string" || !ORIENTATION.has(dati.orientation)) {
+      errori.push("orientation: must be landscape or portrait.");
+    } else orientation = dati.orientation;
+  }
+  const input = [];
+  if (dati.input !== void 0) {
+    if (!Array.isArray(dati.input)) errori.push("input: must be an array.");
+    else for (const [indice, value] of dati.input.entries()) {
+      if (typeof value !== "string" || !INPUT.has(value)) {
+        errori.push(`input[${indice}]: must be keyboard, mouse, touch, or gamepad.`);
+      } else if (input.includes(value)) errori.push(`input[${indice}]: duplicate value ${value}.`);
+      else input.push(value);
+    }
+  }
+  let visibility = "public";
+  if (dati.visibility !== void 0) {
+    if (typeof dati.visibility !== "string" || !VISIBILITY.has(dati.visibility)) {
+      errori.push("visibility: must be public or unlisted.");
+    } else visibility = dati.visibility;
+  }
+  const network = [];
+  if (dati.network !== void 0) {
+    if (!Array.isArray(dati.network)) errori.push("network: must be an array of host names.");
+    else for (const [indice, value] of dati.network.entries()) {
+      if (typeof value !== "string" || !hostValido(value)) {
+        errori.push(`network[${indice}]: must be a host name without scheme, port, path, query, or fragment.`);
+      } else if (network.includes(value)) errori.push(`network[${indice}]: duplicate host ${value}.`);
+      else network.push(value);
+    }
+  }
+  let isolated = false;
+  if (dati.isolated !== void 0) {
+    if (typeof dati.isolated !== "boolean") errori.push("isolated: must be a boolean.");
+    else isolated = dati.isolated;
+  }
+  let players = { min: 1, max: 1 };
+  if (dati.players !== void 0) {
+    const value = oggetto(dati.players);
+    if (value === null) errori.push("players: must be an object with min and max.");
+    else {
+      for (const campo of Object.keys(value)) {
+        if (campo !== "min" && campo !== "max") errori.push(`players.${campo}: unknown field.`);
+      }
+      if (!interoTra(value.min, 1, 16)) errori.push("players.min: must be an integer from 1 to 16.");
+      if (!interoTra(value.max, 1, 16)) errori.push("players.max: must be an integer from 1 to 16 in manifest version 1.");
+      if (interoTra(value.min, 1, 16) && interoTra(value.max, 1, 16)) {
+        if (value.min > value.max) errori.push("players.max: must be greater than or equal to players.min.");
+        else players = { min: value.min, max: value.max };
+      }
+    }
+  }
+  let lobby = false;
+  if (dati.lobby !== void 0) {
+    if (typeof dati.lobby !== "boolean") errori.push("lobby: must be a boolean.");
+    else lobby = dati.lobby;
+  }
+  const roles = [];
+  if (dati.roles !== void 0) {
+    if (!Array.isArray(dati.roles)) errori.push("roles: must be an array.");
+    else {
+      const ids = /* @__PURE__ */ new Set();
+      for (const [indice, raw] of dati.roles.entries()) {
+        const value = oggetto(raw);
+        if (value === null) {
+          errori.push(`roles[${indice}]: must be an object.`);
+          continue;
+        }
+        for (const campo of Object.keys(value)) {
+          if (!["id", "min", "max"].includes(campo)) errori.push(`roles[${indice}].${campo}: unknown field.`);
+        }
+        const idRuolo = value.id;
+        const min = value.min;
+        const max = value.max;
+        let valido = true;
+        if (typeof idRuolo !== "string" || idRuolo.length > 32 || !ID_INTERNO.test(idRuolo)) {
+          errori.push(`roles[${indice}].id: must be 1-32 lowercase letters, digits, or internal hyphens.`);
+          valido = false;
+        } else if (ids.has(idRuolo)) {
+          errori.push(`roles[${indice}].id: duplicate role ${idRuolo}.`);
+          valido = false;
+        } else ids.add(idRuolo);
+        if (!interoTra(min, 0, 16)) {
+          errori.push(`roles[${indice}].min: must be an integer from 0 to 16.`);
+          valido = false;
+        }
+        if (max !== void 0 && !interoTra(max, 0, 16)) {
+          errori.push(`roles[${indice}].max: must be an integer from 0 to 16 when present.`);
+          valido = false;
+        }
+        if (typeof min === "number" && typeof max === "number" && min > max) {
+          errori.push(`roles[${indice}].max: must be greater than or equal to min.`);
+          valido = false;
+        }
+        if (valido) roles.push(max === void 0 ? { id: idRuolo, min } : { id: idRuolo, min, max });
+      }
+    }
+  }
+  let teams = null;
+  if (dati.teams !== void 0 && dati.teams !== null) {
+    const value = oggetto(dati.teams);
+    if (value === null) errori.push("teams: must be null or an object with min and max.");
+    else {
+      for (const campo of Object.keys(value)) {
+        if (campo !== "min" && campo !== "max") errori.push(`teams.${campo}: unknown field.`);
+      }
+      if (!interoTra(value.min, 2, 16)) errori.push("teams.min: must be an integer from 2 to 16.");
+      if (!interoTra(value.max, 2, 16)) errori.push("teams.max: must be an integer from 2 to 16.");
+      if (interoTra(value.min, 2, 16) && interoTra(value.max, 2, 16)) {
+        if (value.min > value.max) errori.push("teams.max: must be greater than or equal to teams.min.");
+        else teams = { min: value.min, max: value.max };
+      }
+    }
+  }
+  let voice = "none";
+  if (dati.voice !== void 0) {
+    if (typeof dati.voice !== "string" || !VOICE.has(dati.voice)) {
+      errori.push("voice: must be none, room, team, or proximity.");
+    } else voice = dati.voice;
+  }
+  const modes = [];
+  if (dati.modes !== void 0) {
+    if (!Array.isArray(dati.modes)) errori.push("modes: must be an array.");
+    else {
+      const ids = /* @__PURE__ */ new Set();
+      for (const [indice, raw] of dati.modes.entries()) {
+        const value = oggetto(raw);
+        if (value === null) {
+          errori.push(`modes[${indice}]: must be an object.`);
+          continue;
+        }
+        for (const campo of Object.keys(value)) {
+          if (campo !== "id" && campo !== "matchmaking") errori.push(`modes[${indice}].${campo}: unknown field.`);
+        }
+        if (typeof value.id !== "string" || value.id.length > 32 || !ID_INTERNO.test(value.id)) {
+          errori.push(`modes[${indice}].id: must be 1-32 lowercase letters, digits, or internal hyphens.`);
+          continue;
+        }
+        if (ids.has(value.id)) {
+          errori.push(`modes[${indice}].id: duplicate mode ${value.id}.`);
+          continue;
+        }
+        ids.add(value.id);
+        if (value.matchmaking === void 0) {
+          modes.push({ id: value.id });
+          continue;
+        }
+        const matchmaking = oggetto(value.matchmaking);
+        if (matchmaking === null) {
+          errori.push(`modes[${indice}].matchmaking: must be an object.`);
+          continue;
+        }
+        for (const campo of Object.keys(matchmaking)) {
+          if (!["key", "timeoutMs", "fallback"].includes(campo)) {
+            errori.push(`modes[${indice}].matchmaking.${campo}: unknown field.`);
+          }
+        }
+        let valido = true;
+        const key = [];
+        if (!Array.isArray(matchmaking.key) || matchmaking.key.length === 0) {
+          errori.push(`modes[${indice}].matchmaking.key: must be a non-empty array.`);
+          valido = false;
+        } else for (const [keyIndice, item] of matchmaking.key.entries()) {
+          if (typeof item !== "string" || item.length > 32 || !ID_INTERNO.test(item)) {
+            errori.push(`modes[${indice}].matchmaking.key[${keyIndice}]: must be 1-32 lowercase letters, digits, or internal hyphens.`);
+            valido = false;
+          } else key.push(item);
+        }
+        if (!Number.isSafeInteger(matchmaking.timeoutMs) || matchmaking.timeoutMs < 1) {
+          errori.push(`modes[${indice}].matchmaking.timeoutMs: must be a positive integer.`);
+          valido = false;
+        }
+        if (matchmaking.fallback !== "ghost" && matchmaking.fallback !== "bot") {
+          errori.push(`modes[${indice}].matchmaking.fallback: must be ghost or bot.`);
+          valido = false;
+        }
+        if (valido) modes.push({ id: value.id, matchmaking: {
+          key,
+          timeoutMs: matchmaking.timeoutMs,
+          fallback: matchmaking.fallback
+        } });
+      }
+    }
+  }
+  if (errori.length > 0) return { ok: false, errori };
+  return { ok: true, manifest: {
+    manifest: 1,
+    id,
+    name,
+    description,
+    cover,
+    screenshots,
+    tags,
+    language,
+    platform,
+    orientation,
+    input,
+    visibility,
+    network,
+    isolated,
+    players,
+    lobby,
+    roles,
+    teams,
+    voice,
+    modes
+  } };
+}
+
+// ../../docs/publish.md
+var publish_default = '# Publish a game on Caisual\n\nCaisual hosts browser games supplied as folders. Each publish creates an immutable version and moves the game\'s stable link to that version.\nThe current publishing flow is for single-player games and does not require changes in the Caisual dashboard.\n\n## Game folder\n\nUse this structure:\n\n```text\nmy-game/\n  caisual.json\n  client/\n    index.html\n    ...\n```\n\n`caisual.json` and `client/index.html` are required. Put every file used by the game under `client/`.\n\nRun `npx @caisual/cli init my-game` to create a minimal folder, or create these files yourself.\n\n## caisual.json\n\nThe file must contain one JSON object. Unknown fields are rejected. This is a complete example for the current single-player release:\n\n```json\n{\n  "manifest": 1,\n  "id": "my-game",\n  "name": "My Game",\n  "description": "A short description of the game.",\n  "cover": "cover.png",\n  "screenshots": ["screenshots/level-one.png"],\n  "tags": ["puzzle"],\n  "language": "en",\n  "platform": "both",\n  "orientation": "landscape",\n  "input": ["keyboard", "mouse", "touch"],\n  "visibility": "public",\n  "network": [],\n  "isolated": false,\n  "players": { "min": 1, "max": 1 },\n  "lobby": false,\n  "roles": [],\n  "teams": null,\n  "voice": "none",\n  "modes": []\n}\n```\n\n- `manifest` is required and must be `1`.\n- `id` is required. Use 3 to 32 lowercase ASCII letters or digits, with single hyphens only between groups. The ID becomes the URL slug. Choose it carefully because it cannot be renamed or reused after deletion.\n- `name` is required and must contain 1 to 60 characters.\n- `description` is optional, defaults to an empty string, and can contain at most 500 characters.\n- `cover` is optional. Use a relative path inside `client/`, or `null`. Do not include a query, fragment, empty segment, or parent segment.\n- `screenshots` is optional and defaults to `[]`. It accepts up to 8 relative paths inside `client/`.\n- `tags` is optional and defaults to `[]`. It accepts up to 10 values. Each value uses 1 to 24 lowercase letters, digits, or hyphens.\n- `language` is optional and defaults to `en`. Use a BCP 47 language tag such as `en`, `it`, or `pt-BR`.\n- `platform` is required. Use `desktop` when the game needs a keyboard, mouse, large display, or desktop performance. Use `mobile` when it is designed only for touch and small screens. Use `both` only after checking that layout, performance, and controls work on both.\n- `orientation` is optional and defaults to `landscape`. Use `landscape` or `portrait` to describe the intended mobile layout. The device may not honor an orientation request.\n- `input` is optional and defaults to `[]`. Include every supported input from `keyboard`, `mouse`, `touch`, and `gamepad`. Do not claim an input until the game is usable with it.\n- `visibility` is optional and defaults to `public`. Use `public` for catalog eligibility or `unlisted` for access by direct link only.\n- `network` is optional and defaults to `[]`. List every external host contacted or loaded by the game, without scheme, port, path, query, or fragment, for example `api.example.com`. If an external host is missing, the browser blocks the request. Keep the array empty when the game uses only its own files and Caisual services.\n- `isolated` is optional and defaults to `false`. Use `true` only when the game requires shared memory or threaded WebAssembly. Every external host in `network` must then send headers compatible with cross-origin isolation.\n- `players` is optional and defaults to `{ "min": 1, "max": 1 }`. Both values are integers from 1 to 16 and `max` must be at least `min`. Keep both at `1` in the current release.\n- `lobby` is optional and defaults to `false`. Keep it `false` in the current release.\n- `roles` is optional and defaults to `[]`. Each future entry has an `id` of 1 to 32 lowercase letters, digits, or internal hyphens, a `min` integer from 0 to 16, and an optional `max` in the same range. Keep it empty in the current release.\n- `teams` is optional and defaults to `null`. A future object has `min` and `max` integers from 2 to 16, with `max` at least `min`. Keep it `null` in the current release.\n- `voice` is optional and defaults to `none`. The accepted values are `none`, `room`, `team`, and `proximity`. Use `none` in the current release.\n- `modes` is optional and defaults to `[]`. A future mode has a unique `id` using 1 to 32 lowercase letters, digits, or internal hyphens. It may have `matchmaking` with a non-empty `key` array using the same format, a positive integer `timeoutMs`, and `fallback` set to `ghost` or `bot`. Keep it empty in the current release.\n\nThe CLI prints every manifest error in one run. Fix every listed field and rule before retrying.\n\n## client/index.html\n\n`index.html` must be at the root of `client/`. Use relative URLs such as `./game.js` or `assets/sprite.png`. Do not use root-relative URLs such as `/game.js`, and do not use parent paths that leave the published `client/` tree.\n\nDo not register a service worker. The game runs in an iframe on its own origin inside `caisual.com`. Test it without assuming access to the parent page, parent cookies, or files outside `client/`.\n\n## Limits\n\n- At most 2,000 files per version.\n- At most 50,000,000 bytes per file.\n- At most 200,000,000 bytes for all files in one version.\n- Dotfiles, dot-directories, and directories named `node_modules` are ignored.\n- Symbolic links and other non-regular files are rejected.\n\nReduce or split files that exceed the per-file limit. Remove generated files that the browser does not need.\n\n## Publish\n\nUse the key supplied by the creator. Set it in the environment so it does not enter shell history as a command-line flag:\n\n```sh\nexport CAISUAL_KEY=\'ck_...\'\nnpx @caisual/cli publish\n```\n\nRun the command from the game folder, or pass the folder path after `publish`. For local portal development only, set `CAISUAL_ORIGIN` to the local HTTP origin.\n\nThe CLI validates the folder, computes every file size and SHA-256 digest, creates a new version, uploads the files, completes the version, and prints the game URL. The stable URL is `https://caisual.com/g/<id>`.\n\nThe first games from a new creator are reviewed before they can appear in the public catalog. Their stable links still work while review is pending.\n\n## Update, unlist, or delete\n\nTo update a game, change its files without changing `id`, then run `npx @caisual/cli publish` again. This creates a new version and keeps the same stable game URL.\n\nTo remove a game from the catalog, set `visibility` to `unlisted` and publish, or change visibility from the dashboard. To delete a game, use the dashboard. Deletion is permanent and its ID cannot be reused.\n\n## Common errors\n\n- `CAISUAL_KEY is required`: export the creator\'s key in the same shell before publishing.\n- `The publish API key is not valid`: create a new key in the account dashboard if the old key expired or was revoked.\n- `caisual.json is not valid`: read every reported field and rule, fix all of them, then retry.\n- `client/index.html: file not found`: place `index.html` directly under `client/`, not in a nested build folder.\n- `referenced file not found`: make sure `cover` and every screenshot path match a file under `client/`, including letter case.\n- `file is larger than 50 MB`: compress, reduce, or split the asset and update its references.\n- `upload failed` or a temporary portal error: keep the files unchanged and retry the same publish command. The CLI retries temporary upload failures automatically.\n- An external request works locally but fails after publishing: add its host to `network` and publish a new version.\n- A threaded WebAssembly game fails to start: set `isolated` to `true` and verify that every declared external host supports cross-origin isolation.\n\nMultiplayer rooms arrive with the kit; the same folder and command will publish them.\n';
+
+// src/caisual.ts
+var DEFAULT_ORIGIN = "https://caisual.com";
+var MAX_FILE_BYTES = 5e7;
+var MAX_VERSION_BYTES = 2e8;
+var MAX_FILES = 2e3;
+var UPLOAD_CONCURRENCY = 4;
+var MAX_RETRIES = 3;
+var SERVER_MESSAGE = "Multiplayer servers arrive in the next kit version. Remove server.js to publish this game as single player.";
+var CliError = class extends Error {
+  constructor(exitCode, message) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "CliError";
+  }
+  exitCode;
+};
+var ApiError = class extends Error {
+  constructor(status, code, message, hints) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.hints = hints;
+    this.name = "ApiError";
+  }
+  status;
+  code;
+  hints;
+};
+function help() {
+  return `Caisual ${"0.1.0"}
+
+Usage:
+  caisual init [folder]
+  caisual publish [folder]
+  caisual skill
+  caisual --help
+  caisual --version
+
+Environment:
+  CAISUAL_KEY       Required by publish. It is never accepted as a flag.
+  CAISUAL_ORIGIN    Portal origin for development. Defaults to ${DEFAULT_ORIGIN}.
+`;
+}
+function slugFromFolder(folderName) {
+  let slug = folderName.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-").slice(0, 32).replace(/-+$/g, "");
+  if (slug.length < 3) slug = slug === "" ? "my-game" : `${slug}-game`;
+  if (isReservedSlug(slug)) slug = `${slug.slice(0, 27).replace(/-+$/g, "")}-game`;
+  return slug.slice(0, 32).replace(/-+$/g, "");
+}
+function displayName(folderName) {
+  const name = folderName.replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+  return (name === "" ? "My Game" : name).slice(0, 60);
+}
+async function exists(path) {
+  try {
+    await fs.lstat(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+async function writeNewFile(path, content) {
+  try {
+    await fs.writeFile(path, content, { encoding: "utf8", flag: "wx" });
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") return false;
+    throw error;
+  }
+}
+async function init(folderArgument) {
+  const root = resolve(process.cwd(), folderArgument);
+  try {
+    await fs.mkdir(join(root, "client"), { recursive: true });
+  } catch {
+    throw new CliError(2, `The game folder could not be created: ${root}`);
+  }
+  const folderName = basename(root);
+  const manifest = {
+    manifest: 1,
+    id: slugFromFolder(folderName),
+    name: displayName(folderName),
+    platform: "both"
+  };
+  const manifestPath = join(root, "caisual.json");
+  const indexPath = join(root, "client", "index.html");
+  const index = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Hello</title>
+</head>
+<body>
+  <main>Hello</main>
+  <!-- Add the Caisual kit here when it becomes available. -->
+</body>
+</html>
+`;
+  const manifestCreated = await writeNewFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  const indexCreated = await writeNewFile(indexPath, index);
+  process.stdout.write(`${manifestCreated ? "Created" : "Kept"} ${manifestPath}
+`);
+  process.stdout.write(`${indexCreated ? "Created" : "Kept"} ${indexPath}
+`);
+}
+async function sha256(path) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest("hex");
+}
+async function mapLimited(items, limit, operation) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (true) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= items.length) return;
+      results[index] = await operation(items[index], index);
+    }
+  }
+  await Promise.all(Array.from(
+    { length: Math.min(limit, items.length) },
+    () => worker()
+  ));
+  return results;
+}
+async function listClientFiles(clientRoot) {
+  let rootStat;
+  try {
+    rootStat = await fs.stat(clientRoot);
+  } catch {
+    throw new CliError(2, "client/: folder not found.");
+  }
+  if (!rootStat.isDirectory()) throw new CliError(2, "client/: must be a folder.");
+  const found = [];
+  async function visit(folder, prefix) {
+    const entries = await fs.readdir(folder, { withFileTypes: true });
+    entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const absolutePath = join(folder, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        throw new CliError(2, `${relativePath}: only regular files are supported.`);
+      }
+      const fileStat = await fs.stat(absolutePath);
+      if (fileStat.size > MAX_FILE_BYTES) {
+        throw new CliError(2, `${relativePath}: file is larger than 50 MB (${fileStat.size} bytes).`);
+      }
+      found.push({ path: relativePath, absolutePath, bytes: fileStat.size });
+      if (found.length > MAX_FILES) {
+        throw new CliError(2, `client/: a version can contain at most ${MAX_FILES} files.`);
+      }
+    }
+  }
+  await visit(clientRoot, "");
+  if (!found.some((file) => file.path === "index.html")) {
+    throw new CliError(2, "client/index.html: file not found.");
+  }
+  const totalBytes = found.reduce((total, file) => total + file.bytes, 0);
+  if (totalBytes > MAX_VERSION_BYTES) {
+    throw new CliError(2, "client/: a version can contain at most 200 MB in total.");
+  }
+  return await mapLimited(found, UPLOAD_CONCURRENCY, async (file) => ({
+    ...file,
+    sha256: await sha256(file.absolutePath)
+  }));
+}
+function portalOrigin() {
+  const raw = process.env.CAISUAL_ORIGIN?.trim() || DEFAULT_ORIGIN;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new CliError(1, "CAISUAL_ORIGIN must be a valid HTTP or HTTPS origin.");
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+    throw new CliError(1, "CAISUAL_ORIGIN must be a valid HTTP or HTTPS origin.");
+  }
+  return url.origin;
+}
+function object(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+async function apiError(response) {
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = null;
+  }
+  const envelope = object(payload);
+  const detail = object(envelope?.error);
+  const message = typeof detail?.message === "string" ? detail.message : `The portal returned HTTP ${response.status}.`;
+  const code = typeof detail?.code === "string" ? detail.code : "http_error";
+  const hints = Array.isArray(detail?.hints) ? detail.hints.filter((hint) => typeof hint === "string") : [];
+  return new ApiError(response.status, code, message, hints);
+}
+async function requestJson(url, init2) {
+  let response;
+  try {
+    response = await fetch(url, init2);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CliError(1, `The portal could not be reached: ${detail}`);
+  }
+  if (!response.ok) throw await apiError(response);
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new CliError(1, "The portal returned an invalid JSON response.");
+  }
+  const result = object(payload);
+  if (result === null) throw new CliError(1, "The portal returned an invalid JSON response.");
+  return result;
+}
+function contentType(path) {
+  const types = {
+    ".aac": "audio/aac",
+    ".avif": "image/avif",
+    ".bmp": "image/bmp",
+    ".css": "text/css; charset=utf-8",
+    ".csv": "text/csv; charset=utf-8",
+    ".gif": "image/gif",
+    ".glb": "model/gltf-binary",
+    ".gltf": "model/gltf+json",
+    ".html": "text/html; charset=utf-8",
+    ".ico": "image/vnd.microsoft.icon",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4",
+    ".oga": "audio/ogg",
+    ".ogg": "audio/ogg",
+    ".opus": "audio/ogg",
+    ".otf": "font/otf",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".ttf": "font/ttf",
+    ".txt": "text/plain; charset=utf-8",
+    ".wasm": "application/wasm",
+    ".wav": "audio/wav",
+    ".webm": "video/webm",
+    ".webmanifest": "application/manifest+json",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".xml": "application/xml; charset=utf-8",
+    ".zip": "application/zip"
+  };
+  return types[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+function progressLine(path, sent, total, retry) {
+  const percentage = total === 0 ? 100 : Math.min(100, Math.floor(sent / total * 100));
+  const blocks = Math.floor(percentage / 10);
+  const suffix = retry === 0 ? "" : ` retry ${retry}/${MAX_RETRIES}`;
+  return `${path} [${"#".repeat(blocks)}${".".repeat(10 - blocks)}] ${percentage}%${suffix}
+`;
+}
+async function* uploadBody(file, retry) {
+  let sent = 0;
+  let lastBlock = -1;
+  process.stdout.write(progressLine(file.path, 0, file.bytes, retry));
+  if (file.bytes === 0) return;
+  for await (const chunk of createReadStream(file.absolutePath)) {
+    const buffer = chunk;
+    sent += buffer.byteLength;
+    const block = Math.floor(Math.min(100, sent / file.bytes * 100) / 10);
+    if (block > lastBlock) {
+      process.stdout.write(progressLine(file.path, sent, file.bytes, retry));
+      lastBlock = block;
+    }
+    yield buffer;
+  }
+}
+function sleep(milliseconds) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
+}
+async function uploadFile(file, target, key, origin) {
+  let uploadUrl;
+  try {
+    uploadUrl = new URL(target.url, origin);
+  } catch {
+    throw new CliError(1, `The portal returned an invalid upload URL for ${file.path}.`);
+  }
+  if (uploadUrl.origin !== origin) {
+    throw new CliError(1, `The portal returned an unsafe upload URL for ${file.path}.`);
+  }
+  for (let retry = 0; retry <= MAX_RETRIES; retry += 1) {
+    try {
+      const response = await fetch(uploadUrl, {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${key}`,
+          "Content-Type": contentType(file.path),
+          "Content-Length": String(file.bytes)
+        },
+        body: uploadBody(file, retry),
+        duplex: "half"
+      });
+      if (response.ok) {
+        return;
+      }
+      if (response.status < 500 || retry === MAX_RETRIES) throw await apiError(response);
+      await response.arrayBuffer();
+      process.stderr.write(`${file.path}: upload failed with HTTP ${response.status}; retrying.
+`);
+    } catch (error) {
+      if (error instanceof ApiError || error instanceof CliError) throw error;
+      if (retry === MAX_RETRIES) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliError(1, `${file.path}: upload failed after ${MAX_RETRIES} retries: ${detail}`);
+      }
+      process.stderr.write(`${file.path}: network error; retrying.
+`);
+    }
+    await sleep(100 * 2 ** retry);
+  }
+}
+function parseUploads(payload, files) {
+  const versionId = payload.versionId;
+  if (!Number.isSafeInteger(versionId) || versionId <= 0 || !Array.isArray(payload.uploads)) {
+    throw new CliError(1, "The portal returned an invalid version response.");
+  }
+  const byPath = /* @__PURE__ */ new Map();
+  for (const raw of payload.uploads) {
+    const target = object(raw);
+    if (typeof target?.path !== "string" || typeof target.url !== "string" || target.method !== "PUT") {
+      throw new CliError(1, "The portal returned an invalid upload target.");
+    }
+    if (byPath.has(target.path)) throw new CliError(1, `The portal returned ${target.path} more than once.`);
+    byPath.set(target.path, { path: target.path, url: target.url, method: "PUT" });
+  }
+  const targets = files.map((file) => {
+    const target = byPath.get(file.path);
+    if (target === void 0) throw new CliError(1, `The portal did not return an upload URL for ${file.path}.`);
+    return target;
+  });
+  if (byPath.size !== files.length) throw new CliError(1, "The portal returned an upload URL for an unknown file.");
+  return {
+    versionId,
+    n: Number.isSafeInteger(payload.n) ? payload.n : null,
+    targets
+  };
+}
+async function readManifest(root) {
+  const path = join(root, "caisual.json");
+  let source;
+  try {
+    source = await fs.readFile(path, "utf8");
+  } catch {
+    throw new CliError(2, "caisual.json: file not found or unreadable.");
+  }
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new CliError(2, "caisual.json: must contain valid JSON.");
+  }
+  const result = validaManifest(value);
+  if (!result.ok) {
+    throw new CliError(2, `caisual.json is not valid:
+${result.errori.map((error) => `- ${error}`).join("\n")}`);
+  }
+  return result.manifest;
+}
+async function publish(folderArgument) {
+  const root = resolve(process.cwd(), folderArgument);
+  let rootStat;
+  try {
+    rootStat = await fs.stat(root);
+  } catch {
+    throw new CliError(2, `The game folder was not found: ${root}`);
+  }
+  if (!rootStat.isDirectory()) throw new CliError(2, `The game path is not a folder: ${root}`);
+  if (await exists(join(root, "server.js"))) throw new CliError(2, SERVER_MESSAGE);
+  const manifest = await readManifest(root);
+  const files = await listClientFiles(join(root, "client"));
+  const filePaths = new Set(files.map((file) => file.path));
+  for (const required of [manifest.cover, ...manifest.screenshots]) {
+    if (required !== null && !filePaths.has(required)) {
+      throw new CliError(2, `caisual.json: referenced file not found in client/: ${required}`);
+    }
+  }
+  const key = process.env.CAISUAL_KEY?.trim();
+  if (!key) {
+    throw new CliError(3, "CAISUAL_KEY is required. Set it with: export CAISUAL_KEY=ck_...");
+  }
+  const origin = portalOrigin();
+  const declared = files.map(({ path, bytes, sha256: digest }) => ({
+    path,
+    bytes,
+    sha256: digest
+  }));
+  process.stdout.write(`Preparing ${files.length} file${files.length === 1 ? "" : "s"}.
+`);
+  const opened = await requestJson(`${origin}/api/versions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${key}`,
+      "Content-Type": "application/json; charset=utf-8"
+    },
+    body: JSON.stringify({ manifest, files: declared })
+  });
+  const version = parseUploads(opened, files);
+  await mapLimited(files, UPLOAD_CONCURRENCY, async (file, index) => {
+    await uploadFile(file, version.targets[index], key, origin);
+  });
+  const completed = await requestJson(`${origin}/api/versions/${version.versionId}/complete`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${key}` }
+  });
+  if (typeof completed.url !== "string") {
+    throw new CliError(1, "The portal completed the version without returning the game URL.");
+  }
+  if (version.n !== null) process.stdout.write(`Published version ${version.n}.
+`);
+  process.stdout.write(`${completed.url}
+`);
+}
+async function installSkill() {
+  const root = process.cwd();
+  const skillPath = join(root, ".claude", "skills", "caisual", "SKILL.md");
+  const skill = `---
+name: caisual
+description: Create and publish a browser game on Caisual.
+---
+
+${publish_default.trim()}
+`;
+  await fs.mkdir(join(root, ".claude", "skills", "caisual"), { recursive: true });
+  let currentSkill = null;
+  try {
+    currentSkill = await fs.readFile(skillPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (currentSkill !== skill) await fs.writeFile(skillPath, skill, "utf8");
+  const agentsPath = join(root, "AGENTS.md");
+  let agents = "";
+  try {
+    agents = await fs.readFile(agentsPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (!/^## Caisual\s*$/m.test(agents)) {
+    const section = "## Caisual\nRead `.claude/skills/caisual/SKILL.md` before creating or publishing a Caisual game.\nUse the current guide at https://caisual.com/publish.md.\n";
+    const separator = agents === "" ? "" : agents.endsWith("\n\n") ? "" : agents.endsWith("\n") ? "\n" : "\n\n";
+    await fs.writeFile(agentsPath, `${agents}${separator}${section}`, "utf8");
+  }
+  process.stdout.write(`Installed ${skillPath}
+`);
+}
+async function run(argumentsList) {
+  const [command, ...argumentsAfterCommand] = argumentsList;
+  if (command === void 0 || command === "--help" || command === "-h" || command === "help") {
+    process.stdout.write(help());
+    return;
+  }
+  if (command === "--version" || command === "-V") {
+    process.stdout.write(`${"0.1.0"}
+`);
+    return;
+  }
+  if (command === "init") {
+    if (argumentsAfterCommand.length > 1) throw new CliError(1, "Usage: caisual init [folder]");
+    await init(argumentsAfterCommand[0] ?? ".");
+    return;
+  }
+  if (command === "publish") {
+    if (argumentsAfterCommand.length > 1) throw new CliError(1, "Usage: caisual publish [folder]");
+    await publish(argumentsAfterCommand[0] ?? ".");
+    return;
+  }
+  if (command === "skill") {
+    if (argumentsAfterCommand.length > 0) throw new CliError(1, "Usage: caisual skill");
+    await installSkill();
+    return;
+  }
+  throw new CliError(1, `Unknown command: ${command}
+
+${help()}`);
+}
+try {
+  await run(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof ApiError) {
+    process.stderr.write(`${error.message}
+`);
+    for (const hint of error.hints) process.stderr.write(`Hint: ${hint}
+`);
+    process.exitCode = error.status === 401 ? 3 : 1;
+  } else if (error instanceof CliError) {
+    process.stderr.write(`${error.message}
+`);
+    process.exitCode = error.exitCode;
+  } else {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${detail}
+`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@caisual/cli",
+  "version": "0.1.0",
+  "description": "Create and publish browser games on Caisual",
+  "type": "module",
+  "bin": {
+    "caisual": "dist/caisual.mjs"
+  },
+  "files": [
+    "dist/caisual.mjs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@caisual/contracts": "workspace:*",
+    "@types/node": "^26.2.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.2"
+  }
+}