@onceworlds/cli 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @onceworlds/cli
+
+Publishes browser games to [Onceworlds](https://onceworlds.com), where every game
+gets multiplayer, saves, player accounts and a shared overlay (sound, chat,
+players) with no server code.
+
+## Deploy from GitHub Actions
+
+Add `.github/workflows/deploy.yml` to your game's repo:
+
+```yaml
+name: Deploy to Onceworlds
+on:
+  push:
+permissions:
+  contents: read
+  id-token: write # proves which repo is deploying; no API keys needed
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+      - run: npx --yes @onceworlds/cli@latest deploy
+```
+
+Pushes to `main` go live at `onceworlds.com/play/<slug>`; other branches get a
+preview URL in the job log. Sign in at https://onceworlds.com with the GitHub
+account that owns the repo (or any member of its organization) before the first
+deploy.
+
+## Project file
+
+`onceworlds.json` at the root of the repo:
+
+```json
+{ "slug": "star-party", "name": "Star Party", "description": "Grab stars with everyone online.", "dir": "." }
+```
+
+`dir` is the folder to publish (for example `dist` after a build); it must contain
+`index.html`. `productionBranch` (default `main`) picks the branch that goes live.
+
+## Commands
+
+- `onceworlds deploy [dir]` uploads only the files that changed and publishes the game.
+- `onceworlds dev [dir]` deploys to a local Onceworlds platform and redeploys on every save.
+
+Games talk to the platform through the injected `window.onceworlds` SDK. The
+starter template's `AGENTS.md` documents it for AI coding tools.

package/dist/cli.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { watch } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+
+// ../protocol/src/index.ts
+var OIDC_AUDIENCE = "onceworlds";
+var LIMITS = {
+  roomMaxPlayersDefault: 16,
+  roomMaxPlayersCap: 50,
+  publicServersPerGame: 20,
+  messageBytes: 16 * 1024,
+  presenceBytes: 1024,
+  stateKeyLength: 64,
+  stateValueBytes: 16 * 1024,
+  stateKeys: 256,
+  messagesPerSecond: 60,
+  presenceHz: 20,
+  chatLength: 200,
+  chatIntervalMs: 750,
+  chatHistory: 50,
+  saveValueBytes: 64 * 1024,
+  saveKeysPerGame: 100,
+  deployFiles: 2e3,
+  deployFileBytes: 25 * 1024 * 1024,
+  deployTotalBytes: 100 * 1024 * 1024,
+  envVars: 50,
+  envValueBytes: 4 * 1024,
+  proxyRequestBytes: 1024 * 1024,
+  proxyResponseBytes: 10 * 1024 * 1024,
+  proxyCallsPerDay: 2e3,
+  errorReportsPerPage: 10
+};
+var CONTENT_TYPES = {
+  html: "text/html; charset=utf-8",
+  htm: "text/html; charset=utf-8",
+  js: "text/javascript; charset=utf-8",
+  mjs: "text/javascript; charset=utf-8",
+  css: "text/css; charset=utf-8",
+  json: "application/json; charset=utf-8",
+  map: "application/json; charset=utf-8",
+  webmanifest: "application/manifest+json",
+  txt: "text/plain; charset=utf-8",
+  csv: "text/csv; charset=utf-8",
+  xml: "application/xml",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  bmp: "image/bmp",
+  ico: "image/x-icon",
+  ktx2: "image/ktx2",
+  basis: "application/octet-stream",
+  hdr: "application/octet-stream",
+  mp3: "audio/mpeg",
+  ogg: "audio/ogg",
+  oga: "audio/ogg",
+  opus: "audio/ogg",
+  wav: "audio/wav",
+  m4a: "audio/mp4",
+  flac: "audio/flac",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  glb: "model/gltf-binary",
+  gltf: "model/gltf+json",
+  bin: "application/octet-stream",
+  obj: "text/plain; charset=utf-8",
+  mtl: "text/plain; charset=utf-8",
+  fbx: "application/octet-stream",
+  wasm: "application/wasm",
+  pck: "application/octet-stream",
+  data: "application/octet-stream",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  fnt: "text/plain; charset=utf-8",
+  atlas: "text/plain; charset=utf-8",
+  tmx: "application/xml",
+  ldtk: "application/json"
+};
+function extensionOf(path) {
+  const dot = path.lastIndexOf(".");
+  return dot > path.lastIndexOf("/") ? path.slice(dot + 1).toLowerCase() : "";
+}
+function contentTypeFor(path) {
+  return CONTENT_TYPES[extensionOf(path)];
+}
+function isValidDeployPath(path) {
+  if (path.length === 0 || path.length > 512) return false;
+  if (path.startsWith("/") || path.includes("\\")) return false;
+  if (/[\u0000-\u001f\u007f]/.test(path)) return false;
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === "." || segment === "..") return false;
+  }
+  return contentTypeFor(path) !== void 0;
+}
+var SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+var RESERVED_SLUGS = /* @__PURE__ */ new Set(["www", "api", "play", "admin", "static", "assets", "docs", "status"]);
+function isValidSlug(slug) {
+  return SLUG_RE.test(slug) && !slug.includes("--") && !RESERVED_SLUGS.has(slug);
+}
+
+// src/index.ts
+var PRODUCTION_API = "https://onceworlds.com";
+var LOCAL_API = "http://localhost:8787";
+var USAGE = `Usage:
+  onceworlds deploy [project-dir]   Upload the game and publish it (to ${PRODUCTION_API})
+  onceworlds dev [project-dir]      Deploy to a local platform (${LOCAL_API}), then redeploy on every change
+
+Options:
+  --api <url>     Platform URL (default: $ONCEWORLDS_API, else the ones above)
+  --token <t>     Deploy token (default: $ONCEWORLDS_TOKEN, GitHub Actions OIDC, or "dev" on localhost)
+
+The project directory needs an onceworlds.json:
+  { "slug": "star-party", "name": "Star Party", "dir": "." }
+`;
+var CliError = class extends Error {
+};
+var QUIET_SKIPS = /* @__PURE__ */ new Set(["node_modules", "onceworlds.json", "package.json", "package-lock.json", "tsconfig.json", "jsconfig.json", "LICENSE"]);
+var QUIET_EXTENSIONS = /* @__PURE__ */ new Set(["md", "ts", "tsx", "jsx", "lock", "log", "yml", "yaml", "sh"]);
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: { api: { type: "string" }, token: { type: "string" }, help: { type: "boolean", short: "h" } }
+  });
+  const [command, projectArg] = positionals;
+  if (values.help || !command || command === "help") {
+    console.log(USAGE);
+    return;
+  }
+  const projectDir = resolve(projectArg ?? ".");
+  const api = (values.api ?? process.env.ONCEWORLDS_API ?? (command === "dev" ? LOCAL_API : PRODUCTION_API)).replace(/\/+$/, "");
+  if (command === "deploy") {
+    await deploy(projectDir, api, values.token);
+  } else if (command === "dev") {
+    await dev(projectDir, api, values.token);
+  } else {
+    throw new CliError(`Unknown command "${command}".
+
+${USAGE}`);
+  }
+}
+async function deploy(projectDir, api, tokenArg, quiet = false) {
+  const config = await loadConfig(projectDir);
+  const root = resolve(projectDir, config.dir ?? ".");
+  const files = await collectFiles(root, quiet);
+  if (!files.some((f) => f.path === "index.html")) {
+    throw new CliError(`No index.html in ${root}. Set "dir" in onceworlds.json to the folder that contains it.`);
+  }
+  const total = files.reduce((sum, f) => sum + f.size, 0);
+  if (total > LIMITS.deployTotalBytes) throw new CliError(`Game is ${formatBytes(total)}; the limit is ${formatBytes(LIMITS.deployTotalBytes)}.`);
+  if (!quiet) console.log(`Deploying ${config.slug} (${files.length} files, ${formatBytes(total)}) to ${api}`);
+  const token = await getToken(api, tokenArg);
+  const start = await send("POST", `${api}/api/deploy`, token, {
+    config: {
+      slug: config.slug,
+      name: config.name,
+      description: config.description ?? "",
+      productionBranch: config.productionBranch ?? "main"
+    },
+    files: files.map(({ path, hash, size }) => ({ path, hash, size })),
+    git: gitInfo(projectDir)
+  });
+  const byHash = new Map(files.map((f) => [f.hash, f]));
+  const uploads = start.missing.map((hash) => byHash.get(hash));
+  if (uploads.length > 0 && !quiet) {
+    console.log(`  \u2191 uploading ${uploads.length} changed file(s), ${formatBytes(uploads.reduce((s, f) => s + f.size, 0))}`);
+  }
+  await runPool(uploads, 6, async (file) => {
+    const body = await readFile(file.abs);
+    await send("PUT", `${api}/api/deploy/${start.deploymentId}/blobs/${file.hash}`, start.uploadToken, body);
+  });
+  const result = await send("POST", `${api}/api/deploy/${start.deploymentId}/finalize`, start.uploadToken, {});
+  if (!quiet) {
+    if (result.production) console.log(`\u2713 Live: ${result.playUrl}`);
+    else console.log(`\u2713 Preview (this branch isn't ${config.productionBranch ?? "main"}): ${result.previewUrl}`);
+  }
+  return result;
+}
+async function dev(projectDir, api, tokenArg) {
+  const config = await loadConfig(projectDir);
+  const root = resolve(projectDir, config.dir ?? ".");
+  const first = await deploy(projectDir, api, tokenArg);
+  console.log(`
+  Play (reloads on every change): ${first.playUrl}?watch
+  Watching ${root}. Press Ctrl+C to stop.
+`);
+  let lastSignature = signature(await collectFiles(root, true));
+  let timer;
+  let running = false;
+  let again = false;
+  const run = async () => {
+    if (running) {
+      again = true;
+      return;
+    }
+    running = true;
+    try {
+      const current = signature(await collectFiles(root, true));
+      if (current !== lastSignature) {
+        await deploy(projectDir, api, tokenArg, true);
+        lastSignature = current;
+        console.log(`  \u21BB ${(/* @__PURE__ */ new Date()).toLocaleTimeString()} redeployed`);
+      }
+    } catch (err) {
+      console.error(`  \u2717 ${err instanceof Error ? err.message : err}`);
+    } finally {
+      running = false;
+      if (again) {
+        again = false;
+        trigger();
+      }
+    }
+  };
+  const trigger = () => {
+    clearTimeout(timer);
+    timer = setTimeout(run, 250);
+  };
+  watch(root, { recursive: true }, (_event, filename) => {
+    if (filename && filename.split(sep).some((part) => part.startsWith(".") || part === "node_modules")) return;
+    trigger();
+  });
+  await new Promise(() => {
+  });
+}
+async function loadConfig(projectDir) {
+  const file = join(projectDir, "onceworlds.json");
+  let config;
+  try {
+    config = JSON.parse(await readFile(file, "utf8"));
+  } catch (err) {
+    const missing = err.code === "ENOENT";
+    throw new CliError(missing ? `No onceworlds.json in ${projectDir}.
+
+${USAGE}` : `Could not parse ${file}: ${err.message}`);
+  }
+  if (!isValidSlug(config.slug ?? "")) {
+    throw new CliError(`"slug" in onceworlds.json must be 1-40 lowercase letters, digits or single dashes (got ${JSON.stringify(config.slug)}).`);
+  }
+  if (typeof config.name !== "string" || !config.name.trim()) throw new CliError('"name" is required in onceworlds.json.');
+  return config;
+}
+async function collectFiles(root, quiet) {
+  const files = [];
+  const skipped = [];
+  async function walk(dir, prefix) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      throw new CliError(`Cannot read ${dir}. Check "dir" in onceworlds.json.`);
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith(".") || QUIET_SKIPS.has(entry.name)) continue;
+      const abs = join(dir, entry.name);
+      const path = prefix + entry.name;
+      if (entry.isDirectory()) {
+        await walk(abs, `${path}/`);
+      } else if (entry.isFile()) {
+        if (!isValidDeployPath(path)) {
+          if (!QUIET_EXTENSIONS.has(extensionOf(path))) skipped.push(path);
+          continue;
+        }
+        const data = await readFile(abs);
+        if (data.byteLength > LIMITS.deployFileBytes) {
+          throw new CliError(`${path} is ${formatBytes(data.byteLength)}; files can be at most ${formatBytes(LIMITS.deployFileBytes)}.`);
+        }
+        files.push({ path, abs, hash: createHash("sha256").update(data).digest("hex"), size: data.byteLength });
+      }
+    }
+  }
+  await walk(root, "");
+  if (skipped.length > 0 && !quiet) console.warn(`  ! skipped unsupported files: ${skipped.join(", ")}`);
+  if (files.length > LIMITS.deployFiles) throw new CliError(`Too many files (${files.length}); the limit is ${LIMITS.deployFiles}.`);
+  return files;
+}
+function signature(files) {
+  return files.map((f) => `${f.path}:${f.hash}`).join("\n");
+}
+function gitInfo(cwd) {
+  const run = (args) => {
+    try {
+      return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  return { sha: run(["rev-parse", "HEAD"]), ref: run(["symbolic-ref", "-q", "HEAD"]) };
+}
+async function getToken(api, tokenArg) {
+  if (tokenArg) return tokenArg;
+  if (process.env.ONCEWORLDS_TOKEN) return process.env.ONCEWORLDS_TOKEN;
+  const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  if (requestUrl && requestToken) {
+    const url = new URL(requestUrl);
+    url.searchParams.set("audience", OIDC_AUDIENCE);
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${requestToken}` } });
+    if (!res.ok) throw new CliError(`Could not get a GitHub OIDC token (${res.status}).`);
+    return (await res.json()).value;
+  }
+  const host = new URL(api).hostname;
+  if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost")) return "dev";
+  throw new CliError(
+    "No deploy credentials. In GitHub Actions, add `permissions: id-token: write` to the workflow. Elsewhere, set ONCEWORLDS_TOKEN."
+  );
+}
+async function send(method, url, token, body) {
+  const binary = body instanceof Uint8Array;
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": binary ? "application/octet-stream" : "application/json"
+      },
+      body: binary ? body : JSON.stringify(body)
+    });
+  } catch {
+    throw new CliError(`Could not reach ${new URL(url).origin}. Is the platform running? (npm run dev)`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new CliError(data.message ?? `${method} ${new URL(url).pathname} failed (${res.status})`);
+  return data;
+}
+async function runPool(items, size, task) {
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) await task(items[next++]);
+  };
+  await Promise.all(Array.from({ length: Math.min(size, items.length) }, worker));
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+main().catch((err) => {
+  console.error(err instanceof CliError ? `\u2717 ${err.message}` : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@onceworlds/cli",
+  "version": "0.1.0",
+  "description": "Deploy games to Onceworlds.",
+  "homepage": "https://onceworlds.com",
+  "type": "module",
+  "bin": {
+    "onceworlds": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit -p ."
+  },
+  "devDependencies": {
+    "@onceworlds/protocol": "0.1.0"
+  }
+}