@onceworlds/cli 0.3.0 → 0.5.0

package/README.md

@@ -9,8 +9,9 @@ players) with no server code.
 Deploys run from GitHub Actions: GitHub vouches for the repo, so there are no API
 keys. The easiest setup is to import the repo at https://onceworlds.com/dashboard/new,
 which adds `onceworlds.json` and `.github/workflows/onceworlds.yml` for you (that
-workflow also builds with npm, pnpm, yarn or bun when there's a build script). By
-hand, the minimum is:
+workflow also builds with npm, pnpm, yarn or bun when there's a build script). To write
+the same files into a folder before it is on GitHub, run `npx @onceworlds/cli init` there.
+By hand, the minimum is:
 
 ```yaml
 name: Deploy to Onceworlds
@@ -63,10 +64,11 @@ with the link) or Public (also listed on Onceworlds).
 `index.html`. `productionBranch` (default `main`) picks the branch that goes live;
 the dashboard can change it too, and the file wins again only when this value changes.
 
-`controls` (`[{ "keys": ["W", "A", "S", "D"], "action": "Move" }]`, up to 12) and `help` (up to 400
-characters) fill "How to play" in the platform menu. The rest fills in the game page: `genre`, a square `icon` (at least 128×128),
+`controls` (`[{ "keys": ["W", "A", "S", "D"], "action": "Move" }]`, up to 12) fill "How to play" in the platform
+menu, folded until a player opens it (`help` is still accepted but no longer shown). The rest fills in the game page: `genre`, a square `icon` (at least 128×128),
 16:9 `thumbnails` (at least 480 wide; the first is the cover) and `badges` (`id`,
-`name`, `description` and an optional square `icon`). Images are PNG, JPEG, WebP
+`name`, `description` and an optional square `icon`). A game page holds at most 5
+thumbnails and videos together, and a game at most 50 badges. Images are PNG, JPEG, WebP
 or GIF up to 5 MB, with paths relative to `onceworlds.json`. Live deploys apply
 these fields only when they change, so edits made in the dashboard last until then.
 
@@ -77,6 +79,13 @@ from the running game and commit them under `store/`. `onceworlds doctor` says w
 
 ## Commands
 
+- `onceworlds init [dir]` sets a game folder up, with the files the dashboard's import commits. It writes
+  `onceworlds.json` (the link and name come from `package.json`'s name or the folder's; `dir` is your build's
+  output folder when `package.json` has a build script, else `.` or the folder with your `index.html`),
+  `.github/workflows/onceworlds.yml`, and the guide for AI coding tools as `AGENTS.md` with a `CLAUDE.md` that
+  imports it (next to a `AGENTS.md` of your own it writes `ONCEWORLDS.md` and adds a pointer to yours). It never
+  overwrites a file you have: `--force` replaces only what init writes, never your own `AGENTS.md` or `CLAUDE.md`.
+  Then commit, push, and import the repo at https://onceworlds.com/dashboard/new.
 - `onceworlds deploy [dir]` uploads only the files that changed and publishes the game
   (the workflow runs it). It lists every file it skipped because Onceworlds can't serve it.
 - `onceworlds dev [dir]` deploys to a local Onceworlds platform (for platform development)

package/dist/cli.js

@@ -1,20 +1,65 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } 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 { readdir as readdir3, readFile as readFile3, stat as stat2 } from "node:fs/promises";
+import { join as join4, resolve as resolve2, sep } from "node:path";
 import { parseArgs } from "node:util";
 
+// src/credentials.ts
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+function configFile() {
+  const base = process.env.ONCEWORLDS_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "onceworlds");
+  return join(base, "credentials.json");
+}
+async function readAll() {
+  try {
+    const data = JSON.parse(await readFile(configFile(), "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+var originOf = (api2) => new URL(api2).origin;
+async function readCredential(api2) {
+  const fromEnv = process.env.ONCEWORLDS_TOKEN;
+  if (fromEnv) return { token: fromEnv, username: "" };
+  const found = (await readAll())[originOf(api2)];
+  return found && typeof found.token === "string" && found.token ? found : null;
+}
+async function saveCredential(api2, credential) {
+  const file = configFile();
+  await mkdir(dirname(file), { recursive: true, mode: 448 });
+  const all = await readAll();
+  all[originOf(api2)] = credential;
+  const temp = `${file}.${process.pid}.tmp`;
+  await writeFile(temp, JSON.stringify(all, null, 2), { mode: 384 });
+  await rename(temp, file);
+  await chmod(file, 384).catch(() => {
+  });
+}
+async function removeCredential(api2) {
+  const all = await readAll();
+  if (!(originOf(api2) in all)) return false;
+  delete all[originOf(api2)];
+  const file = configFile();
+  const temp = `${file}.${process.pid}.tmp`;
+  await writeFile(temp, JSON.stringify(all, null, 2), { mode: 384 });
+  await rename(temp, file);
+  return true;
+}
+
 // src/doctor.ts
 var ROOM_MAX_PLAYERS = 30;
 var MINIFIED_LINE = 400;
-var lineOf = (text, index) => text.slice(0, index).split("\n").length;
-function looksMinified(text) {
-  const lines = text.split("\n");
-  return text.length > 2e4 && text.length / lines.length > MINIFIED_LINE;
+var lineOf = (text2, index) => text2.slice(0, index).split("\n").length;
+function looksMinified(text2) {
+  const lines = text2.split("\n");
+  return text2.length > 2e4 && text2.length / lines.length > MINIFIED_LINE;
 }
 function cssIn(file) {
   if (/\.css$/i.test(file.path)) return [{ css: file.text, offset: 0 }];
@@ -74,12 +119,12 @@ function checkListing(config, file = "onceworlds.json") {
     note("listing-icon", `No "icon": the game's card shows a plain colored placeholder. Add a square image (512\xD7512, simple, no words), like "icon": "store/icon.png".`);
   }
   if (!Array.isArray(config.thumbnails) || config.thumbnails.length === 0) {
-    note("listing-thumbnails", 'No "thumbnails": the game page and its card have no cover. Add three or more 16:9 pictures (1280\xD7720) of the game being played; the first is the cover.');
+    note("listing-thumbnails", 'No "thumbnails": the game page and its card have no cover. Add 3-5 16:9 pictures (1280\xD7720) of the game being played; the first is the cover.');
   }
   if (!filled(config.genre)) note("listing-genre", `No "genre": players can't find the game under a Discover genre. Pick one of the genres in AGENTS.md.`);
   const noControls = !Array.isArray(config.controls) || config.controls.length === 0;
-  if (noControls && !filled(config.help)) {
-    note("listing-help", `No "controls" or "help": the menu's How to play is empty. List every key or button the game uses and a line on how to win.`);
+  if (noControls) {
+    note("listing-help", `No "controls": the menu's How to play is empty. List every key or button the game uses.`);
   }
   return found;
 }
@@ -168,6 +213,12 @@ function checkGame(files) {
   return found.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
 }
 
+// src/init.ts
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir as mkdir2, readdir, readFile as readFile2, stat, writeFile as writeFile2 } from "node:fs/promises";
+import { basename, dirname as dirname2, join as join2 } from "node:path";
+
 // ../protocol/src/index.ts
 var OIDC_AUDIENCE = "onceworlds";
 var LIMITS = {
@@ -214,6 +265,11 @@ var LIMITS = {
   idleAfterMs: 3e4,
   /** A running match whose connected players have all been idle this long is over: nobody is playing. */
   idleAbandonMs: 5 * 6e4,
+  /**
+   * Rated matches two accounts on opposite sides may play against each other in one game's ladder per UTC day: past it,
+   * their matches aren't rated, so two accounts that keep getting matched in a quiet game can't farm wins.
+   */
+  rankedPairMatchesPerDay: 5,
   chatLength: 200,
   chatIntervalMs: 750,
   chatHistory: 50,
@@ -234,7 +290,7 @@ var LIMITS = {
   envValueBytes: 4 * 1024,
   /** All of a game's public variables together, as injected into its pages. */
   envTotalBytes: 16 * 1024,
-  /** Proxied request bodies: routes that take a file (audio to transcribe, an image to edit, model inputs on Replicate and fal). */
+  /** Proxied request bodies: routes that take a file (audio to transcribe, an image to edit). */
   proxyRequestBytes: 1024 * 1024,
   /** Proxied JSON bodies for text, embeddings and image generation. */
   proxyTextRequestBytes: 256 * 1024,
@@ -264,7 +320,7 @@ var LIMITS = {
   errorReportsPerPage: 10,
   gameNameLength: 60,
   gameDescriptionLength: 1e3,
-  galleryItems: 10,
+  galleryItems: 5,
   mediaImageBytes: 5 * 1024 * 1024,
   mediaVideoBytes: 30 * 1024 * 1024,
   /** GIFs are served as they are (never resized), so they're small: at most this many bytes and pixels a side. */
@@ -273,7 +329,7 @@ var LIMITS = {
   /** Media an account uploads in the dashboard (or a repo owner's deploys add to game pages) in any 24 hours. */
   mediaUploadsPerDay: 200,
   mediaBytesPerDay: 500 * 1024 * 1024,
-  badgesPerGame: 100,
+  badgesPerGame: 50,
   /** The menu's "How to play": up to this many controls (each with a few keys and a short action), and a few lines of help. */
   controlHints: 12,
   controlHintKeys: 4,
@@ -287,13 +343,27 @@ var LIMITS = {
   gamesPerOwner: 50,
   /** New games per creator in any rolling 24-hour period. Redeploys do not count. */
   gamesCreatedPerCreatorPerDay: 3,
+  /** An account made with just a username (no email, Google or GitHub) can publish a new game by upload once it is this old. */
+  uploadAccountAgeMs: 7 * 24 * 60 * 6e4,
   deploysPerOwnerPerDay: 100,
+  /** Drafts (what a creator's AI tool pushes to try a game out, see cli.ts) in any 24 hours, per account: they're counted apart from deploys. */
+  draftsPerOwnerPerDay: 1e3,
+  /** Drafts kept per game (the newest ones; a published draft becomes an ordinary version). */
+  draftsKeptPerGame: 3,
+  /** Tools a creator has connected to one account (Claude Code, Codex, other computers). */
+  cliTokensPerAccount: 10,
+  /** How long a `onceworlds login` code can be approved on the site. */
+  cliDeviceCodeSeconds: 600,
   /** Finished versions retained per game, including its live version. */
   deploymentsKeptPerGame: 10,
   deployBytesPerOwnerPerDay: 2 * 1024 * 1024 * 1024,
   /** Files listed by all of a repo owner's deploys in any 24 hours (each is a record to keep and clean up). */
   deployEntriesPerOwnerPerDay: 1e5,
   bioLength: 500,
+  /** Settings > Download my data: rows from any one table, the characters of saves, and how often an account may ask. */
+  exportRows: 2e3,
+  exportSaveChars: 4 * 1024 * 1024,
+  exportEveryMs: 60 * 6e4,
   friendsMax: 200,
   /** Requests one player has sent that are still waiting. */
   friendRequestsMax: 100,
@@ -417,10 +487,213 @@ function isValidDeployPath(path) {
 }
 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"]);
+var NEW_GAME_RESERVED_SLUGS = /* @__PURE__ */ new Set([
+  "star-party",
+  "login",
+  "log-in",
+  "logon",
+  "logout",
+  "signin",
+  "sign-in",
+  "signup",
+  "sign-up",
+  "register",
+  "auth",
+  "oauth",
+  "sso",
+  "verify",
+  "verified",
+  "verification",
+  "support",
+  "help",
+  "helpdesk",
+  "contact",
+  "official",
+  "staff",
+  "team",
+  "moderator",
+  "moderators",
+  "mod",
+  "mods",
+  "security",
+  "account",
+  "accounts",
+  "password",
+  "passwords",
+  "reset",
+  "billing",
+  "payment",
+  "payments",
+  "robux",
+  "vbucks",
+  "v-bucks",
+  "nitro",
+  "gift",
+  "gifts",
+  "giftcard",
+  "free",
+  "settings",
+  "dashboard",
+  "discover",
+  "games",
+  "users",
+  "friends",
+  "notifications",
+  "terms",
+  "privacy",
+  "changelog",
+  "create",
+  "guide",
+  "about",
+  "blog",
+  "news",
+  "mail",
+  "email"
+]);
+var NEW_GAME_RESERVED_PREFIXES = ["onceworlds", "admin", "free-"];
+var SLUG_AUTH_WORDS = /* @__PURE__ */ new Set(["login", "logon", "signin", "signon", "signup", "verify", "verification", "password", "passwords", "billing"]);
+var BRANDS = ["onceworlds", "roblox", "robux", "vbucks", "fortnite", "minecraft", "xbox", "playstation", "nintendo"];
+var LOOKALIKES = {
+  "0": "o",
+  "3": "e",
+  "4": "a",
+  "5": "s",
+  "7": "t",
+  "8": "b",
+  "@": "a",
+  "$": "s",
+  "|": "l",
+  "!": "i",
+  "\u0430": "a",
+  "\u0432": "b",
+  "\u0435": "e",
+  "\u043A": "k",
+  "\u043C": "m",
+  "\u043D": "h",
+  "\u043E": "o",
+  "\u0440": "p",
+  "\u0441": "c",
+  "\u0442": "t",
+  "\u0443": "y",
+  "\u0445": "x",
+  "\u0455": "s",
+  "\u0456": "i",
+  "\u0458": "j",
+  "\u04CF": "l",
+  "\u0501": "d",
+  "\u051D": "w",
+  "\u03B1": "a",
+  "\u03B2": "b",
+  "\u03B5": "e",
+  "\u03B9": "i",
+  "\u03BA": "k",
+  "\u03BD": "v",
+  "\u03BF": "o",
+  "\u03C1": "p",
+  "\u03C4": "t",
+  "\u03C5": "u",
+  "\u03C7": "x",
+  "\u03C9": "w"
+};
 function isValidSlug(slug) {
   return SLUG_RE.test(slug) && !slug.includes("--") && !RESERVED_SLUGS.has(slug);
 }
+function isReservedSlug(slug, newGame2 = true) {
+  if (RESERVED_SLUGS.has(slug)) return true;
+  if (!newGame2) return false;
+  if (NEW_GAME_RESERVED_SLUGS.has(slug) || NEW_GAME_RESERVED_PREFIXES.some((prefix) => slug.startsWith(prefix))) return true;
+  if (!SLUG_RE.test(slug)) return false;
+  const parts = slug.split("-");
+  if (parts.some((part, i) => SLUG_AUTH_WORDS.has(part) || SLUG_AUTH_WORDS.has(part + (parts[i + 1] ?? "")))) return true;
+  return hasBrand(slug);
+}
+function foldedWords(text2) {
+  const base = text2.normalize("NFKD").toLowerCase().replace(/[\u0300-\u036f]/g, "");
+  const variants = [];
+  for (const one of ["l", "i"]) {
+    const mapped = [...base].map((c) => c === "1" ? one : LOOKALIKES[c] ?? c);
+    const words = mapped.map((c) => /[a-z]/.test(c) ? c : /[0-9]/.test(c) ? "" : " ").join("").split(" ").filter(Boolean);
+    variants.push(words, words.map((w) => w.replace(/vv/g, "w")));
+  }
+  return variants;
+}
+function hasBrand(text2) {
+  for (const words of foldedWords(text2)) {
+    if (words.some((word) => BRANDS.some((brand) => word.includes(brand)))) return true;
+    for (let i = 0; i < words.length; i++) {
+      let joined = words[i];
+      for (let j = i + 1; j < words.length && joined.length < 16; j++) {
+        joined += words[j];
+        if (BRANDS.includes(joined)) return true;
+      }
+    }
+  }
+  return false;
+}
 var DEFAULT_PRODUCTION_BRANCH = "main";
+function deployWorkflow() {
+  return `name: Deploy to Onceworlds
+
+# Branches only: tags don't deploy.
+on:
+  push:
+    branches: ['**']
+
+# A newer push to the same branch replaces a deploy still running.
+concurrency:
+  group: onceworlds-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write # lets the Onceworlds CLI prove which repo is deploying; no API keys needed
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # The build never needs the repo's GitHub token, so it isn't left in .git/config.
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        if: hashFiles('bun.lock', 'bun.lockb') != ''
+
+      # Only if package.json has a build script, with the package manager its lockfile belongs to.
+      - name: Build
+        run: |
+          if [ ! -f package.json ] || [ "$(npm pkg get scripts.build)" = "{}" ]; then
+            exit 0
+          elif [ -f pnpm-lock.yaml ]; then
+            corepack enable
+            pnpm install --frozen-lockfile
+            pnpm run build
+          elif [ -f yarn.lock ]; then
+            corepack enable
+            yarn install
+            yarn run build
+          elif [ -f bun.lock ] || [ -f bun.lockb ]; then
+            bun install
+            bun run build
+          elif [ -f package-lock.json ]; then
+            npm ci
+            npm run build
+          else
+            npm install
+            npm run build
+          fi
+
+      # Pushes to the production branch (set in the dashboard or onceworlds.json,
+      # default "main") go live; other branches get a preview URL in the job log.
+      - name: Deploy
+        run: npx --yes @onceworlds/cli@0 deploy
+`;
+}
 var BADGE_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
 var GENRES = [
   "Action",
@@ -440,7 +713,7 @@ var GENRES = [
   "Party",
   "Other"
 ];
-var tidy = (text) => text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+var tidy = (text2) => text2.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
 function checkGuide(controls, help) {
   const hints = [];
   if (controls !== void 0 && controls !== null) {
@@ -454,20 +727,20 @@ function checkGuide(controls, help) {
       }
       const cleaned = keys.map((k) => typeof k === "string" ? tidy(k) : "");
       if (cleaned.some((k) => !k || k.length > LIMITS.controlKeyLength)) throw new Error(`${name}.keys are short names (at most ${LIMITS.controlKeyLength} characters), like "Space" or "Left click"`);
-      const text2 = typeof action === "string" ? tidy(action) : "";
-      if (!text2 || text2.length > LIMITS.controlActionLength) throw new Error(`${name}.action is what the keys do, in at most ${LIMITS.controlActionLength} characters`);
-      hints.push({ keys: cleaned, action: text2 });
+      const text3 = typeof action === "string" ? tidy(action) : "";
+      if (!text3 || text3.length > LIMITS.controlActionLength) throw new Error(`${name}.action is what the keys do, in at most ${LIMITS.controlActionLength} characters`);
+      hints.push({ keys: cleaned, action: text3 });
     });
   }
   if (help !== void 0 && help !== null && typeof help !== "string") throw new Error('"help" must be text');
-  const text = typeof help === "string" ? help.replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, " ").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim() : "";
-  if (text.length > LIMITS.helpLength) throw new Error(`"help" can be at most ${LIMITS.helpLength} characters`);
-  return { controls: hints, help: text };
+  const text2 = typeof help === "string" ? help.replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, " ").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim() : "";
+  if (text2.length > LIMITS.helpLength) throw new Error(`"help" can be at most ${LIMITS.helpLength} characters`);
+  return { controls: hints, help: text2 };
 }
 var MAX_IMAGE_SIDE = 4096;
 function imageInfo(bytes) {
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  const ascii = (at, text) => text.split("").every((c, i) => bytes[at + i] === c.charCodeAt(0));
+  const ascii = (at, text2) => text2.split("").every((c, i) => bytes[at + i] === c.charCodeAt(0));
   if (bytes.length >= 24 && bytes[0] === 137 && ascii(1, "PNG\r\n\n") && ascii(12, "IHDR")) {
     return { type: "image/png", width: view.getUint32(16), height: view.getUint32(20) };
   }
@@ -521,11 +794,540 @@ function imageSizeProblem(slot, width, height) {
   return null;
 }
 
+// src/init.ts
+var OUTPUT_DIRS = ["dist", "build", "out", "public", "web", "www", "export"];
+var WORKFLOW_PATH = ".github/workflows/onceworlds.yml";
+async function init(dir, options) {
+  const log = options.log ?? console.log;
+  const { force } = options;
+  const at = (path) => join2(dir, path);
+  const read = (path) => readFile2(at(path), "utf8").catch(() => null);
+  const exists = (path) => stat(at(path)).then(() => true, () => false);
+  const lines = [];
+  let kept = false;
+  const put = async (path, content, label = path) => {
+    try {
+      await mkdir2(dirname2(at(path)), { recursive: true });
+      await writeFile2(at(path), content, { flag: force ? "w" : "wx" });
+      lines.push(`  wrote  ${label}`);
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      lines.push(`  kept   ${path} (it exists already)`);
+      kept = true;
+    }
+  };
+  const append = async (path, existing, line, label) => {
+    await writeFile2(at(path), `${existing.trimEnd()}
+
+${line}
+`);
+    lines.push(`  wrote  ${label}`);
+  };
+  const pkg = await readPackage(dir);
+  const source = typeof pkg?.name === "string" && pkg.name.replace(/^@[^/]+\//, "") || basename(dir);
+  const fromName = slugFrom(source);
+  const slug = fromName ?? `game-${randomBytes(3).toString("hex")}`;
+  const found = await findDir(pkg, exists);
+  const branch = defaultBranch(dir);
+  const config = { slug, name: titleFrom(source), description: "", dir: found.dir, ...branch ? { productionBranch: branch } : {} };
+  await put("onceworlds.json", `${JSON.stringify(config, null, 2)}
+`, `onceworlds.json (link "${slug}", publishing "${found.dir}")`);
+  const present = await findWorkflow(dir);
+  if (present && present !== WORKFLOW_PATH) lines.push(`  kept   ${present} (it already deploys with the Onceworlds CLI)`);
+  else await put(WORKFLOW_PATH, deployWorkflow());
+  const guide = await fetchGuide(options.fetch ?? fetch, options.api, (line) => lines.push(line));
+  const agents = await read("AGENTS.md");
+  const separate = agents !== null && !/^# Onceworlds\b/.test(agents);
+  const guidePath = separate ? "ONCEWORLDS.md" : "AGENTS.md";
+  if (guide !== null) await put(guidePath, guide);
+  if (guide !== null || await exists(guidePath)) {
+    if (separate && !agents.includes("ONCEWORLDS.md")) {
+      await append("AGENTS.md", agents, "## Onceworlds\n\nThis game is published on Onceworlds. Read ONCEWORLDS.md for the platform rules and SDK.", "AGENTS.md (a pointer to ONCEWORLDS.md)");
+    }
+    const claude = await read("CLAUDE.md");
+    if (claude === null) await put("CLAUDE.md", `@${guidePath}
+`);
+    else if (!claude.includes(guidePath)) await append("CLAUDE.md", claude, `@${guidePath}`, `CLAUDE.md (a pointer to ${guidePath})`);
+  }
+  for (const line of lines) log(line);
+  if (fromName === null) log(`  note   "${source}" can't be a game's link, so the link is ${slug}. Change slug in onceworlds.json.`);
+  if (found.note) log(`  note   ${found.note}`);
+  if (kept) log("  note   --force replaces the files init writes. Your own AGENTS.md and CLAUDE.md are never replaced.");
+  log(`
+Next:
+  1. Check onceworlds.json: "slug" is your game's link (onceworlds.com/play/<slug>) and "name" is its title.
+  2. Commit these files and push the repo to GitHub.
+  3. Open ${options.api}/dashboard/new, import the repo, and every push publishes your game.`);
+}
+async function readPackage(dir) {
+  try {
+    const parsed = JSON.parse(await readFile2(join2(dir, "package.json"), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function slugFrom(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+  return isValidSlug(slug) && !isReservedSlug(slug) ? slug : null;
+}
+function titleFrom(name) {
+  const title = name.replace(/[-_.]+/g, " ").trim().replace(/\s+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return (title || "My Game").slice(0, LIMITS.gameNameLength);
+}
+async function findDir(pkg, exists) {
+  if (typeof pkg?.scripts?.build === "string") {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const out = deps.next ? "out" : deps["react-scripts"] || deps["@sveltejs/kit"] ? "build" : "dist";
+    return { dir: out, note: `"dir" is ${out}, where the build script is expected to write the game. Change it in onceworlds.json if yours writes elsewhere.` };
+  }
+  if (await exists("index.html")) return { dir: "." };
+  for (const name of OUTPUT_DIRS) if (await exists(`${name}/index.html`)) return { dir: name };
+  return { dir: ".", note: `No index.html here yet. Set "dir" in onceworlds.json to the folder that has your game's index.html.` };
+}
+function defaultBranch(dir) {
+  const git = (args) => {
+    try {
+      return execFileSync("git", args, { cwd: dir, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
+    } catch {
+      return null;
+    }
+  };
+  return git(["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"])?.replace(/^origin\//, "") ?? git(["symbolic-ref", "-q", "--short", "HEAD"]);
+}
+async function findWorkflow(dir) {
+  const folder = join2(dir, ".github/workflows");
+  const names = await readdir(folder).catch(() => []);
+  for (const name of names.filter((n) => /\.ya?ml$/.test(n)).slice(0, 20)) {
+    if ((await readFile2(join2(folder, name), "utf8").catch(() => "")).includes("@onceworlds/cli")) return `.github/workflows/${name}`;
+  }
+  return null;
+}
+async function fetchGuide(fetcher, api2, warn) {
+  const url = `${api2}/agents.md`;
+  let problem;
+  try {
+    const res = await fetcher(url, { signal: AbortSignal.timeout(1e4) });
+    const text2 = res.ok ? await res.text() : "";
+    if (text2.trim()) return text2;
+    problem = res.ok ? "it is empty" : `${res.status}`;
+  } catch (err) {
+    problem = err instanceof Error ? err.message : String(err);
+  }
+  warn(`  ! Skipped AGENTS.md and CLAUDE.md: could not fetch ${url} (${problem}). Run init again when it works.`);
+  return null;
+}
+
+// src/login.ts
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+async function post(url, body) {
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+  } catch {
+    throw new Error(`Could not reach ${new URL(url).origin}.`);
+  }
+  return { status: res.status, data: await res.json().catch(() => ({})) };
+}
+function openBrowser(url) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+var sleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+async function login(api2) {
+  const started = await post(`${api2}/api/cli/device`, { label: hostname().slice(0, 40) });
+  if (started.status !== 200) throw new Error(String(started.data.message ?? `Login failed (${started.status}).`));
+  const start = started.data;
+  console.log(`
+  Your code:  ${start.userCode}
+
+  Approve it in your browser: ${start.verifyUrl}
+`);
+  openBrowser(start.verifyUrl);
+  console.log("  Waiting for you to approve it\u2026");
+  const deadline = Date.now() + start.expiresIn * 1e3;
+  let interval = Math.max(2, start.interval) * 1e3;
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    const polled = await post(`${api2}/api/cli/token`, { deviceCode: start.deviceCode });
+    if (polled.status === 200) {
+      const done = polled.data;
+      await saveCredential(api2, { token: done.token, username: done.username });
+      console.log(`
+\u2713 Logged in as @${done.username}. Your AI can push drafts now: it can't publish, only you can.`);
+      return;
+    }
+    const error = String(polled.data.error ?? "");
+    if (error === "authorization_pending") continue;
+    if (error === "slow_down") {
+      interval += 2e3;
+      continue;
+    }
+    throw new Error(String(polled.data.message ?? `Login failed (${polled.status}).`));
+  }
+  throw new Error("That code expired. Run onceworlds login again.");
+}
+async function logout(api2) {
+  console.log(await removeCredential(api2) ? "\u2713 Logged out on this computer." : "You were not logged in.");
+}
+
+// src/mcp.ts
+import { mkdir as mkdir3, readdir as readdir2, writeFile as writeFile3 } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { dirname as dirname3, isAbsolute, join as join3, relative, resolve } from "node:path";
+
+// src/zip.ts
+import { inflateRawSync } from "node:zlib";
+var MAX_ENTRIES = 500;
+var MAX_BYTES = 50 * 1024 * 1024;
+function readZip(zip) {
+  let end = -1;
+  for (let i = zip.length - 22; i >= Math.max(0, zip.length - 22 - 65535); i--) {
+    if (zip.readUInt32LE(i) === 101010256) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) throw new Error("Not a zip file.");
+  const count = zip.readUInt16LE(end + 10);
+  let cursor = zip.readUInt32LE(end + 16);
+  if (count > MAX_ENTRIES) throw new Error("The zip has too many files.");
+  const entries = [];
+  let total = 0;
+  for (let n = 0; n < count; n++) {
+    if (zip.readUInt32LE(cursor) !== 33639248) throw new Error("The zip is damaged.");
+    const flags = zip.readUInt16LE(cursor + 8);
+    const method = zip.readUInt16LE(cursor + 10);
+    const compressed = zip.readUInt32LE(cursor + 20);
+    const size = zip.readUInt32LE(cursor + 24);
+    const nameLength = zip.readUInt16LE(cursor + 28);
+    const extraLength = zip.readUInt16LE(cursor + 30);
+    const commentLength = zip.readUInt16LE(cursor + 32);
+    const local = zip.readUInt32LE(cursor + 42);
+    const path = zip.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8");
+    cursor += 46 + nameLength + extraLength + commentLength;
+    if (path.endsWith("/")) continue;
+    if (flags & 1) throw new Error("The zip is encrypted.");
+    total += size;
+    if (total > MAX_BYTES) throw new Error("The zip is too big.");
+    if (zip.readUInt32LE(local) !== 67324752) throw new Error("The zip is damaged.");
+    const start = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+    const body = zip.subarray(start, start + compressed);
+    let data;
+    if (method === 0) data = Buffer.from(body);
+    else if (method === 8) data = inflateRawSync(body, { maxOutputLength: MAX_BYTES });
+    else throw new Error(`The zip uses a compression method (${method}) this tool can't read.`);
+    if (data.length !== size) throw new Error("The zip is damaged.");
+    entries.push({ path, data });
+  }
+  return entries;
+}
+
+// src/mcp.ts
+var INSTRUCTIONS = `Onceworlds hosts browser games with multiplayer, saves and accounts built in. These tools build a game on the user's account as drafts: the user plays every draft on their Create page and publishes it there. You never publish.
+
+How to work:
+1. read_guide once. It is the reference for the platform's SDK (window.onceworlds) and what a multiplayer game must handle (lobby, ready, reloads, a host leaving, phones).
+2. new_game starts a folder from a template (party: rounds with a lobby, the best start for most multiplayer games; starter: a small real-time game). Build the game in that folder: plain HTML, CSS and JavaScript, or a library from a CDN (jsdelivr, cdnjs). Keep onceworlds.json's name and description right.
+3. check, then deploy_preview after every meaningful change. The user sees each push on their Create page within seconds.
+4. game_status shows the errors the user's plays of your latest draft hit. Fix them and push again.
+Not logged in? Ask the user to run \`npx @onceworlds/cli login\` in a terminal and approve the code in their browser.`;
+var TOOLS = [
+  {
+    name: "read_guide",
+    title: "Read the Onceworlds guide",
+    description: 'The platform guide (AGENTS.md): the SDK, multiplayer rooms and matches, what to handle, how to design and ship a game. Read it before building. Pass `section` (part of a heading, like "Matches" or "Secrets") to get only that part.',
+    inputSchema: { type: "object", properties: { section: { type: "string", description: "Part of a heading to return only that section." } }, additionalProperties: false },
+    annotations: { readOnlyHint: true }
+  },
+  {
+    name: "new_game",
+    title: "Start a game from a template",
+    description: "Creates a folder with a working multiplayer game to build on (templates: party, starter) and writes its onceworlds.json. The folder must not exist yet or must be empty. Build the game there, then push drafts with deploy_preview.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "The game's link: 1-40 lowercase letters, digits or single dashes." },
+        name: { type: "string", description: "The game's name." },
+        description: { type: "string", description: "One line for the game page." },
+        template: { type: "string", enum: ["party", "starter"], description: "party (default): lobby and rounds. starter: a small real-time game." },
+        dir: { type: "string", description: "Folder to create (default: ./<slug>)." }
+      },
+      required: ["slug", "name"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "check",
+    title: "Check the game for common mistakes",
+    description: `Looks through the game's files for what games often ship with (no viewport tag, tiny text fields, missing touch controls, localStorage, Date.now() for shared time). Suggestions only; fix the "likely problems".`,
+    inputSchema: { type: "object", properties: { dir: { type: "string", description: "The game folder (default: the current folder)." } }, additionalProperties: false },
+    annotations: { readOnlyHint: true }
+  },
+  {
+    name: "deploy_preview",
+    title: "Push a draft for the user to play",
+    description: "Uploads the game as a draft (only changed files move) and returns where the user plays it. Creates the game on first push. Call it after every meaningful change. A draft is private to the user until they publish it on the site.",
+    inputSchema: { type: "object", properties: { dir: { type: "string", description: "The game folder (default: the current folder)." } }, additionalProperties: false }
+  },
+  {
+    name: "game_status",
+    title: "Latest draft and the errors it hit",
+    description: "The game's newest draft and the uncaught errors the user's plays of it hit (message, file and line, how many times). Look here after the user has played.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "The game's link (default: the one in the folder's onceworlds.json)." },
+        dir: { type: "string", description: "The game folder (default: the current folder)." }
+      },
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true }
+  },
+  {
+    name: "list_games",
+    title: "List the user's games",
+    description: "The games made with these tools on the user's account.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true }
+  }
+];
+var text = (value) => ({ content: [{ type: "text", text: value }] });
+var failure = (value) => ({ content: [{ type: "text", text: value }], isError: true });
+var ToolError = class extends Error {
+};
+var LOGIN_HINT = "Not logged in. Ask the user to run `npx @onceworlds/cli login` in a terminal and approve the code in their browser.";
+async function serveMcp(host) {
+  console.log = (...args) => console.error(...args);
+  const send2 = (message) => process.stdout.write(`${JSON.stringify(message)}
+`);
+  const reader = createInterface({ input: process.stdin });
+  const pending = /* @__PURE__ */ new Set();
+  for await (const line of reader) {
+    if (!line.trim()) continue;
+    const work = (async () => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        send2({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+        return;
+      }
+      for (const one of Array.isArray(message) ? message : [message]) {
+        const reply = await handleMessage(host, one);
+        if (reply) send2(reply);
+      }
+    })().finally(() => pending.delete(work));
+    pending.add(work);
+  }
+  await Promise.all(pending);
+}
+var PROTOCOLS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+async function handleMessage(host, message) {
+  const id = message.id;
+  const method = typeof message.method === "string" ? message.method : "";
+  const params = message.params && typeof message.params === "object" ? message.params : {};
+  if (id === void 0 || id === null) return null;
+  const ok = (result) => ({ jsonrpc: "2.0", id, result });
+  const error = (code, text2) => ({ jsonrpc: "2.0", id, error: { code, message: text2 } });
+  if (method === "initialize") {
+    const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+    return ok({
+      protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[1],
+      capabilities: { tools: {} },
+      serverInfo: { name: "onceworlds", title: "Onceworlds", version: host.version },
+      instructions: INSTRUCTIONS
+    });
+  }
+  if (method === "ping") return ok({});
+  if (method === "tools/list") return ok({ tools: TOOLS });
+  if (method === "tools/call") {
+    const name = typeof params.name === "string" ? params.name : "";
+    if (!TOOLS.some((tool) => tool.name === name)) return error(-32602, `Unknown tool: ${name}`);
+    const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
+    try {
+      return ok(await callTool(host, name, args));
+    } catch (err) {
+      return ok(failure(err instanceof Error ? err.message : String(err)));
+    }
+  }
+  return error(-32601, `Method not found: ${method}`);
+}
+var stringArg = (args, key) => typeof args[key] === "string" && args[key] !== "" ? args[key] : void 0;
+async function callTool(host, name, args) {
+  const dir = resolve(stringArg(args, "dir") ?? ".");
+  switch (name) {
+    case "read_guide":
+      return text(await readGuide(host, stringArg(args, "section")));
+    case "new_game":
+      return text(await newGame(host, args));
+    case "check": {
+      const findings = await host.findings(dir);
+      return text(formatFindings(findings, dir));
+    }
+    case "deploy_preview": {
+      if (!await host.token()) return failure(LOGIN_HINT);
+      const findings = await host.findings(dir).catch(() => []);
+      const result = await host.deploy(dir);
+      const warnings = findings.filter((f) => f.level === "warn");
+      return text(
+        [
+          `Draft pushed. The user plays it here: ${result.createUrl ?? result.previewUrl}`,
+          ...warnings.length ? ["", `${warnings.length} likely problem${warnings.length === 1 ? "" : "s"} found, fix them:`, ...warnings.map((f) => `  ${f.file}:${f.line}  ${f.message}`)] : [],
+          ...result.notes?.length ? ["", ...result.notes] : [],
+          "",
+          "Ask the user to play it. After they have, game_status shows the errors they hit."
+        ].join("\n")
+      );
+    }
+    case "game_status": {
+      const token = await host.token();
+      if (!token) return failure(LOGIN_HINT);
+      const slug = stringArg(args, "slug") ?? await host.slugOf(dir);
+      if (!slug || !isValidSlug(slug)) throw new ToolError("Say which game: pass slug, or run this in the game's folder.");
+      return text(formatStatus(await api(host, token, `/api/cli/games/${slug}`)));
+    }
+    case "list_games": {
+      const token = await host.token();
+      if (!token) return failure(LOGIN_HINT);
+      const data = await api(host, token, "/api/cli/games");
+      return text(data.games.length ? data.games.map((g) => `${g.slug}  ${g.name}  ${g.live ? "live" : "not published"}  ${g.createUrl}`).join("\n") : "No games yet.");
+    }
+  }
+  throw new ToolError(`Unknown tool: ${name}`);
+}
+async function api(host, token, path) {
+  let res;
+  try {
+    res = await fetch(`${host.api}${path}`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } });
+  } catch {
+    throw new ToolError(`Could not reach ${host.api}.`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new ToolError(data.message ?? `${path} failed (${res.status})`);
+  return data;
+}
+async function readGuide(host, section) {
+  let guide;
+  try {
+    const res = await fetch(`${host.api}/agents.md`);
+    if (!res.ok) throw new Error(String(res.status));
+    guide = await res.text();
+  } catch {
+    throw new ToolError(`Could not read the guide from ${host.api}/agents.md.`);
+  }
+  if (!section) return guide;
+  const wanted = section.toLowerCase();
+  const lines = guide.split("\n");
+  const out = [];
+  let level = 0;
+  let inside = false;
+  let fenced = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) fenced = !fenced;
+    const heading = !fenced ? /^(#{1,6})\s+(.*)$/.exec(line) : null;
+    if (heading) {
+      const depth = heading[1].length;
+      if (inside && depth <= level) inside = false;
+      if (!inside && heading[2].toLowerCase().includes(wanted)) {
+        inside = true;
+        level = depth;
+      }
+    }
+    if (inside) out.push(line);
+  }
+  if (out.length === 0) {
+    const headings = lines.filter((l) => /^#{2,3}\s/.test(l)).map((l) => l.replace(/^#+\s+/, ""));
+    throw new ToolError(`No section matches "${section}". Sections: ${headings.join("; ")}`);
+  }
+  return out.join("\n");
+}
+async function newGame(host, args) {
+  const slug = stringArg(args, "slug") ?? "";
+  const name = (stringArg(args, "name") ?? "").trim();
+  const description = (stringArg(args, "description") ?? "").trim().slice(0, 280);
+  const template = stringArg(args, "template") ?? "party";
+  if (!isValidSlug(slug)) throw new ToolError("slug must be 1-40 lowercase letters, digits or single dashes.");
+  if (!name || name.length > LIMITS.gameNameLength) throw new ToolError(`name must be 1-${LIMITS.gameNameLength} characters.`);
+  if (template !== "party" && template !== "starter") throw new ToolError("template is party or starter.");
+  const dir = resolve(stringArg(args, "dir") ?? slug);
+  const existing = await readdir2(dir).catch(() => null);
+  if (existing && existing.length > 0) throw new ToolError(`${dir} already has files. Pick another folder, or build in it directly.`);
+  let zip;
+  try {
+    const res = await fetch(`${host.api}/onceworlds-${template}.zip`);
+    if (!res.ok) throw new Error(String(res.status));
+    zip = Buffer.from(await res.arrayBuffer());
+  } catch {
+    throw new ToolError(`Could not download the ${template} template from ${host.api}.`);
+  }
+  const entries = readZip(zip);
+  const top = entries[0]?.path.split("/")[0] ?? "";
+  const written = [];
+  for (const entry of entries) {
+    const path = entry.path.startsWith(`${top}/`) ? entry.path.slice(top.length + 1) : entry.path;
+    const target = resolve(dir, path);
+    const inside = relative(dir, target);
+    if (!path || inside.startsWith("..") || isAbsolute(inside)) throw new ToolError("The template has an unsafe path.");
+    await mkdir3(dirname3(target), { recursive: true });
+    await writeFile3(target, entry.data);
+    written.push(path);
+  }
+  await writeFile3(join3(dir, "onceworlds.json"), `${JSON.stringify({ slug, name, description, dir: "." }, null, 2)}
+`);
+  return [
+    `Created ${dir} from the ${template} template (${written.join(", ")}, onceworlds.json).`,
+    "",
+    "Next: read the folder's AGENTS.md (or read_guide), build the game, then check and deploy_preview."
+  ].join("\n");
+}
+function formatFindings(findings, dir) {
+  if (findings.length === 0) return `Checked ${dir}. Nothing to suggest.`;
+  const warn = findings.filter((f) => f.level === "warn");
+  return [
+    ...findings.map((f) => `${f.level === "warn" ? "!" : "\xB7"} ${f.file}:${f.line}  ${f.message}`),
+    "",
+    `${warn.length} likely problem${warn.length === 1 ? "" : "s"}, ${findings.length - warn.length} note${findings.length - warn.length === 1 ? "" : "s"}.`
+  ].join("\n");
+}
+function ago(ms) {
+  const seconds = Math.max(0, Math.round((Date.now() - ms) / 1e3));
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)} min ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)} h ago`;
+  return `${Math.floor(seconds / 86400)} d ago`;
+}
+function formatStatus(raw) {
+  const status = raw;
+  const lines = [`${status.name} (${status.slug}): ${status.live ? "published" : "not published yet"}. ${status.createUrl}`];
+  if (!status.draft) lines.push("No draft yet: call deploy_preview.");
+  else lines.push(`Latest draft ${status.draft.id}, pushed ${ago(status.draft.createdAt)}.`);
+  if (status.errors.length === 0) lines.push(status.draft ? "No errors reported from it (the user may not have played it yet)." : "");
+  else lines.push("", "Errors players hit:", ...status.errors.map((e) => `  ${e.message}  (${e.source}${e.count > 1 ? `, ${e.count} times` : ""}, ${ago(e.lastSeen)})`));
+  return lines.filter((line, i, all) => line !== "" || all[i - 1] !== "").join("\n").trim();
+}
+
 // src/index.ts
+var CLI_VERSION = "0.5.0";
 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 login                  Connect this computer to your Onceworlds account (approve a code in your browser)
+  onceworlds logout                 Forget this computer's login
+  onceworlds whoami                 Who you're logged in as
+  onceworlds mcp                    Run as an MCP server, so Claude Code, Codex and other AI tools can build games
+                                    on your account (they push drafts; only you publish, on onceworlds.com/create)
+  onceworlds init [project-dir]     Set a game folder up for Onceworlds: writes onceworlds.json, the GitHub workflow
+                                    that publishes every push, and AGENTS.md and CLAUDE.md for AI coding tools
+  onceworlds deploy [project-dir]   Upload the game (to ${PRODUCTION_API}): from GitHub Actions it goes live; after login
+                                    it is a draft you play and publish on onceworlds.com/create
   onceworlds dev [project-dir]      Deploy to a local platform (${LOCAL_API}), then redeploy on every change
   onceworlds doctor [project-dir]   Look for what games often ship with: no viewport tag, small text fields,
                                     localStorage, dialogs, Date.now() for shared time, keys with no touch
@@ -536,9 +1338,12 @@ Options:
   --token <t>     Local platform's deploy token (default: "dev")
   --players <n>   dev: also print links for players 2 to n, to play a multiplayer game with yourself
   --strict        doctor: exit with an error when it finds a likely bug (not for notes)
+  --force         init: replace onceworlds.json, the workflow and the guide when they exist already
+                  (never your own AGENTS.md or CLAUDE.md)
 
-Deploys to onceworlds.com run from GitHub Actions: the repo's Onceworlds
-workflow runs this on every push, and GitHub vouches for the repo.
+Deploys to onceworlds.com from a repo run from GitHub Actions: the repo's Onceworlds
+workflow runs this on every push, and GitHub vouches for the repo. From your own
+computer, onceworlds login lets you (and your AI tool) push drafts of games on your account.
 
 The project directory needs an onceworlds.json:
   { "slug": "my-game", "name": "My Game", "dir": "." }
@@ -555,6 +1360,7 @@ async function main() {
       token: { type: "string" },
       players: { type: "string" },
       strict: { type: "boolean" },
+      force: { type: "boolean" },
       help: { type: "boolean", short: "h" }
     }
   });
@@ -563,14 +1369,25 @@ async function main() {
     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);
+  const projectDir = resolve2(projectArg ?? ".");
+  const api2 = (values.api ?? process.env.ONCEWORLDS_API ?? (command === "dev" ? LOCAL_API : PRODUCTION_API)).replace(/\/+$/, "");
+  if (command === "login") {
+    await login(api2);
+  } else if (command === "logout") {
+    await logout(api2);
+  } else if (command === "whoami") {
+    await whoami(api2);
+  } else if (command === "mcp") {
+    await serveMcp(mcpHost(api2));
+  } else if (command === "init") {
+    if (!(await stat2(projectDir).catch(() => null))?.isDirectory()) throw new CliError(`${projectDir} isn't a folder.`);
+    await init(projectDir, { api: api2, force: values.force === true });
+  } else if (command === "deploy") {
+    await deploy(projectDir, api2, values.token);
   } else if (command === "dev") {
     const players = Number(values.players ?? 1);
     if (!Number.isInteger(players) || players < 1 || players > 9) throw new CliError("--players is a number from 1 to 9.");
-    await dev(projectDir, api, values.token, players);
+    await dev(projectDir, api2, values.token, players);
   } else if (command === "doctor") {
     await doctor(projectDir, values.strict === true);
   } else {
@@ -579,9 +1396,9 @@ async function main() {
 ${USAGE}`);
   }
 }
-async function deploy(projectDir, api, tokenArg, quiet = false) {
+async function deploy(projectDir, api2, tokenArg, quiet = false, dev2 = false) {
   const config = await loadConfig(projectDir);
-  const root = resolve(projectDir, config.dir ?? ".");
+  const root = resolve2(projectDir, config.dir ?? ".");
   const { files, skipped } = await collectFiles(root);
   if (skipped.length > 0) {
     console.warn(`  ! ${skipped.length} unsupported file${skipped.length === 1 ? "" : "s"} not deployed:`);
@@ -599,9 +1416,9 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
   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)}.`);
   const { store, images } = await loadStore(projectDir, config);
-  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, {
+  if (!quiet) console.log(`Deploying ${config.slug} (${files.length} files, ${formatBytes(total)}) to ${api2}`);
+  const token = await getToken(api2, tokenArg, dev2);
+  const start = await send("POST", `${api2}/api/deploy`, token, {
     config: {
       slug: config.slug,
       name: config.name,
@@ -618,28 +1435,29 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
     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 body = await readFile3(file.abs);
+    await send("PUT", `${api2}/api/deploy/${start.deploymentId}/blobs/${file.hash}`, start.uploadToken, body);
   });
-  const result = await send("POST", `${api}/api/deploy/${start.deploymentId}/finalize`, start.uploadToken, {});
+  const result = await send("POST", `${api2}/api/deploy/${start.deploymentId}/finalize`, start.uploadToken, {});
   if (!quiet) {
     const branch = result.productionBranch ?? start.productionBranch;
-    if (result.production) console.log(`\u2713 Live: ${result.playUrl}`);
+    if (result.draft) console.log(`\u2713 Draft: play it and publish it at ${result.createUrl}`);
+    else if (result.production) console.log(`\u2713 Live: ${result.playUrl}`);
     else console.log(`\u2713 Preview${branch ? ` (only ${branch} goes live)` : ""}: ${result.previewUrl}`);
     for (const note of result.notes ?? []) console.log(`  ${note}`);
   }
   return result;
 }
-async function dev(projectDir, api, tokenArg, players = 1) {
+async function dev(projectDir, api2, tokenArg, players = 1) {
   const config = await loadConfig(projectDir);
-  const root = resolve(projectDir, config.dir ?? ".");
-  const first = await deploy(projectDir, api, tokenArg);
+  const root = resolve2(projectDir, config.dir ?? ".");
+  const first = await deploy(projectDir, api2, tokenArg, false, true);
   console.log(`
   Play (reloads on every change): ${first.playUrl}?watch`);
   for (let n = 2; n <= players; n++) console.log(`  Player ${n}: ${first.playUrl}?player=${n}&watch`);
   console.log(`  Watching ${root}. Press Ctrl+C to stop.
 `);
-  const projectSignature = async () => signature((await collectFiles(root)).files) + await readFile(join(projectDir, "onceworlds.json"), "utf8").catch(() => "");
+  const projectSignature = async () => signature((await collectFiles(root)).files) + await readFile3(join4(projectDir, "onceworlds.json"), "utf8").catch(() => "");
   let lastSignature = await projectSignature();
   let timer;
   let running = false;
@@ -653,7 +1471,7 @@ async function dev(projectDir, api, tokenArg, players = 1) {
     try {
       const current = await projectSignature();
       if (current !== lastSignature) {
-        await deploy(projectDir, api, tokenArg, true);
+        await deploy(projectDir, api2, tokenArg, true, true);
         lastSignature = current;
         console.log(`  \u21BB ${(/* @__PURE__ */ new Date()).toLocaleTimeString()} redeployed`);
       }
@@ -682,13 +1500,13 @@ async function readSources(files) {
   const sources = [];
   for (const file of files) {
     if (!/\.(html?|m?js|css)$/i.test(file.path) || file.size > 15e5) continue;
-    sources.push({ path: file.path, text: await readFile(file.abs, "utf8") });
+    sources.push({ path: file.path, text: await readFile3(file.abs, "utf8") });
   }
   return sources;
 }
 async function doctor(projectDir, strict) {
   const config = await loadConfig(projectDir);
-  const root = resolve(projectDir, config.dir ?? ".");
+  const root = resolve2(projectDir, config.dir ?? ".");
   const { files } = await collectFiles(root);
   const sources = await readSources(files);
   const findings = [...checkGame(sources), ...checkListing(config)];
@@ -704,10 +1522,10 @@ ${warnings} likely problem${warnings === 1 ? "" : "s"}, ${findings.length - warn
   if (strict && warnings > 0) process.exitCode = 1;
 }
 async function loadConfig(projectDir) {
-  const file = join(projectDir, "onceworlds.json");
+  const file = join4(projectDir, "onceworlds.json");
   let config;
   try {
-    config = JSON.parse(await readFile(file, "utf8"));
+    config = JSON.parse(await readFile3(file, "utf8"));
   } catch (err) {
     const missing = err.code === "ENOENT";
     throw new CliError(missing ? `No onceworlds.json in ${projectDir}.
@@ -724,11 +1542,11 @@ async function loadStore(projectDir, config) {
   const images = /* @__PURE__ */ new Map();
   const image = async (value, slot, field) => {
     if (typeof value !== "string" || !value.trim()) throw new CliError(`"${field}" in onceworlds.json must be the path of an image, like "store/icon.png".`);
-    const abs = resolve(projectDir, value);
+    const abs = resolve2(projectDir, value);
     if (!abs.startsWith(projectDir + sep)) throw new CliError(`"${field}" in onceworlds.json (${value}) must be inside the project folder.`);
     let data;
     try {
-      data = await readFile(abs);
+      data = await readFile3(abs);
     } catch {
       throw new CliError(`"${field}" in onceworlds.json: ${value} doesn't exist.`);
     }
@@ -792,13 +1610,13 @@ async function collectFiles(root) {
   async function walk(dir, prefix) {
     let entries;
     try {
-      entries = await readdir(dir, { withFileTypes: true });
+      entries = await readdir3(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 abs = join4(dir, entry.name);
       const path = prefix + entry.name;
       if (entry.isDirectory()) {
         await walk(abs, `${path}/`);
@@ -807,7 +1625,7 @@ async function collectFiles(root) {
           if (!QUIET_EXTENSIONS.has(extensionOf(path))) skipped.push(path);
           continue;
         }
-        const data = await readFile(abs);
+        const data = await readFile3(abs);
         if (data.byteLength > LIMITS.deployFileBytes) {
           throw new CliError(`${path} is ${formatBytes(data.byteLength)}; files can be at most ${formatBytes(LIMITS.deployFileBytes)}.`);
         }
@@ -825,15 +1643,19 @@ function signature(files) {
 function gitInfo(cwd) {
   const run = (args) => {
     try {
-      return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || void 0;
+      return execFileSync2("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) {
+async function getToken(api2, tokenArg, dev2 = false) {
   if (tokenArg) return tokenArg;
+  const local = isLocalApi(api2);
+  if (dev2 && local) return "dev";
+  const stored = await readCredential(api2);
+  if (stored) return stored.token;
   const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
   const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
   if (requestUrl && requestToken) {
@@ -843,12 +1665,38 @@ async function getToken(api, tokenArg) {
     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";
+  if (local) return "dev";
   throw new CliError(
-    "Deploys to Onceworlds run from GitHub Actions: push to GitHub and the repo's Onceworlds workflow deploys (it needs `permissions: id-token: write`)."
+    "Not logged in. Run `onceworlds login` to push drafts of your games, or push to GitHub and let the repo's Onceworlds workflow deploy (it needs `permissions: id-token: write`)."
   );
 }
+function isLocalApi(api2) {
+  const host = new URL(api2).hostname;
+  return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
+}
+async function whoami(api2) {
+  const stored = await readCredential(api2);
+  if (!stored) {
+    console.log(`Not logged in to ${api2}. Run: onceworlds login`);
+    return;
+  }
+  const me = await send("GET", `${api2}/api/cli/me`, stored.token, void 0);
+  console.log(`@${me.username} on ${api2}`);
+}
+function mcpHost(api2) {
+  return {
+    api: api2,
+    version: CLI_VERSION,
+    deploy: (dir) => deploy(dir, api2, void 0),
+    findings: async (dir) => {
+      const config = await loadConfig(dir);
+      const { files } = await collectFiles(resolve2(dir, config.dir ?? "."));
+      return [...checkGame(await readSources(files)), ...checkListing(config)];
+    },
+    slugOf: async (dir) => (await loadConfig(dir).catch(() => null))?.slug ?? null,
+    token: async () => (await readCredential(api2))?.token ?? null
+  };
+}
 async function send(method, url, token, body) {
   const binary = body instanceof Uint8Array;
   let res;
@@ -857,9 +1705,9 @@ async function send(method, url, token, body) {
       method,
       headers: {
         Authorization: `Bearer ${token}`,
-        "Content-Type": binary ? "application/octet-stream" : "application/json"
+        ...body === void 0 ? {} : { "Content-Type": binary ? "application/octet-stream" : "application/json" }
       },
-      body: binary ? body : JSON.stringify(body)
+      body: body === void 0 ? void 0 : binary ? body : JSON.stringify(body)
     });
   } catch {
     throw new CliError(`Could not reach ${new URL(url).origin}. Is the platform running? (npm run dev)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onceworlds/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Deploy games to Onceworlds.",
   "homepage": "https://onceworlds.com",
   "type": "module",