@xgamesfun/xcore 0.1.0 → 0.2.1

package/lib/publish/index.mjs

@@ -1,29 +1,29 @@
-// `xcore publish`: a game to games.fun, at a link anyone can play (games.fun hosts it; the person needs no host of
+// `xcore publish`: a game to xgames.fun, at a link anyone can play (xgames.fun hosts it; the person needs no host of
 // their own). A game brought from anywhere (`xcore adopt`) or made with the kit (@xgamesfun/kit, which passes its own
 // check): the command, the kit's MCP tool and its studio's Publish tab all come here.
 //
 //   1. signed in?           ./client.mjs (xcore login)
 //   2. the files            ./tree.mjs: refuses .env files and links; leaves out evidence/ and hidden files
-//   3. no secrets           ./scan.mjs (games.fun runs the same scan again on its side)
+//   3. no secrets           ./scan.mjs (xgames.fun runs the same scan again on its side)
 //      no reference names   ./names.mjs: a file that names a game this one was made to look or play
 //                           like refuses it (spec.json goes up as a copy without them; the person's records keep them)
 //   4. its backend          backend.json → origins (`xcore backend connect`): the only other sites the game may
-//                           talk to once published; games.fun's play host opens that game's CSP to exactly those
+//                           talk to once published; xgames.fun's play host opens that game's CSP to exactly those
 //   5. its server code      server/ (the gf-server-v1 contract, ../server/contract.mjs): bundled into one file and
 //                           checked (it builds, no code from text, no Node built-in a Worker lacks, no secrets, its
 //                           Durable Objects exported, its size); a problem refuses the publish. Sent only when
-//                           games.fun says it takes server code (GET /api/kit/me → server.contracts has gf-server-v1);
+//                           xgames.fun says it takes server code (GET /api/kit/me → server.contracts has gf-server-v1);
 //                           otherwise the files go up alone, and the person is told. server/ itself is never a
 //                           public file.
 //   6. the checks           ./gate.mjs: a check on these files; a fail publishes a private draft only. A brought game:
 //                           the page check (../check.mjs). A game the kit made: the kit's six gates, its `check`; one
 //                           without it is refused here, never checked by less
-//   7. upload               only the files (and the server bundle) games.fun does not have yet
+//   7. upload               only the files (and the server bundle) xgames.fun does not have yet
 //   8. the version + link   unlisted; an update is the next version at the same link
 // A brought game (gamesfun.json → page, ./page.mjs; `xcore adopt`) is built first when it has a build, and its `out`
 // folder is what goes up (with its server/ bundle, as for any game); the files publish adds live in its `static` folder.
 // Signed in by `xcore login`, or in a GitHub Actions job by the job's own OIDC token (./oidc.mjs; actions/publish).
-// The link is remembered in <game>/.gamesfun/publish.json (public facts only: which games.fun, the game's id, its link),
+// The link is remembered in <game>/.gamesfun/publish.json (public facts only: which xgames.fun, the game's id, its link),
 // so the next publish of this folder updates the same game.
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
@@ -40,16 +40,17 @@ import {
 } from './scan.mjs';
 import { findNames, namesMessage } from './names.mjs';
 import { gate } from './gate.mjs';
-import { call, ownOrigins, studioOrigin } from './client.mjs';
+import { call, ownOrigins, signInState, studioOrigin } from './client.mjs';
 import { shown as shownDir } from '../games.mjs';
-import { publishCredential } from './oidc.mjs';
+import { publishCredential, requireCredential } from './oidc.mjs';
 import { bundleServer } from '../server/bundle.mjs';
-import { publishField, studioAccepts } from '../server/contract.mjs';
+import { CONFIG_FILE, migrationsChanged, publishField, studioAccepts, studioFeatures } from '../server/contract.mjs';
 import { economyFile, installPage, installServerCopy } from '../economy.mjs';
 import { rpcWords, serverRpc, solanaRpc } from '../solana-rpc.mjs';
 import { shadowedPath } from './hosting.mjs';
 import { buildFailure, pageRoots, runBuild } from './page.mjs';
 import { CMD } from '../command.mjs';
+import { stateFolder } from '../state-folder.mjs';
 
 export const linkFile = dir => path.join(dir, '.gamesfun', 'publish.json');
 export async function readLinks(dir) {
@@ -62,13 +63,14 @@ export async function readLinks(dir) {
 async function writeLink(dir, origin, record) {
   const all = await readLinks(dir);
   all[origin] = record;
+  await stateFolder(dir);
   await mkdir(path.dirname(linkFile(dir)), { recursive: true });
   await writeFile(linkFile(dir), JSON.stringify(all, null, 2) + '\n');
 }
 
 const mb = n => `${(n / 1048576).toFixed(1)} MB`;
 const PACKAGE = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
-/** Who checked a game, in the report games.fun keeps with its version: this package, unless the kit says it was. */
+/** Who checked a game, in the report xgames.fun keeps with its version: this package, unless the kit says it was. */
 export const LABEL = `${PACKAGE.name} ${PACKAGE.version}`;
 /** A game the kit made (its record, gf-three.json): its check is the kit's six gates, never this package's page check. */
 export const madeByKit = dir => existsSync(path.join(dir, 'gf-three.json'));
@@ -101,6 +103,41 @@ export class PublishRefusal extends Error {
   }
 }
 
+/**
+ * xgames.fun's refusal of the game's database migrations (STORAGE.md §8.4, §8.10), as words the person can act on:
+ * 409 migration-changed, 409 migration-busy (another publish is applying them), 422 migration-failed (the SQL failed,
+ * or a file was left partly applied: its why says how to undo it), 502 database-unavailable (Cloudflare, not the SQL). Any other answer goes on as it came.
+ */
+async function migrationWords(pending) {
+  try {
+    return await pending;
+  } catch (e) {
+    const a = e.answer ?? {};
+    const name = typeof a.name === 'string' ? a.name : 'a migration';
+    if (e.code === 'migration-changed')
+      throw new PublishRefusal(
+        `Nothing was published: ${name} changed after xgames.fun applied it to the game's database. A migration is never changed once applied: put ${name} back as it was, and make the change in a new migration after the last one.`,
+        { code: e.code, name, status: e.status },
+      );
+    if (e.code === 'database-unavailable')
+      throw new PublishRefusal(
+        "Nothing new went live: xgames.fun could not reach the game's database (Cloudflare did not answer, or was busy). Nothing is wrong with the migrations, and the version before keeps playing: publish again in a minute.",
+        { code: e.code, status: e.status },
+      );
+    if (e.code === 'migration-busy')
+      throw new PublishRefusal(
+        'Nothing was published: another publish of this game is applying its database migrations on xgames.fun right now. Try again in a minute.',
+        { code: e.code, status: e.status },
+      );
+    if (e.code === 'migration-failed')
+      throw new PublishRefusal(
+        `Nothing new went live: ${name} failed on the game's database on xgames.fun${a.why ? ` (${String(a.why).replace(/\.$/, '')})` : ''}. The version before keeps playing. Fix ${name} (try it under ${CMD} dev, which applies the same migrations) and publish again.`,
+        { code: e.code, name, why: a.why ?? null, status: e.status },
+      );
+    throw e;
+  }
+}
+
 /** Step 5, offline: the game's server code as it would go up. → null (no server/) or the bundle's facts. */
 export async function serverCheck(dir) {
   let b;
@@ -152,6 +189,14 @@ export function checkSummary(p) {
           compatibilityFlags: s.compatibilityFlags ?? [],
           files: (s.sources ?? []).map(f => f.path),
           warnings: s.warnings ?? [],
+          stock: !!s.stock,
+          database: s.database?.has
+            ? {
+                binding: s.database.binding,
+                migrations: s.database.migrations.map(m => m.path),
+                ...(s.stock ? { collections: s.database.collections } : {}),
+              }
+            : null,
         }
       : null,
   };
@@ -250,12 +295,9 @@ export async function publishGame(
       { code: 'kit' },
     );
   check ??= pageCheck;
-  const cred = await publishCredential(origin, { env, fetchImpl });
-  if (!cred)
-    throw new PublishRefusal(
-      `Not signed in to games.fun (${origin}). Sign in first: ${CMD} login (in GitHub Actions: permissions id-token: write; see the README's "Publish" section)`,
-      { code: 'login' },
-    );
+  const cred = await requireCredential(origin, { env, fetchImpl }).catch(e => {
+    throw new PublishRefusal(e.message, { code: 'login', state: e.state, next: e.next });
+  });
   if (cred.kind !== 'login') progress(`Signed in as ${cred.label} (GitHub's OIDC token; no key is stored anywhere).`);
   // every call signs with the credential's current token (a GitHub token is asked for again before it runs out)
   const api = async (route, opts = {}) => call(origin, route, { ...opts, ...(await cred.auth()), fetchImpl });
@@ -295,24 +337,54 @@ export async function publishGame(
     });
   if (pre.secrets) throw new PublishRefusal(pre.secrets, { code: 'secrets', hits: pre.hits });
   if (pre.names) throw new PublishRefusal(pre.names, { code: 'names', hits: pre.named });
+  // the page's documents have rules (database.collections) and nobody to answer them: every gf.db call would 404
+  if (pre.server?.docsUnrouted)
+    throw new PublishRefusal(
+      `Nothing was published: ${CONFIG_FILE} → database.collections sets the rules of the page's documents (gf.db, at api/db/), and this game's own server does not route api/db/, so every gf.db call would answer 404. ${CMD} add database writes server/gf-docs.js; route it first thing in your server's fetch: const db = await handleDocs(request, env); if (db) return db; (import { handleDocs } from './gf-docs.js'). Or take "collections" out of ${CONFIG_FILE} if the page does not use gf.db.`,
+      { code: 'db-route' },
+    );
   const takes = pre.server?.has ? studioAccepts(me) : null;
+  const database = pre.server?.database?.has ? pre.server.database : null;
+  if (database) {
+    // a database needs xgames.fun to make one (STORAGE.md §8.1): the game is not published without it
+    if (!takes.ok)
+      throw new PublishRefusal(
+        `Nothing was published: this game has a database (${CONFIG_FILE} → database), which runs on the game's server, and ${takes.why}. Publish it again once it does.`,
+        { code: 'feature', feature: 'server' },
+      );
+    if (!studioFeatures(me).has('d1'))
+      throw new PublishRefusal(
+        `Nothing was published: this game has a database (${CONFIG_FILE} → database), and this xgames.fun does not make databases for games yet (GET /api/kit/me does not list "d1"). Publish it again once it does, or take "database" out of ${CONFIG_FILE} to publish without one.`,
+        { code: 'feature', feature: 'd1' },
+      );
+    // append only: what this folder put on this xgames.fun before still comes first, byte for byte
+    const before = newGame ? [] : ((await readLinks(dir))[origin]?.migrations ?? []);
+    const changed = migrationsChanged(database.migrations, before);
+    if (changed)
+      throw new PublishRefusal(`Nothing was published: ${changed.why}.`, { code: changed.code, name: changed.name });
+  }
+  if (takes?.ok && pre.server.usesFiles && !studioFeatures(me).has('files'))
+    throw new PublishRefusal(
+      `Nothing was published: this game's server uses its project files (env.GF.files), and this xgames.fun does not keep project files yet (GET /api/kit/me does not list "files"). Publish it again once it does.`,
+      { code: 'feature', feature: 'files' },
+    );
   if (takes && !takes.ok)
     progress(
-      `This game has server code (server/), and ${takes.why}: only its files are published now, without its server. Its /api/ calls will not answer until games.fun takes server code; publish again then.`,
+      `This game has server code (server/), and ${takes.why}: only its files are published now, without its server. Its /api/ calls will not answer until xgames.fun takes server code; publish again then.`,
     );
   if (takes?.ok && pre.server.bytes > takes.maxBytes)
-    throw new PublishRefusal(`The server bundle is ${mb(pre.server.bytes)}; games.fun takes ${mb(takes.maxBytes)}.`, {
+    throw new PublishRefusal(`The server bundle is ${mb(pre.server.bytes)}; xgames.fun takes ${mb(takes.maxBytes)}.`, {
       code: 'size',
     });
   for (const w of pre.server?.warnings ?? []) progress(`Server code: ${w}`);
   // a page's Solana calls go to the game's own RPC when its server has one (xcore add rpc: server/rpc.js at api/rpc,
-  // the URL a secret of the server), else to /loot/v1/rpc on the play host, games.fun's shared relay, which counts
+  // the URL a secret of the server), else to /loot/v1/rpc on the play host, xgames.fun's shared relay, which counts
   // every call toward the game's plan
   if (economyFile(roots.out) || (roots.overlay && economyFile(roots.overlay))) {
     const ownRpc = pre.server?.has && existsSync(path.join(dir, 'server', 'rpc.js'));
     if (ownRpc) {
       progress(
-        `Its economy's Solana calls go to the game's own RPC (server/rpc.js, api/rpc) once its server has XSOLANA_RPC_URL: ${CMD} secret set XSOLANA_RPC_URL (once; ${CMD} secret list shows whether it is set). Until then they use games.fun's shared relay.`,
+        `Its economy's Solana calls go to the game's own RPC (server/rpc.js, api/rpc) once its server has XSOLANA_RPC_URL: ${CMD} secret set XSOLANA_RPC_URL (once; ${CMD} secret list shows whether it is set). Until then they use xgames.fun's shared relay.`,
       );
       // the server may call only backend.json's origins: the RPC's must be one
       const local = serverRpc(dir);
@@ -327,7 +399,7 @@ export async function publishGame(
     } else {
       const rpc = solanaRpc(env, rpcFile ? { file: rpcFile } : undefined);
       progress(
-        `Its economy's Solana calls go through games.fun's shared relay once published, and each counts toward the game's plan ($10 a million; on Free's $1 a month, ~140 player-hours of an economy that reads every 5 s). Bring the game's own devnet RPC: ${CMD} add rpc${rpc.shared ? '' : ` (${rpcWords(rpc)} is used on this machine only)`}.`,
+        `Its economy's Solana calls go through xgames.fun's shared relay once published, and each counts toward the game's plan ($10 a million; on Free's $1 a month, ~140 player-hours of an economy that reads every 5 s). Bring the game's own devnet RPC: ${CMD} add rpc${rpc.shared ? '' : ` (${rpcWords(rpc)} is used on this machine only)`}.`,
       );
     }
   }
@@ -394,7 +466,7 @@ export async function publishGame(
     );
   if (!report.pass && !draft)
     progress(
-      `Its checks did not pass (${report.failed.map(c => `${c.n} ${c.name}`).join('; ') || 'the check did not run'}), so it goes up as a private draft: a version in your games.fun Studio, with no public link.`,
+      `Its checks did not pass (${report.failed.map(c => `${c.n} ${c.name}`).join('; ') || 'the check did not run'}), so it goes up as a private draft: a version in your xgames.fun Studio, with no public link.`,
     );
 
   const links = await readLinks(dir),
@@ -408,21 +480,30 @@ export async function publishGame(
   if (server) {
     built.sources.set(server.sha256, { data: Buffer.from(server.code) });
     for (const w of server.wasm ?? []) built.sources.set(w.sha256, { data: Buffer.from(w.bytes) }); // its wasm modules, the same way
+    for (const m of database?.migrations ?? []) built.sources.set(m.sha256, { data: m.data }); // and its migrations
     progress(
-      `With its server code: ${server.sources.length} file${server.sources.length === 1 ? '' : 's'} of server/ as one bundle (${(server.bytes / 1024).toFixed(1)} KB)${server.objects.length ? `, Durable Objects ${server.objects.map(o => o.class).join(', ')}` : ''}.`,
+      server.stock
+        ? `With xcore's stock server (${(server.bytes / 1024).toFixed(1)} KB), which serves the page's api/db/ from the game's database.`
+        : `With its server code: ${server.sources.length} file${server.sources.length === 1 ? '' : 's'} of server/ as one bundle (${(server.bytes / 1024).toFixed(1)} KB)${server.objects.length ? `, Durable Objects ${server.objects.map(o => o.class).join(', ')}` : ''}.`,
     );
+    if (database)
+      progress(
+        `With its database (env.${database.binding}): ${database.migrations.length ? `${database.migrations.length} migration${database.migrations.length === 1 ? '' : 's'} (${database.migrations.map(m => m.name).join(', ')}); xgames.fun applies the new ones before the new version goes live` : 'no migrations'}.`,
+      );
   }
-  const begun = await api('/api/kit/publish', {
-    method: 'POST',
-    body: {
-      title: name,
-      ...(known?.projectId ? { projectId: known.projectId } : {}),
-      tree: built.tree,
-      verify: report,
-      draft: draft === true,
-      ...(server ? { server: publishField(server) } : {}),
-    },
-  });
+  const begun = await migrationWords(
+    api('/api/kit/publish', {
+      method: 'POST',
+      body: {
+        title: name,
+        ...(known?.projectId ? { projectId: known.projectId } : {}),
+        tree: built.tree,
+        verify: report,
+        draft: draft === true,
+        ...(server ? { server: publishField(server) } : {}),
+      },
+    }),
+  );
 
   // the game exists from here on: remember it, so publishing again (after a failure below) updates this game, never
   // making another
@@ -464,19 +545,20 @@ export async function publishGame(
     }
   };
   progress(
-    `Uploading ${begun.missing.length} new file${begun.missing.length === 1 ? '' : 's'} (${mb(begun.newBytes)}); ${alreadyThere} games.fun already has.`,
+    `Uploading ${begun.missing.length} new file${begun.missing.length === 1 ? '' : 's'} (${mb(begun.newBytes)}); ${alreadyThere} xgames.fun already has.`,
   );
   await Promise.all(Array.from({ length: Math.min(4, begun.missing.length) }, worker));
 
   let done;
   try {
-    done = await api(`/api/kit/publish/${begun.id}`, { method: 'POST', body: { action: 'complete' } });
+    done = await migrationWords(api(`/api/kit/publish/${begun.id}`, { method: 'POST', body: { action: 'complete' } }));
   } catch (e) {
-    // games.fun can finish the publish after it stops answering (a large game's last step outlasts the request)
+    if (e instanceof PublishRefusal) throw e;
+    // xgames.fun can finish the publish after it stops answering (a large game's last step outlasts the request)
     if ([502, 503, 504].includes(e.status))
       throw Object.assign(
         new Error(
-          `games.fun did not answer in time (${e.status}) while it finished the publish, which may have gone through anyway. Run \`${CMD} publish ${shownDir(dir)} --status\` before publishing again; publishing again updates this same game, it does not make a new one.`,
+          `xgames.fun did not answer in time (${e.status}) while it finished the publish, which may have gone through anyway. Run \`${CMD} publish ${shownDir(dir)} --status\` before publishing again; publishing again updates this same game, it does not make a new one.`,
         ),
         { status: e.status, code: 'timeout' },
       );
@@ -507,6 +589,8 @@ export async function publishGame(
             bytes: server.bytes,
             sha256: server.sha256,
             objects: server.objects.map(o => o.class),
+            ...(server.stock ? { stock: true } : {}),
+            ...(database ? { database: { binding: database.binding, migrations: database.migrations.length } } : {}),
             ...(done.server ? { games: done.server } : {}),
           }
         : { sent: false, why: takes?.why ?? 'not sent' }
@@ -521,16 +605,46 @@ export async function publishGame(
     gameUrl: result.gameUrl ?? known?.gameUrl ?? null,
     lastVersion: done.version?.number ?? null,
     draft: done.draft,
+    // the migrations xgames.fun applied (a version that went up live has had them applied): the next publish
+    // checks they come first, unchanged
+    ...(database && server
+      ? done.draft
+        ? known?.migrations
+          ? { migrations: known.migrations }
+          : {}
+        : { migrations: database.migrations.map(m => ({ name: m.name, sha256: m.sha256 })) }
+      : known?.migrations
+        ? { migrations: known.migrations }
+        : {}),
     at: new Date().toISOString(),
   });
   return result;
 }
 
-/** The game's remembered link and what games.fun says about it now (`xcore publish --status`). */
+/**
+ * Where a folder's game stands on one xgames.fun, from its remembered link (.gamesfun/publish.json):
+ *   never --publish begins--> started --a version goes up--> public | draft
+ *   public --a version whose checks failed--> draft-over-public (the earlier version stays live) --publish--> public
+ * `started`: xgames.fun made the game but no version finished going up (an interrupted first publish); publishing
+ * again goes on with the same game.
+ */
+export function linkState(known) {
+  if (!known?.projectId) return 'never';
+  if (known.lastVersion == null) return 'started';
+  if (known.draft) return known.url ? 'draft-over-public' : 'draft';
+  return 'public';
+}
+
+/** The game's remembered link and what xgames.fun says about it now (`xcore publish --status`). */
 export async function publishStatus(dir, { origin = studioOrigin(), env = process.env, fetchImpl = fetch } = {}) {
   const links = await readLinks(dir),
     known = links[origin] ?? null;
-  const cred = await publishCredential(origin, { env, fetchImpl }).catch(() => null);
+  let oidcError = null;
+  const cred = await publishCredential(origin, { env, fetchImpl }).catch(e => {
+    oidcError = e.message;
+    return null;
+  });
+  const { token: _token, words: _words, ...signIn } = await signInState(origin, { env });
   let live = null;
   if (known?.projectId && cred) {
     try {
@@ -546,6 +660,14 @@ export async function publishStatus(dir, { origin = studioOrigin(), env = proces
         ? { email: cred.email, expiresAt: cred.expiresAt, store: cred.store }
         : { email: null, via: cred.kind, as: cred.label }
       : null,
+    // the saved sign-in's state ('signed-in' | 'signed-out' | 'expired' | 'unreadable') and what to run next;
+    // `oidcError`: a GitHub Actions job whose OIDC token could not be had
+    signIn: {
+      ...signIn,
+      ...(cred && cred.kind !== 'login' ? { via: cred.kind } : {}),
+      ...(oidcError ? { oidcError } : {}),
+    },
+    link: linkState(known),
     known,
     live,
   };

package/lib/publish/oidc.mjs

@@ -3,14 +3,15 @@
 // A workflow with `permissions: id-token: write` gets two variables from GitHub: ACTIONS_ID_TOKEN_REQUEST_URL and
 // ACTIONS_ID_TOKEN_REQUEST_TOKEN. With them the kit asks GitHub for a short-lived JWT (issuer
 // token.actions.githubusercontent.com, audience https://xgames.fun, the repository and ref as claims) and sends it to
-// games.fun's kit publish routes as `Authorization: Bearer <JWT>` with `x-gamesfun-credential: github-oidc`. games.fun
+// xgames.fun's kit publish routes as `Authorization: Bearer <JWT>` with `x-gamesfun-credential: github-oidc`. xgames.fun
 // checks the issuer, the audience and the repository + branch against the link its owner made once in Studio ("this
 // repo and branch publish this game"), so nothing secret is stored in the repository or in GitHub.
 //
-// Used only when no `xcore login` is saved for that games.fun: a person's own sign-in always wins on their machine.
+// Used only when no `xcore login` is saved for that xgames.fun: a person's own sign-in always wins on their machine.
 // The token lasts a few minutes, so it is asked for again before each call once it is four minutes old (a publish
-// with verify runs longer than one token lives). GAMESFUN_OIDC_AUDIENCE changes the audience (a games.fun of your own).
-import { savedLogin } from './client.mjs';
+// with verify runs longer than one token lives). GAMESFUN_OIDC_AUDIENCE changes the audience (an xgames.fun of your own).
+import { signInState } from './client.mjs';
+import { CMD } from '../command.mjs';
 
 export const OIDC_AUDIENCE = 'https://xgames.fun';
 export const OIDC_HEADER = 'x-gamesfun-credential';
@@ -71,7 +72,10 @@ export function claimsOf(jwt) {
  * { kind: 'login' | 'github-oidc', label, email, auth(): Promise<{ token, headers }> }.
  */
 export async function publishCredential(origin, { env = process.env, fetchImpl = fetch } = {}) {
-  const login = await savedLogin(origin, { env });
+  // only a sign-in that is still good wins: an expired or unreadable one gives way to the job's OIDC token
+  const st = await signInState(origin, { env });
+  const login =
+    st.state === 'signed-in' ? { token: st.token, email: st.email, expiresAt: st.expiresAt, store: st.store } : null;
   if (login)
     return {
       kind: 'login',
@@ -106,3 +110,20 @@ export async function publishCredential(origin, { env = process.env, fetchImpl =
     auth,
   };
 }
+
+/**
+ * The credential, or an Error saying why there is none, in the sign-in state's own words ("ended on …", "cannot be
+ * read in this session"), with the command that fixes it. `.code` is 'login', `.state` the sign-in state.
+ */
+export async function requireCredential(origin, { env = process.env, fetchImpl = fetch } = {}) {
+  const cred = await publishCredential(origin, { env, fetchImpl });
+  if (cred) return cred;
+  const st = await signInState(origin, { env });
+  const state = st.state === 'signed-in' ? 'signed-out' : st.state;
+  throw Object.assign(
+    new Error(
+      `${st.state === 'signed-out' ? `Not signed in to xgames.fun (${origin}).` : st.words} Run: ${CMD} login (in GitHub Actions: permissions id-token: write; see the README's "Publish" section)`,
+    ),
+    { code: 'login', state, next: `${CMD} login` },
+  );
+}

package/lib/publish/page.mjs

@@ -10,7 +10,7 @@
 //            output; index.html at its root is the game's entry
 //   static   the folder the build copies into `out` as it is (Vite, Next.js, Astro: public/), where the kit puts the
 //            files it adds (backend.json, xsolana.json, gf/loot/); "." for plain files; omitted when the build has none
-//   title    optional: the game's name on games.fun (else index.html's <title>, else package.json's name)
+//   title    optional: the game's name on xgames.fun (else index.html's <title>, else package.json's name)
 //
 // Only these four keys; every path is relative, with forward slashes, and stays inside the game's folder.
 import { execFile, spawn } from 'node:child_process';

package/lib/publish/plans.mjs

@@ -1,19 +1,20 @@
-// `xcore plan`'s calls to games.fun. A plan is a game's backend tier: Free by default (strict), or
+// `xcore plan`'s calls to xgames.fun. A plan is a game's backend tier: Free by default (strict), or
 // Creator when its owner puts it in one of their paid game slots (priced per game slot a month; a slot moves between
-// games at any time without changing the bill), or Scale, which games.fun's operator grants.
-//   GET  /api/kit/plan                                  → {ok, slots, used, billing, capCents, monthCents, includedCents, games}
+// games at any time without changing the bill), or Scale, which xgames.fun's operator grants.
+// Every game sits in a slot: 2 free ones for everyone (their games on Free), any more are paid (their games on Creator).
+//   GET  /api/kit/plan                                  → {ok, slots, used, billing, capCents, monthCents, includedCents, games,
+//                                                          gameSlots?: {free: {slots, used}, paid: {slots, used}, granted, open}}
+//                                                          (slots/used: the paid slots; gameSlots: from xgames.fun 2026-11-08)
 //   GET  /api/kit/games/<gameId>/plan                   → {ok, game, tier, capped, comp, limits, monthCents, includedCents, slots, used}
 //   POST /api/kit/games/<gameId>/plan  {"active": bool} → the same, and changed
 // The game is the folder's own (its .gamesfun/publish.json for this Studio); the credential is publish's.
 import { readLinks } from './index.mjs';
 import { call, studioOrigin } from './client.mjs';
-import { publishCredential } from './oidc.mjs';
+import { requireCredential } from './oidc.mjs';
 import { CMD } from '../command.mjs';
 
 async function signedIn(origin, { env, fetchImpl }) {
-  const cred = await publishCredential(origin, { env, fetchImpl });
-  if (!cred) throw new Error(`not signed in to ${origin}: run ${CMD} login first`);
-  return cred.auth();
+  return (await requireCredential(origin, { env, fetchImpl })).auth();
 }
 async function gameId(dir, origin) {
   const known = (await readLinks(dir))[origin];
@@ -53,7 +54,7 @@ export function describeGame(r) {
   const lines = [];
   const name = r.game?.title || r.game?.slug || 'This game';
   lines.push(
-    `${name}: ${tierName(r.tier)}${r.comp ? ' (granted by games.fun)' : ''}${r.capped ? ', capped for the rest of the month' : ''}`,
+    `${name}: ${tierName(r.tier)}${r.comp ? ' (granted by xgames.fun)' : ''}${r.capped ? ', capped for the rest of the month' : ''}`,
   );
   const included = r.includedCents == null ? '' : ` of ${dollars(r.includedCents)} included`;
   lines.push(`  this month: ${dollars(r.monthCents)}${included}`);
@@ -71,7 +72,7 @@ export function describeGame(r) {
     lines.push(
       '  capped: its server answers slowly (60 requests a minute) until the month ends, or until it gets more room',
     );
-  if (r.slots !== undefined) lines.push(`  game slots: ${r.used ?? 0} of ${r.slots} in use`);
+  if (r.slots !== undefined) lines.push(`  paid slots: ${r.used ?? 0} of ${r.slots} in use`);
   return lines.join('\n');
 }
 
@@ -80,12 +81,18 @@ export function describeAccount(r) {
   const open = r.payments?.on || r.billing;
   const until = r.periodEnd ? `, paid through ${new Date(r.periodEnd).toISOString().slice(0, 10)}` : '';
   const how = r.payments?.on
-    ? ` (buy or renew on games.fun: Studio → Plans, in ${(r.payments.currencies ?? ['SOL', 'USDC']).join(' or ')}${r.payments.cluster === 'devnet' ? ', devnet test payments' : ''})`
+    ? ` (buy or renew on xgames.fun: your console → Plans, in ${(r.payments.currencies ?? ['SOL', 'USDC']).join(' or ')}${r.payments.cluster === 'devnet' ? ', devnet test payments' : ''})`
     : open
       ? ''
-      : ' (buying slots is not open on this games.fun yet)';
+      : ' (buying slots is not open on this xgames.fun yet)';
+  const s = r.gameSlots;
   const lines = [
-    `Game slots: ${r.used ?? 0} of ${r.slots ?? 0} in use${until}${how}`,
+    ...(s
+      ? [
+          `Free slots: ${s.free.used} of ${s.free.slots} in use (their games run on Free)${s.open === 0 ? '; a new game needs one: archive a game or move one to a paid slot' : ''}`,
+        ]
+      : []),
+    `${s ? 'Paid slots' : 'Game slots'}: ${r.used ?? 0} of ${r.slots ?? 0} in use${s ? ' (their games run on Creator)' : ''}${until}${how}`,
     `This month: ${dollars(r.monthCents)}${r.includedCents == null ? '' : ` of ${dollars(r.includedCents)} included`}${r.creditCents ? `; usage credit ${dollars(r.creditCents)}` : ''}${r.capCents ? `; spending cap ${dollars(r.capCents)}` : ''}`,
   ];
   for (const g of r.games ?? [])