@joystack/cli 0.1.43 → 0.1.45

package/CHANGELOG.md

@@ -14,6 +14,34 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.45] - 2026-10-09
+
+### Changed
+
+- `joystack publish` uploads only the files Joystack does not already have,
+  one file per request and several at once, then puts the game live. A large game publishes reliably
+  instead of failing with HTTP 503; a copy under a new name (a review link, a
+  lane's copy) sends only what changed; a publish cut off halfway picks up
+  where it stopped; and a passing failure (a dropped connection, the platform
+  busy, a rate limit) is retried instead of failing the publish.
+- `joystack publish` checks your game's code against its engine before
+  uploading anything: a `/shared/…` path or a `joystack…` import your engine
+  does not have stops the publish with the same message as before, without
+  waiting for the upload.
+
+### Fixed
+
+- A publish that fails no longer leaves its name claimed, or a multiplayer
+  game's server running with no page in front of it.
+
+## [0.1.44] - 2026-10-09
+
+### Added
+
+- When `joystack update` moves a game made before the rename, it ends with a
+  short checklist for your agent: the links, tests and publishing tokens in
+  your game's own files that the update cannot move itself.
+
 ### Removed
 
 - `joystack dev` no longer starts a services proxy on port 8788. Nothing in the
@@ -22,6 +50,9 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- `joystack create` marks the new game as ES modules (`"type": "module"` in
+  package.json), so `joystack publish` no longer prints Node's
+  `MODULE_TYPELESS_PACKAGE_JSON` warning.
 - **The CLI is `@joystack/cli`, and its command is `joystack`** (`npx joystack
   dev`, `npx joystack test`, `npx joystack publish`, …). Nothing in your game has
   to change: the previous command name runs the same CLI, so the scripts in your

package/lib/create.mjs

@@ -112,6 +112,8 @@ async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, rec
       {
         name,
         private: true,
+        // Every file a game is made of is an ES module.
+        type: 'module',
         description: `A Joystack game. Play at https://${name}.joystack.games/`,
         // The scaffold is a framework-v2 game (entities + traits + a world root,
         // lowered to the engine runtime on this machine). This flag is what makes

package/lib/inject.mjs

@@ -34,7 +34,7 @@ function jsJson(value) {
 // resolve them to the framework runtime under the (already-mounted) /shared/
 // tree. This set is the import surface (shared/docs/api.md); keep it in sync
 // with V2_BARE_SPECIFIERS in backend/api/src/lib/inject.js.
-const V2_IMPORTS = {
+export const V2_IMPORTS = {
   joystack: '/shared/framework/runtime/joystack.js',
   'joystack/traits': '/shared/framework/runtime/traits.js',
   'joystack/client': '/shared/framework/runtime/client.js',

package/lib/legacy-names.mjs

@@ -93,6 +93,12 @@ export function canonicalSpecifier(specifier) {
   return specifier;
 }
 
+/**
+ * The engine file the root door resolves to in an engine released before the
+ * rename, which has no `shared/framework/runtime/joystack.js`.
+ */
+export const LEGACY_ROOT_DOOR_FILE = `shared/framework/runtime/${OLD}.js`;
+
 /** A browser import map extended with the old name of every joystack door it maps. */
 export function withLegacyDoors(imports) {
   const out = { ...imports };
@@ -244,3 +250,32 @@ export const LEGACY_MANAGED_MARKERS = Object.freeze({
   start: `<!-- ${OLD}:managed:start -->`,
   end: `<!-- ${OLD}:managed:end -->`,
 });
+
+// Whether this update moved a game made under the old name: the CLI dependency
+// was switched over, or the old update skill was retired. `cli` and `surface`
+// are what update.mjs got from syncCli and the agent-surface reconcile.
+export function movedFromLegacy(cli, surface) {
+  return Boolean(cli?.switched) || (surface?.removed ?? []).some((f) => /(^|\/)skills\/update-looop(\/|$)/.test(f));
+}
+
+// What `joystack update` prints after such a move, once. It is addressed to
+// the creator's agent, which reads the update's output: the update moved what
+// is Joystack's, and these are what the game itself may still say about Looop.
+export const MOVED_FROM_LEGACY_NOTE = [
+  'This game just moved from Looop to Joystack. The update moved what is',
+  "Joystack's; check the game's own files for what it could not move, and",
+  'fix what you find before calling the update done:',
+  '  • Links to play.looop.games/g/<slug>: the game lives at',
+  '    https://<slug>.joystack.games/ from its first `npx joystack publish`.',
+  '    The Looop copy stays as it was.',
+  '  • Tests or scripts matching `[looop]`, `looop:` keys or `.looop/`: the',
+  '    engine now writes `[joystack]`, `joystack:` and `.joystack/`.',
+  '  • Automation that publishes (GitHub Actions, scripts) with a Looop token:',
+  '    Joystack does not accept it. Make one for the job by signing in with an',
+  '    empty folder (mktemp -d) as the home: `JOYSTACK_HOME=<folder> npx joystack login`.',
+  '    With the creator\'s OK, store it without ever displaying it:',
+  '      node -e "process.stdout.write(require(\'<folder>/config.json\').token)" | gh secret set <NAME>',
+  '    Without gh, pipe the same into pbcopy (Mac) and walk them through',
+  '    GitHub → Settings → Secrets and variables → Actions → <NAME> → Update.',
+  '    Then delete the folder.',
+];

package/lib/publish-checks.mjs

@@ -0,0 +1,75 @@
+// The checks of a game's code against its engine, run before a publish uploads
+// anything: every `/shared/…` path the game's code names, and every door it
+// imports (`joystack`, `joystack/client`, `three`, …), must exist in the
+// engine the game is pinned to. Without them the published page fails to load
+// a module.
+//
+// The publish server runs the same checks on the single-request route
+// (backend/api/src/routes/publish.js, codeError). The file-by-file route does
+// not read the game's files back, so the CLI runs them here, with the same
+// rules and the same messages.
+
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { V2_IMPORTS } from './inject.mjs';
+import { LEGACY_ROOT_DOOR_FILE, withLegacyDoors } from './legacy-names.mjs';
+
+const SHARED_REF_RE = /["'(=]\s*\/(shared\/[A-Za-z0-9_@./-]+)/g;
+const CODE_FILE_RE = /\.(js|mjs|html|css)$/i;
+const ROOT_DOOR = 'joystack';
+
+function decodeText(bytes) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Throws when the game's code names an engine file or door its engine does not
+ * ship. `files` maps each path to its bytes; `engine` is the installed engine
+ * ({ version, sharedDir }).
+ */
+export function checkGameCode(files, engine) {
+  // The engine's files by exact path, as the platform's release lists them: a
+  // folder, a `..` path or a different letter case is not a file it serves.
+  let entries = [];
+  try {
+    entries = readdirSync(engine.sharedDir, { recursive: true, withFileTypes: true });
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const shipped = new Set(
+    entries.filter((e) => e.isFile()).map((e) => `shared/${relative(engine.sharedDir, join(e.parentPath ?? e.path, e.name)).split('\\').join('/')}`),
+  );
+  const ships = (path) => shipped.has(path);
+  const texts = new Map();
+  for (const [path, bytes] of files) texts.set(path, decodeText(bytes));
+
+  for (const [path, text] of texts) {
+    if (text == null || !CODE_FILE_RE.test(path)) continue;
+    for (const m of text.matchAll(SHARED_REF_RE)) {
+      if (!ships(m[1])) throw new Error(`game references /${m[1]}, which engine ${engine.version} does not ship`);
+    }
+  }
+
+  // Whether each door's engine file ships, under the door's current name and
+  // its old one. An engine from before the rename has the root door under its
+  // old file name.
+  const available = {};
+  for (const [door, url] of Object.entries(V2_IMPORTS)) {
+    available[door] = ships(url.replace(/^\//, '')) || (door === ROOT_DOOR && ships(LEGACY_ROOT_DOOR_FILE));
+  }
+  const doors = withLegacyDoors(available);
+  const used = new Set([ROOT_DOOR, `${ROOT_DOOR}/client`]);
+  for (const text of texts.values()) {
+    if (!text) continue;
+    for (const door of Object.keys(doors)) {
+      if (text.includes(`'${door}'`) || text.includes(`"${door}"`)) used.add(door);
+    }
+  }
+  for (const door of used) {
+    if (!doors[door]) throw new Error(`engine ${engine.version} does not ship the \`${door}\` import`);
+  }
+}

package/lib/publish-upload.mjs

@@ -0,0 +1,163 @@
+// The file-by-file publish: ask which files the platform lacks, upload those
+// one per request, then ask it to put the game live.
+//
+//   POST /api/creator/publish/missing      fingerprints, CHECK_BATCH at a time
+//   PUT  /api/creator/publish/file/<sha256> one file each, UPLOAD_CONCURRENCY at once
+//   POST /api/creator/publish/finish       the publish's meta
+//
+// The platform stores files by fingerprint and shares them across every game,
+// so a publish to a new name (a review copy, a lane's copy) uploads only what no
+// earlier publish stored, and a publish cut off halfway resumes where it
+// stopped. Each request is small, so none runs into the platform's
+// per-request limits. A request refused for a passing reason (a rate limit, a
+// network error, the platform busy or restarting) is retried on its own with a
+// growing wait; anything else fails the publish with the platform's message.
+
+// Fingerprints asked about per request. The platform answers up to 250
+// (MAX_CHECK_BATCH in backend/api/src/routes/publish.js), but each request
+// looks them up in storage only six at a time, each lookup a round trip of
+// hundreds of milliseconds from far away; small batches in parallel requests
+// answer a large game in a few seconds.
+export const CHECK_BATCH = 25;
+// Each upload request spends most of its time waiting on round trips between
+// the platform and its database and storage, about 1.4 s from far away, so
+// many overlap. Measured from Mauritius on 120 small files: 29 s at 6 at once,
+// 8 s at 24, 5 s at 48.
+export const UPLOAD_CONCURRENCY = 32;
+// Batches of the "which are missing" question in flight at once.
+export const CHECK_CONCURRENCY = 32;
+const ATTEMPTS = 6;
+const UPLOAD_TIMEOUT_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 2 * 60_000;
+// The platform answers 503 for a failure that may pass (storage busy, a
+// publish that failed and changed nothing); Cloudflare's edge answers 503 when
+// a request ran out of CPU, and 52x when it could not reach the platform. A 500
+// is retried only when it is the platform's unexpected-error answer: its other
+// 500s name a fault in its own setup, which a retry does not fix. A 502 means
+// a game's server failed to deploy.
+const RETRYABLE = new Set([408, 429, 503, 504, 520, 521, 522, 523, 524]);
+const UNEXPECTED_ERROR = '{"error":"internal error"}';
+
+export class LegacyPlatform extends Error {}
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Uploads what the platform lacks and finishes the publish. `files` maps each
+ * path to its bytes, `meta.files` each path to its SHA-256. Returns the
+ * platform's answer ({ slug, title, … }) with `uploaded` and `alreadyStored`
+ * counts. Throws LegacyPlatform when the platform predates these routes.
+ */
+export async function publishFileByFile({ apiBase, token, files, meta, log = console.log, fetchImpl = fetch, sleep = defaultSleep }) {
+  const auth = token ? { Authorization: `Bearer ${token}` } : {};
+
+  // One request, retried while the reason passes. Returns the response of the
+  // first attempt that is not retryable.
+  const request = async (what, url, init, timeoutMs = REQUEST_TIMEOUT_MS) => {
+    for (let attempt = 1; ; attempt++) {
+      let res = null;
+      let error = null;
+      try {
+        res = await fetchImpl(url, { ...init, headers: { ...auth, ...init.headers }, signal: AbortSignal.timeout(timeoutMs) });
+      } catch (err) {
+        error = err;
+      }
+      if (res?.status === 500) {
+        const body = await res.text();
+        if (body.trim() !== UNEXPECTED_ERROR) return new Response(body, { status: 500 });
+        res = new Response(body, { status: 500 });
+      } else if (res && !RETRYABLE.has(res.status)) return res;
+      if (attempt === ATTEMPTS) {
+        if (res) return res;
+        throw new Error(`${what} failed after ${ATTEMPTS} attempts: ${error?.cause?.message ?? error?.message ?? error}`);
+      }
+      const retryAfter = Number(res?.headers.get('retry-after'));
+      const wait = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** (attempt - 1);
+      if (res?.status === 429) log(`  The platform asked to slow down; continuing in ${Math.round(wait / 1000)} s…`);
+      await res?.body?.cancel().catch(() => {});
+      await sleep(wait);
+    }
+  };
+  const failed = async (what, res) => {
+    const detail = await res.text().catch(() => '');
+    return new Error(`${what} failed (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+  };
+
+  const byHash = new Map();
+  for (const [path, bytes] of files) byHash.set(meta.files[path], bytes);
+  const hashes = [...byHash.keys()];
+
+  const batches = [];
+  for (let i = 0; i < hashes.length; i += CHECK_BATCH) batches.push(hashes.slice(i, i + CHECK_BATCH));
+  const missing = [];
+  const ask = async (batch) => {
+    const res = await request('checking which files the platform has', `${apiBase}/api/creator/publish/missing`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ files: batch }),
+    });
+    if (res.status === 404) throw new LegacyPlatform('the platform has no file-by-file publish');
+    if (!res.ok) throw await failed('publish', res);
+    missing.push(...(await res.json()).missing);
+  };
+  // The first batch alone, so a platform without these routes is found before
+  // anything else is sent.
+  await ask(batches[0]);
+  const rest = batches.slice(1);
+  await Promise.all(Array.from({ length: Math.min(CHECK_CONCURRENCY, rest.length) }, async () => {
+    for (let batch = rest.shift(); batch; batch = rest.shift()) await ask(batch);
+  }));
+
+  const bytesOf = (hash) => byHash.get(hash).byteLength;
+  const total = missing.reduce((n, h) => n + bytesOf(h), 0);
+  const mb = (n) => (n / 1024 / 1024).toFixed(1);
+  log(
+    missing.length
+      ? `Uploading ${missing.length} of ${hashes.length} files (${mb(total)} MB); the platform already has the rest.`
+      : `The platform already has all ${hashes.length} files; nothing to upload.`,
+  );
+
+  let done = 0;
+  let sent = 0;
+  let nextReport = 0.25;
+  const queue = [...missing];
+  let stopped = false;
+  const worker = async () => {
+    for (let hash = queue.shift(); hash && !stopped; hash = queue.shift()) {
+      let res;
+      try {
+        res = await request(
+          'uploading a file',
+          `${apiBase}/api/creator/publish/file/${hash}`,
+          { method: 'PUT', headers: { 'content-type': 'application/octet-stream' }, body: byHash.get(hash) },
+          UPLOAD_TIMEOUT_MS,
+        );
+      } catch (err) {
+        stopped = true;
+        throw err;
+      }
+      if (!res.ok) {
+        stopped = true;
+        const path = Object.keys(meta.files).find((p) => meta.files[p] === hash);
+        throw await failed(`uploading ${path}`, res);
+      }
+      await res.body?.cancel().catch(() => {});
+      done++;
+      sent += bytesOf(hash);
+      // Progress on a long upload, at each quarter.
+      if (missing.length >= 40 && done / missing.length >= nextReport && done < missing.length) {
+        log(`  ${done} of ${missing.length} files uploaded (${mb(sent)} of ${mb(total)} MB)…`);
+        while (done / missing.length >= nextReport) nextReport += 0.25;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, missing.length) }, worker));
+
+  const res = await request('publish', `${apiBase}/api/creator/publish/finish`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(meta),
+  });
+  if (!res.ok) throw await failed('publish', res);
+  return { ...(await res.json()), uploaded: missing.length, alreadyStored: hashes.length - missing.length };
+}

package/lib/publish.mjs

@@ -5,10 +5,11 @@
 // release registry. The client never stages the shared library itself — that
 // trust hole is what this design replaces.
 //
-// Target: /api/creator/publish — the token-authenticated creator lane, the
-// one publish route reachable on the public play host (the legacy
-// /api/publish stays behind the builder's Access wall). The endpoint
-// requires the creator token; without one it 401s with a login hint.
+// The upload is file by file (publish-upload.mjs): the platform says which
+// files it lacks, those go up one per request, and a last request puts the
+// game live. A platform without those routes gets the single request
+// /api/creator/publish with every file. Both need the creator token; without
+// one the platform answers 401 with a login hint.
 import { createHash } from 'node:crypto';
 import { findProject } from './project.mjs';
 import { isLane, laneParentSlug } from './lane.mjs';
@@ -32,6 +33,8 @@ export const playUrlFor = (slug) => `https://${slug}.joystack.games/`;
 export { collectGameFiles, gitIgnored } from './game-files.mjs';
 import { collectGameFiles } from './game-files.mjs';
 import { gameBuild } from './build-id.mjs';
+import { checkGameCode } from './publish-checks.mjs';
+import { LegacyPlatform, publishFileByFile } from './publish-upload.mjs';
 
 export async function publish({
   cwd = process.cwd(),
@@ -154,15 +157,33 @@ export async function publish({
   }
 
   const meta = { slug: targetSlug, entry: 'index.html', engineVersion: engine.version, build, files: {}, ...frameworkMeta, ...(devTools ? { devTools: true } : {}) };
-  const form = new FormData();
-  for (const [path, bytes] of files) {
-    meta.files[path] = createHash('sha256').update(bytes).digest('hex');
-    form.append(path, new Blob([bytes]), path);
-  }
-  form.append('meta', JSON.stringify(meta));
+  for (const [path, bytes] of files) meta.files[path] = createHash('sha256').update(bytes).digest('hex');
+
+  // The platform only publishes framework-v2 games, and checks their code
+  // against the engine only on the single-request route; these are the same
+  // checks, before anything is uploaded.
+  if (isFrameworkV2(project.dir)) checkGameCode(files, engine);
 
   log(`Publishing ${targetSlug} (${files.size} files, engine ${engine.version}, build ${build.id}) → ${apiBase}…`);
   const token = getToken();
+  let out;
+  try {
+    out = await publishFileByFile({ apiBase, token, files, meta, log });
+  } catch (err) {
+    if (!(err instanceof LegacyPlatform)) throw err;
+    out = await publishInOneRequest({ apiBase, token, files, meta });
+  }
+  const url = playUrlFor(out.slug);
+  log(devTools ? `✅ Live (review build, Tweaks on): ${url}` : `✅ Live: ${url}`);
+  return { slug: out.slug, url };
+}
+
+// The single-request publish, for a platform without the file-by-file routes:
+// every file in one multipart request.
+async function publishInOneRequest({ apiBase, token, files, meta }) {
+  const form = new FormData();
+  for (const [path, bytes] of files) form.append(path, new Blob([bytes]), path);
+  form.append('meta', JSON.stringify(meta));
   const res = await fetch(`${apiBase}/api/creator/publish`, {
     method: 'POST',
     headers: token ? { Authorization: `Bearer ${token}` } : {},
@@ -172,8 +193,5 @@ export async function publish({
     const detail = await res.text().catch(() => '');
     throw new Error(`publish failed (HTTP ${res.status}): ${detail.slice(0, 300)}`);
   }
-  const out = await res.json();
-  const url = playUrlFor(out.slug);
-  log(devTools ? `✅ Live (review build, Tweaks on): ${url}` : `✅ Live: ${url}`);
-  return { slug: out.slug, url };
+  return res.json();
 }

package/lib/update.mjs

@@ -16,6 +16,7 @@ import { login } from './login.mjs';
 import { compareVersions, renderReleases } from './changelog.mjs';
 import { syncCli, reportCli } from './self-update.mjs';
 import { fetchStatus, landedIn } from './feedback-sync.mjs';
+import { MOVED_FROM_LEGACY_NOTE, movedFromLegacy } from './legacy-names.mjs';
 
 // The report is the point. A creator reading this must be able to answer, with
 // no further digging: what changed, was any of it mine, and what do I do now.
@@ -69,6 +70,20 @@ function report(log, engineVersion, surface) {
   log("   changes you didn't make. Review them and save them with your next commit.");
 }
 
+// A game made before the rename moves over in this update. What is Joystack's
+// has moved; what the game itself says (its links, its tests, a token its
+// automation publishes with) has not, and the note lists it for the agent
+// reading this output. Neither condition holds on a later update, so it is
+// printed this once only.
+function noteMove(log, cli, surface) {
+  const moved = movedFromLegacy(cli, surface);
+  if (moved) {
+    log('');
+    for (const line of MOVED_FROM_LEGACY_NOTE) log(`   ${line}`);
+  }
+  return moved;
+}
+
 export async function update({
   cwd = process.cwd(),
   apiBase = getApiBase(DEFAULT_API_BASE),
@@ -146,7 +161,8 @@ export async function update({
     log('   This is a pre-release candidate — its changelog and any migration');
     log('   notes ship inside the engine (read the handbook / engine docs), not');
     log('   via `joystack changelog`. Republish (`npx joystack publish`) when ready.');
-    return { from, to: engine.version, updated: from !== engine.version, surface, crossed: null, cli, candidate: true };
+    const movedIn = noteMove(log, cli, surface);
+    return { from, to: engine.version, updated: from !== engine.version, surface, crossed: null, cli, candidate: true, movedIn };
   }
 
   const res = await fetchImpl(`${apiBase}/api/creator/engine`, {
@@ -295,5 +311,6 @@ export async function update({
     log('');
     log('   Republish (`npx joystack publish`) when you want the live game on it.');
   }
-  return { from, to: latest, updated, surface, crossed, cli, landed };
+  const movedIn = noteMove(log, cli, surface);
+  return { from, to: latest, updated, surface, crossed, cli, landed, movedIn };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",