@xgamesfun/xcore 0.3.0 → 0.4.0

package/lib/dev/files.mjs

@@ -12,11 +12,84 @@ import { createReadStream, existsSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import path from 'node:path';
-import { FILES, filePathProblem, fileType, servedType } from '../server/contract.mjs';
+import { FILES, filePathProblem, servedType } from '../server/contract.mjs';
 import { stateFolder } from '../state-folder.mjs';
 
 const no = (code, why) => ({ ok: false, code, why });
 
+// ---- public files: the types a file may be public as, each known by its first bytes, as xgames.fun checks them ----
+// A public file is media or data a page loads: an image, audio, video, a font, JSON or plain text, whose first bytes
+// are plainly that type. Never a document a browser runs (HTML, SVG, XML, JavaScript, CSS, PDF) nor a download
+// (programs, archives, application/octet-stream): those stay private, and the game's own server serves them.
+const at = (b, offset, sig) => b.length >= offset + sig.length && sig.every((x, i) => b[offset + i] === x);
+const word = (b, offset, text) =>
+  at(
+    b,
+    offset,
+    [...text].map(c => c.charCodeAt(0)),
+  );
+/** The first byte that is not whitespace (after a UTF-8 byte order mark), or -1. */
+function firstVisible(b) {
+  let i = at(b, 0, [0xef, 0xbb, 0xbf]) ? 3 : 0;
+  while (i < b.length && (b[i] === 0x20 || b[i] === 0x09 || b[i] === 0x0a || b[i] === 0x0d)) i++;
+  return i < b.length ? b[i] : -1;
+}
+const riff = (b, kind) => word(b, 0, 'RIFF') && word(b, 8, kind);
+const ftyp = (b, brands = null) => word(b, 4, 'ftyp') && (!brands || brands.some(x => word(b, 8, x)));
+const mpegAudio = b => word(b, 0, 'ID3') || (b[0] === 0xff && (b[1] & 0xe0) === 0xe0);
+const ogg = b => word(b, 0, 'OggS'),
+  webm = b => at(b, 0, [0x1a, 0x45, 0xdf, 0xa3]),
+  wave = b => riff(b, 'WAVE');
+export const PUBLIC_TYPES = Object.freeze({
+  'image/png': b => at(b, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+  'image/jpeg': b => at(b, 0, [0xff, 0xd8, 0xff]),
+  'image/gif': b => word(b, 0, 'GIF87a') || word(b, 0, 'GIF89a'),
+  'image/webp': b => riff(b, 'WEBP'),
+  'image/avif': b => ftyp(b, ['avif', 'avis']),
+  'audio/mpeg': mpegAudio,
+  'audio/ogg': ogg,
+  'video/ogg': ogg,
+  'audio/wav': wave,
+  'audio/wave': wave,
+  'audio/x-wav': wave,
+  'audio/webm': webm,
+  'video/webm': webm,
+  'audio/mp4': b => ftyp(b),
+  'audio/x-m4a': b => ftyp(b),
+  'video/mp4': b => ftyp(b),
+  'audio/aac': b => b[0] === 0xff && (b[1] & 0xf6) === 0xf0,
+  'audio/flac': b => word(b, 0, 'fLaC'),
+  'font/woff': b => word(b, 0, 'wOFF'),
+  'font/woff2': b => word(b, 0, 'wOF2'),
+  'font/ttf': b => at(b, 0, [0, 1, 0, 0]) || word(b, 0, 'true'),
+  'font/otf': b => word(b, 0, 'OTTO'),
+  'font/collection': b => word(b, 0, 'ttcf'),
+  'application/json': b => {
+    const c = firstVisible(b);
+    return c >= 0 && '{["-0123456789tfn'.includes(String.fromCharCode(c));
+  },
+  'text/plain': b => !b.includes(0) && firstVisible(b) !== 0x3c,
+});
+/** How many leading bytes the public check reads. */
+const SNIFF_BYTES = 512;
+const PUBLIC_WORDS =
+  'an image (PNG, JPEG, WebP, GIF, AVIF), audio (MP3, Ogg, WAV, WebM, MP4, AAC, FLAC), video (MP4, WebM, Ogg), a font (WOFF, WOFF2, TTF, OTF), JSON or plain text';
+/** A type's essence: "Image/PNG; x=y" → "image/png". */
+const essenceOf = type =>
+  String(type ?? '')
+    .split(';')[0]
+    .trim()
+    .toLowerCase();
+const MEDIA_TYPE =
+  /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(\s*;\s*[a-z0-9_-]+=("[^"\\]*"|[a-z0-9_.+-]+))*$/i;
+/** The type a put names (lower case), application/octet-stream for none, or null when it is not a media type. */
+const typeOf = type =>
+  type == null || type === ''
+    ? 'application/octet-stream'
+    : typeof type === 'string' && type.length <= 128 && MEDIA_TYPE.test(type)
+      ? type.trim().toLowerCase()
+      : null;
+
 /** One game's files. `origin`: where the public ones are served (a function: the files server's port comes later). */
 export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes, fileBytes = FILES.fileBytes }) {
   const root = path.join(dir, '.gamesfun', 'dev', 'files');
@@ -56,7 +129,10 @@ export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes
 
   return {
     root,
-    /** body: a string, bytes (ArrayBuffer, a typed array, a Buffer). → {ok, path, bytes, url?} */
+    /**
+     * body: a string, bytes (ArrayBuffer, a typed array, a Buffer). `type`: a media type (none: application/octet-stream);
+     * `public`: served on the files origin, for the public types only (PUBLIC_TYPES). → {ok, path, bytes, url?}
+     */
     put(p, body, { type, public: isPublic = false } = {}) {
       return queued(async () => {
         const bad = filePathProblem(p);
@@ -70,6 +146,20 @@ export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes
                 ? Buffer.from(body.buffer, body.byteOffset, body.byteLength)
                 : null;
         if (!bytes) return no('body', 'A file is a string, an ArrayBuffer or a stream of bytes.');
+        const t = typeOf(type);
+        if (t === null) return no('type', 'A file’s type is a media type, like image/png or application/json.');
+        // a public file is media or data the game's page loads, plainly so by its first bytes
+        const shown = isPublic === true;
+        if (shown && !PUBLIC_TYPES[essenceOf(t)])
+          return no(
+            'type',
+            `A public file is ${PUBLIC_WORDS}; this one is ${essenceOf(t)}. Keep it private (public: false) and serve it from the game’s server.`,
+          );
+        if (shown && !PUBLIC_TYPES[essenceOf(t)](bytes.subarray(0, SNIFF_BYTES)))
+          return no(
+            'type',
+            `This file’s first bytes are not ${essenceOf(t)}, so it can’t be public as that. A public file is ${PUBLIC_WORDS}.`,
+          );
         if (bytes.length > fileBytes)
           return no(
             'too-big',
@@ -88,8 +178,10 @@ export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes
         await rename(`${file}.gf-tmp`, file);
         m[p] = {
           bytes: bytes.length,
-          type: typeof type === 'string' && type ? type.slice(0, 200) : fileType(p),
-          public: !!isPublic,
+          type: t,
+          public: shown,
+          // the type its first bytes showed: only a file so marked is served as itself
+          ...(shown ? { checked: essenceOf(t) } : {}),
           updatedAt: Date.now(),
           etag: createHash('sha256').update(bytes).digest('hex').slice(0, 32),
         };
@@ -206,7 +298,12 @@ export function serveFiles(store, { port = 0, host = '127.0.0.1' } = {}) {
     if (filePathProblem(p)) return send(404, { 'content-type': 'text/plain' }, 'No such file.');
     const f = await store.served(p);
     if (!f) return send(404, { 'content-type': 'text/plain' }, 'No such file.');
-    const { type, inline } = servedType(f.meta.type);
+    // as itself only when its first bytes were checked as its type; anything else (a file kept before the check) is a
+    // download
+    const { type, inline } =
+      f.meta.checked && f.meta.checked === essenceOf(f.meta.type)
+        ? servedType(f.meta.type)
+        : { type: 'application/octet-stream', inline: false };
     const etag = `"${f.meta.etag}"`;
     const head = {
       'content-type': type,

package/lib/dev/gf-local.js

@@ -67,6 +67,10 @@ class Scores extends RpcTarget {
   drop(board) {
     return call(this.#env, 'scores.drop', [board]);
   }
+  /** The game's boards (who made each: 'server' or 'page') and rules, as xgames.fun's GF.scores.list answers. */
+  list() {
+    return call(this.#env, 'scores.list', []);
+  }
 }
 class Loot extends RpcTarget {
   #env;

package/lib/dev/index.mjs

@@ -3,7 +3,8 @@
 //   /game/*            the published files (gamesfun.json page.out), with the play host's headers (../check.mjs servePage)
 //   /game/api/*        the game's own server/ under workerd (./server.mjs), WebSockets too, sent on as /api/*; for a
 //                      game with a database and no server/, xcore's stock server, with a local D1 (./d1.mjs)
-//   /platform/v1/*     sign-in, saves and leaderboards (./platform.mjs), the store env.GF reads as well
+//   /platform/v1/*     sign-in, saves and leaderboards (./platform.mjs), the store env.GF reads as well, held to the
+//                      limits of the plan it imitates (./plans.mjs: Free unless `plan` says another)
 //   /platform/v1/live  the game's announcement, config and maintenance, from .gamesfun/live.json (./live.mjs); while
 //                      maintenance is on there, the holding page for its HTML and 503 'maintenance' for its api/
 //                      and platform calls, as xgames.fun's play edge does
@@ -25,6 +26,7 @@ import { PAGE_RPC, rpcWords, solanaRpc } from '../solana-rpc.mjs';
 import { handlePlatform, createPlatformStore } from './platform.mjs';
 import { createLiveRoutes, readLive, LIVE_FILE } from './live.mjs';
 import { createLimitWatch } from './limits.mjs';
+import { devPlan, planLine } from './plans.mjs';
 import { serveFiles } from './files.mjs';
 
 const readJson = file => {
@@ -106,20 +108,27 @@ async function body(req, cap = 256 * 1024) {
   return Buffer.concat(chunks);
 }
 
-/**
- * Start the dev host for `dir`. Options: port (default 8787; 0 any), filesPort (default the next one; 0 any), noBuild,
- * log, env, fetchImpl (the RPC forward's).
- * → {url, origin, files (the public files' origin), rpc, server (the game server's status, or null), store, reload(),
- * close()}
- */
+/** What xcore dev does not imitate, said once when it starts. */
+export const NOT_IMITATED =
+  "platform: not imitated, only said in this log when a page passes them: one player's requests to the game's " +
+  "server a minute and its CPU a request, and one address's reads of /platform/v1; not imitated at all: the " +
+  "network's delays and the owner's moderation (bans, blocked words); a board's player ids are this machine's own";
+
 /** A Host header naming this machine: localhost, 127.0.0.1, [::1] or a name under .localhost, with any port. */
 export const isLocalHost = host =>
   /^(localhost|127\.0\.0\.1|\[::1\]|[a-z0-9-]+\.localhost)(:\d{1,5})?$/i.test(String(host ?? ''));
 
+/**
+ * Start the dev host for `dir`. Options: port (default 8787; 0 any), filesPort (default the next one; 0 any), noBuild,
+ * plan (the plan imitated: 'free', the default, 'creator' or 'scale'), log, env, fetchImpl (the RPC forward's).
+ * → {url, origin, files (the public files' origin), rpc, plan, server (the game server's status, or null), store,
+ * reload(), close()}
+ */
 export async function startDev(
   dir,
   {
     port = 8787,
+    plan: planName = 'free',
     filesPort = port ? port + 1 : 0,
     noBuild = false,
     log = m => console.log(m),
@@ -128,6 +137,7 @@ export async function startDev(
   } = {},
 ) {
   const game = path.resolve(dir);
+  const plan = devPlan(planName);
   const roots = pageRoots(game);
   if (roots.build && !noBuild) {
     log(`build: ${roots.build}`);
@@ -142,7 +152,9 @@ export async function startDev(
       `no index.html in ${path.relative(game, roots.out) || '.'}: ${roots.build ? 'build the game first' : "export the game for the Web there first (or adopt it again with --out <the export's folder>)"}`,
     );
 
-  const store = createPlatformStore({ dir: game, log: m => log(`platform: ${m}`) });
+  const store = createPlatformStore({ dir: game, plan, log: m => log(`platform: ${m}`) });
+  log(planLine(plan));
+  log(NOT_IMITATED);
   // the game's public files on an origin of their own, as <slug>.xgamesusercontent.com is to the published game:
   // another port is another origin (no sign-in, no calls to the game's api/), though the same site here (both are
   // 127.0.0.1); live, xgamesusercontent.com is another site as well
@@ -219,7 +231,7 @@ export async function startDev(
     res.end(text);
   }
 
-  const limits = createLimitWatch({ log });
+  const limits = createLimitWatch({ log, plan });
   const apiAt = `/game${API_PREFIX}`; // the page's api/ beside it: /game/api/
   const live = createLiveRoutes({ dir: game, apiAt, say: problems => log(`live: ${problems.join('; ')}`) });
   const said = await readLive(game);
@@ -239,6 +251,16 @@ export async function startDev(
     }
     if (url.pathname === PAGE_RPC) return (await forwardRpc(req, res), true);
     if (await live.handle(req, res, url)) return true;
+    // the play edge holds one address's reads of /platform/v1 to a number a minute; a board read with no
+    // Authorization header may come from its cache, which is not counted
+    const p = url.pathname;
+    if (
+      (req.method === 'GET' || req.method === 'HEAD') &&
+      p.startsWith('/platform/v1/') &&
+      !p.startsWith('/platform/v1/dev/') &&
+      !(/^\/platform\/v1\/scores\/[^/]+$/.test(p) && !req.headers.authorization)
+    )
+      limits.platformRead(`${req.method} ${p}`);
     if (await handlePlatform(req, res, url, store)) return true;
     if (url.pathname.startsWith(apiAt) || url.pathname === apiAt.slice(0, -1)) {
       const rest = url.pathname.slice('/game'.length) + url.search;
@@ -354,6 +376,7 @@ export async function startDev(
     origin: site.origin,
     files: files.origin,
     rpc: rpcWords(rpc),
+    plan: plan.key,
     server: server ? server.status() : null,
     store,
     reload: () => server?.reload(),

package/lib/dev/limits.mjs

@@ -1,26 +1,39 @@
-// What `xcore dev` says about xgames.fun's plan limits (README §5, `xcore plan`). The local server runs with no CPU or
-// request limits, so a page that polls its server ten times a second works here and is refused once published. This
-// counts the page's requests to its server and times each one, and says so in the dev log, once a minute at most for
-// the rate and once per route for the time. It never refuses anything itself.
+// What `xcore dev` says about xgames.fun's limits that depend on the network, not on the game's store: one player's
+// requests to the game's server a minute and the CPU each may take (by plan), and one address's reads of the page's
+// /platform/v1 at the play edge. The local server runs with no CPU or request limits, and here every tab is the same
+// address, so these are said in the dev log, never refused: once a minute at most for a rate, once per route for the
+// time. The platform's own limits (saves, scores, reads and writes a minute) are refused as published: ./platform.mjs.
 //
-// The numbers are xgames.fun's plans; xgames.fun is the source and can change them.
-export const PLAN_LIMITS = Object.freeze({
-  free: Object.freeze({ name: 'Free', perPlayer: 120, cpuMs: 50 }),
-  creator: Object.freeze({ name: 'Creator', perPlayer: 600, cpuMs: 200 }),
-});
+// The numbers are ./plans.mjs's, one table with the rest.
+import { PLANS, PLAN_NAMES, RULES, devPlan } from './plans.mjs';
+
+/** The plans' request numbers, as this watch reads them (kept for callers of an earlier version). */
+export const PLAN_LIMITS = Object.freeze(
+  Object.fromEntries(
+    PLAN_NAMES.map(k => [
+      k,
+      Object.freeze({ name: PLANS[k].name, perPlayer: PLANS[k].rate.player, cpuMs: PLANS[k].cpuMs }),
+    ]),
+  ),
+);
 const MINUTE = 60_000;
 
 /**
- * A watch over one dev session's server requests. `log(line)` takes what it has to say.
- * → {request(method, pathname) → done(), upgrade(pathname)}: request() before the server is called, done() when it
- *   has answered (its headers).
+ * A watch over one dev session's server requests. `log(line)` takes what it has to say; `plan`: the plan imitated.
+ * → {request(method, pathname) → done(), upgrade(pathname), platformRead(what)}: request() before the server is
+ *   called, done() when it has answered (its headers).
  */
-export function createLimitWatch({ log, now = () => Date.now() }) {
-  const { free, creator } = PLAN_LIMITS;
+export function createLimitWatch({ log, now = () => Date.now(), plan = 'free' }) {
+  const key = typeof plan === 'object' && plan?.key ? plan.key : devPlan(plan).key;
+  const here = PLAN_LIMITS[key];
+  const up = PLAN_LIMITS[PLAN_NAMES[PLAN_NAMES.indexOf(key) + 1]] ?? null;
   let start = now();
   let count = 0;
-  let said = 0; // the highest plan already named this minute: 0 none, 1 Free, 2 Creator
+  let said = 0; // what is already said this minute: 0 nothing, 1 past this plan's, 2 past the next plan's too
   const slow = new Set();
+  let readStart = now(),
+    reads = 0,
+    readSaid = false;
 
   function count1(what) {
     const t = now();
@@ -30,21 +43,21 @@ export function createLimitWatch({ log, now = () => Date.now() }) {
       said = 0;
     }
     count++;
-    if (count > creator.perPlayer && said < 2) {
+    if (up && count > up.perPlayer && said < 2) {
       said = 2;
       log(
         `limits: ${count} requests to the game's server within a minute (the last: ${what}). Published, one player's ` +
-          `requests past ${creator.perPlayer} a minute are refused even on Creator (${free.perPlayer} on Free): its ` +
+          `requests past ${up.perPlayer} a minute are refused even on ${up.name} (${here.perPlayer} on ${here.name}): its ` +
           `server answers 429 with retry-after 60. Send frequent updates (positions, state) over a WebSocket ` +
           `(docs/SERVER.md, "A room over a WebSocket"); a socket is one request for its whole life.`,
       );
-    } else if (count > free.perPlayer && said < 1) {
+    } else if (count > here.perPlayer && said < 1) {
       said = 1;
       log(
         `limits: ${count} requests to the game's server within a minute (the last: ${what}). Published on ` +
-          `${free.name}, one player's requests past ${free.perPlayer} a minute are refused (429, retry-after 60); ` +
-          `${creator.name} allows ${creator.perPlayer}. Poll less often, or send frequent updates over a WebSocket ` +
-          `(docs/SERVER.md). Two tabs here count as one player.`,
+          `${here.name}, one player's requests past ${here.perPlayer} a minute are refused (429, retry-after 60)` +
+          `${up ? `; ${up.name} allows ${up.perPlayer}` : ''}. Poll less often, or send frequent updates over a ` +
+          `WebSocket (docs/SERVER.md). Two tabs here count as one player.`,
       );
     }
   }
@@ -56,11 +69,11 @@ export function createLimitWatch({ log, now = () => Date.now() }) {
       const t0 = now();
       return () => {
         const ms = now() - t0;
-        if (ms <= free.cpuMs || slow.has(what)) return;
+        if (ms <= here.cpuMs || slow.has(what)) return;
         slow.add(what);
         log(
-          `limits: ${what} took ${ms} ms here. Published, a request gets ${free.cpuMs} ms of CPU on ${free.name} ` +
-            `(${creator.cpuMs} on ${creator.name}). Waiting on storage or fetch does not count, but if this is ` +
+          `limits: ${what} took ${ms} ms here. Published, a request gets ${here.cpuMs} ms of CPU on ${here.name}` +
+            `${up ? ` (${up.cpuMs} on ${up.name})` : ''}. Waiting on storage or fetch does not count, but if this is ` +
             `computing, it can pass a few times live and then answer 503 ("went over its limit"). Do less a ` +
             `request, or split the work.`,
         );
@@ -69,5 +82,23 @@ export function createLimitWatch({ log, now = () => Date.now() }) {
     upgrade(pathname) {
       count1(`WebSocket ${pathname}`);
     },
+    /** A read of /platform/v1 that the play edge would count against the address it came from. */
+    platformRead(what) {
+      const t = now(),
+        max = RULES.edge.platformReadsPerCallerMinute;
+      if (t - readStart >= MINUTE) {
+        readStart = t;
+        reads = 0;
+        readSaid = false;
+      }
+      if (++reads <= max || readSaid) return;
+      readSaid = true;
+      log(
+        `limits: ${reads} reads of /platform/v1 within a minute (the last: ${what}). Published, the play edge ` +
+          `refuses one address's reads past ${max} a minute (429 'rate'), on every plan; a board read with no ` +
+          `token may come from its 5 s cache and is not counted. Here every tab shares one address, so this is only ` +
+          `said: read less often (a board after a score, not on a timer).`,
+      );
+    },
   };
 }

package/lib/dev/plans.mjs

@@ -0,0 +1,101 @@
+// The numbers xgames.fun's platform holds a published game to, as `xcore dev` imitates them: one table, so a change
+// on xgames.fun is one edit here. The source is xgames.fun's own plan table, the one its platform enforces (README
+// "Plans and limits"; `xcore plan` shows a published game's own numbers). PLANS changes with the game's plan; RULES
+// are the same on every plan. `xcore dev --plan <name>` picks the plan the dev host imitates (Free by default).
+const deepFreeze = o => {
+  for (const v of Object.values(o)) if (v && typeof v === 'object') deepFreeze(v);
+  return Object.freeze(o);
+};
+const KB = 1024,
+  MB = 1024 * KB,
+  GB = 1024 * MB;
+
+export const PLANS = deepFreeze({
+  free: {
+    name: 'Free',
+    cpuMs: 50,
+    rate: { player: 120 },
+    saves: { valueBytes: 64 * KB, keysPerPlayer: 16, gameBytes: 10 * MB, writesPerMinute: 600 },
+    scores: { boards: 8, rules: 16, entriesPerBoard: 10_000, submitsPerMinute: 600 },
+    reads: { perMinute: 1_200 },
+    files: { bytes: 100 * MB, fileBytes: 25 * MB, opsPerMinute: 120 },
+  },
+  creator: {
+    name: 'Creator',
+    cpuMs: 200,
+    rate: { player: 600 },
+    saves: { valueBytes: 64 * KB, keysPerPlayer: 16, gameBytes: GB, writesPerMinute: 12_000 },
+    scores: { boards: 16, rules: 32, entriesPerBoard: 1_000_000, submitsPerMinute: 6_000 },
+    reads: { perMinute: 12_000 },
+    files: { bytes: 10 * GB, fileBytes: 25 * MB, opsPerMinute: 1_200 },
+  },
+  scale: {
+    name: 'Scale',
+    cpuMs: 1_000,
+    rate: { player: 1_200 },
+    saves: { valueBytes: 64 * KB, keysPerPlayer: 16, gameBytes: 10 * GB, writesPerMinute: 60_000 },
+    scores: { boards: 16, rules: 32, entriesPerBoard: 1_000_000, submitsPerMinute: 30_000 },
+    reads: { perMinute: 60_000 },
+    files: { bytes: 100 * GB, fileBytes: 25 * MB, opsPerMinute: 6_000 },
+  },
+});
+export const PLAN_NAMES = Object.freeze(Object.keys(PLANS));
+export const DEFAULT_PLAN = 'free';
+
+export const RULES = deepFreeze({
+  saves: {
+    playerChars: 128,
+    // a page's writes may keep at most 1/128 of the game's save bytes for one player (never less than one save)
+    playerShareDivisor: 128,
+    // with the game's saves full, a player whose saves stay within 4 KB still writes, up to an eighth past the total
+    floorBytes: 4 * KB,
+    floorPoolDivisor: 8,
+  },
+  scores: { nameChars: 32, perPlayerEveryMs: 1_000, topMax: 100, offsetMax: 10_000, rankMax: 10_000 },
+  // the page's own calls (/platform/v1/*): the same on every plan
+  page: {
+    bodyBytes: 96 * KB,
+    saveWritesPerPlayerMinute: 60,
+    scoreSubmitsPerPlayerMinute: 30,
+    // once pages have spent the game's minute, a player with at most this many this minute still writes
+    saveWritesFloorPerPlayerMinute: 6,
+    scoreSubmitsFloorPerPlayerMinute: 3,
+    // boards a page makes: "high" only, two a player, and half the plan's boards for all pages together
+    boardsPerPlayer: 2,
+    boardsDivisor: 2,
+    // a board read with no good player token: the top 100 only, an identical read within 5 s from a cache, and a
+    // minute of its own, a tenth of the plan's reads
+    anonTopDepth: 100,
+    anonReadsDivisor: 10,
+    anonReadCacheMs: 5_000,
+  },
+  // the play edge's own limit on reads of /platform/v1 from one address (xcore dev only says it: see limits.mjs)
+  edge: { platformReadsPerCallerMinute: 120 },
+  // what GF.files.put holds in memory: a string or ArrayBuffer body, or a stream with no declared length
+  files: { unsizedBytes: MB },
+});
+
+/** The plan `xcore dev` imitates: 'free', 'creator' or 'scale' (any case). → {key, ...PLANS[key]}; throws on another. */
+export function devPlan(name = DEFAULT_PLAN) {
+  const key = String(name ?? DEFAULT_PLAN)
+    .trim()
+    .toLowerCase();
+  if (!Object.hasOwn(PLANS, key)) throw new Error(`there is no plan "${name}": ${PLAN_NAMES.join(', ')}`);
+  return { key, ...PLANS[key] };
+}
+
+const count = n => n.toLocaleString('en-US');
+/** A size in words: 10 MB, 1 GB, 80 KB. */
+export const size = b =>
+  b >= GB ? `${count(b / GB)} GB` : b >= MB ? `${count(b / MB)} MB` : `${count(Math.round(b / KB))} KB`;
+export { count };
+
+/** The dev host's first line about the plan it imitates. */
+export function planLine(plan) {
+  const others = PLAN_NAMES.filter(k => k !== plan.key).join('|');
+  return (
+    `platform: imitating the ${plan.name} plan (--plan ${others} for another): ${plan.scores.boards} boards, ` +
+    `${size(plan.saves.gameBytes)} of saves, ${count(plan.reads.perMinute)} reads and ` +
+    `${count(plan.saves.writesPerMinute)} saves a minute, ${size(plan.files.bytes)} of files`
+  );
+}