@joystack/cli 0.0.0-stage → 0.1.43

package/lib/printable.mjs

@@ -0,0 +1,12 @@
+// Text that may have come from somewhere other than the person at the
+// terminal (a page the game's code runs in, a file in the game folder),
+// made safe to print: no escape sequences a terminal would act on (C0 and C1
+// controls, DEL), and no characters that make text display in an order or on
+// lines other than the ones it is written in (direction marks, overrides and
+// isolates, the line and paragraph separators). Each is replaced by a space.
+export const printable = (text) => String(text ?? '')
+  .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, ' ');
+
+// The same for a message of several lines: each line made printable, the
+// line breaks kept.
+export const printableLines = (text) => String(text ?? '').split('\n').map(printable).join('\n');

package/lib/process-tree.mjs

@@ -0,0 +1,30 @@
+import { execFileSync } from 'node:child_process';
+import { win32 } from 'node:path';
+
+// PartyKit owns worker descendants. Windows has no Unix process groups, so
+// killing its wrapper alone can leave a worker holding ports and directories.
+export function terminateChildTree(child, signal = 'SIGTERM', {
+  platform = process.platform, exec = execFileSync, kill = process.kill,
+} = {}) {
+  if (child.pid == null) return;
+  if (platform === 'win32') {
+    if (child.exitCode != null || child.signalCode != null) return;
+    const taskkill = win32.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
+    try {
+      exec(taskkill, ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'pipe', timeout: 5000, windowsHide: true,
+      });
+    } catch (error) {
+      // An already-exited child is harmless; a live tree that could not be
+      // terminated must fail shutdown rather than silently leak workers.
+      try { kill(child.pid, 0); } catch (probe) {
+        if (probe.code === 'ESRCH') return;
+      }
+      throw error;
+    }
+    return;
+  }
+  try { kill(-child.pid, signal); } catch {
+    child.kill(signal);
+  }
+}

package/lib/project.mjs

@@ -0,0 +1,84 @@
+// Locate the standalone game project and its installed engine bundle.
+//
+// A project is the folder holding the game's package.json (created by
+// `joystack create`, or by hand). The slug — the published URL is
+// <slug>.joystack.games — defaults to the folder name; package.json's
+// `joystack.slug` overrides it for folks whose repo name differs.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { gameConfig, readEnv } from './legacy-names.mjs';
+
+export function findProject(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath) && existsSync(join(dir, 'index.html'))) {
+      let pkg = {};
+      try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      } catch {
+        // Unparseable package.json: still treat as the project root; slug
+        // falls back to the folder name.
+      }
+      return { dir, slug: gameConfig(pkg).slug || basename(dir), pkg };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(
+        `Not inside a Joystack game project (no folder with both package.json and index.html above ${startDir}). ` +
+          'Run this from your game folder, or bootstrap one with `joystack create <name>`.',
+      );
+    }
+    dir = parent;
+  }
+}
+
+// An engine CHECKOUT, used where it lies — the lane for working on the engine
+// itself against a real game. Dev-only, and env-gated rather than a flag so it
+// cannot be left switched on in a repo.
+//
+// Every tool resolves the engine through here, which is the point: the dev
+// server serving one engine while `joystack lint` and the auto-bake sweep check a
+// different one is a false green of the worst kind — the browser runs the new
+// code, the gate passes on the old, and nothing on screen says so.
+//
+// It does NOT fall back to the installed copy when the path is wrong. A silent
+// fallback is how the override became invisible in the first place.
+function engineCheckout(dir) {
+  if (!existsSync(join(dir, 'package.json')) || !existsSync(join(dir, 'shared'))) {
+    throw new Error(
+      `JOYSTACK_ENGINE_DIR=${dir} is not an engine build.\n` +
+        'Expected a package.json and a shared/ directory in it — point at an engine ' +
+        "bundle (packages/engine/dist after `node packages/engine/build.mjs`), not at the repo root.",
+    );
+  }
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+  return {
+    dir,
+    // A checkout carries no cut version; only a release does.
+    version: pkg.version ?? 'working tree',
+    sharedDir: join(dir, 'shared'),
+    roomServerDir: join(dir, 'room-server'),
+  };
+}
+
+export function resolveEngine(projectDir) {
+  const override = readEnv('JOYSTACK_ENGINE_DIR');
+  if (override) return engineCheckout(resolve(override));
+  const dir = join(projectDir, 'node_modules', '@joystack', 'engine');
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      'the Joystack engine is not installed in this project.\n' +
+        `Expected it at ${dir}.\n` +
+        'Run `joystack dev` (or `joystack publish`) — it downloads the engine from the platform (sign-in required).',
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  return {
+    dir,
+    version: pkg.version,
+    sharedDir: join(dir, 'shared'),
+    roomServerDir: join(dir, 'room-server'),
+  };
+}

package/lib/publish.mjs

@@ -0,0 +1,179 @@
+// `joystack publish` — ship the game to its own host, https://<slug>.joystack.games/.
+//
+// Server-resolved: we send ONLY the game's own files plus the engine version
+// the installed bundle declares; the platform resolves /shared/... from its
+// 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.
+import { createHash } from 'node:crypto';
+import { findProject } from './project.mjs';
+import { isLane, laneParentSlug } from './lane.mjs';
+import { ensureEngine } from './engine.mjs';
+import { DEFAULT_API_BASE, getApiBase, getToken } from './config.mjs';
+import { bundlePrimitives } from './bundle-primitives.mjs';
+import { scanEntityComponents, buildV2PublishModule } from './room-server.mjs';
+import {
+  BROWSER_REGISTRY,
+  SERVER_BARREL,
+  SERVER_V2_ROOM,
+  assertNoInertOverride,
+  isFrameworkV2,
+  renderBrowserRegistry,
+  scanPrimitives,
+} from './primitives.mjs';
+
+// A published game is served from its own host.
+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';
+
+export async function publish({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  slug,
+  devTools = false,
+  log = console.log,
+} = {}) {
+  const project = findProject(cwd);
+
+  // `--dev-tools` publishes a REVIEW BUILD: the published page carries the dev
+  // toolbox, so whoever opens the link can use the game's Tweaks. That belongs on
+  // a copy made for reviewing (a pull request's link, a lane's), never on the
+  // game players open — so it needs its own --slug, and the game's own slug is
+  // refused outright, and so is the slug of the game a lane was opened from.
+  // Checked before anything is built or sent.
+  if (devTools && (!slug || slug === project.slug || slug === laneParentSlug(project.dir))) {
+    throw new Error(
+      `--dev-tools publishes a review build, and a review build never replaces the live game.\n\n` +
+        `  npx joystack publish --dev-tools --slug ${project.slug}-review   # a review copy with Tweaks\n` +
+        `  npx joystack publish                                   # the live game, without dev tools`,
+    );
+  }
+
+  // Published rooms must hit the surface players see: re-bake any referenced
+  // model whose GLB or bake config changed before the game ships. Fails the
+  // publish, loudly, rather than deploying a room that shoots at an old shape.
+  {
+    const { ensureBaked } = await import('./model-bake.mjs');
+    await ensureBaked({ dir: project.dir, log });
+  }
+
+  // A publish is GLOBAL, PERMANENT and IRREVERSIBLE — the first one claims the
+  // name for this account forever. A lane is a throwaway experiment in a folder
+  // named after it, and the slug defaults to the folder name, so a bare publish
+  // from one would claim "riven-judder" for all time (or 403 against whoever
+  // owns it). And when a game overrides `joystack.slug`, the lane inherits it and
+  // would silently overwrite the LIVE game with the experiment.
+  //
+  // A name this permanent is never guessed inside a lane. The guard is on
+  // GUESSING, not on publishing: name it with --slug and it goes through.
+  if (!slug && isLane(project.dir)) {
+    throw new Error(
+      `This is a lane, not your game. Publishing from here would claim the name ` +
+        `"${project.slug}" permanently.\n\n` +
+        `  npx joystack publish --slug ${project.slug}-test   # publish an A/B copy to compare\n` +
+        `  npx joystack publish --slug <your-game>            # ship this lane AS the real game\n\n` +
+        `Or merge the lane into your game and publish from there.`,
+    );
+  }
+
+  // The declared engineVersion must be a version the platform can resolve —
+  // ensureEngine keeps the local install synced to the game's pin.
+  const engine = await ensureEngine(project.dir, { apiBase, log });
+  const targetSlug = slug ?? project.slug;
+
+  const files = collectGameFiles(project.dir);
+  // The build id of the creator's own files, before the generated ones below
+  // join the upload: the same files, and so the same id, a recording of this
+  // code under `joystack dev` carries (build-id.mjs). It is computed from the
+  // files just collected, so it names exactly what is uploaded.
+  const build = gameBuild(project.dir, { files });
+  if (!files.has('index.html')) {
+    throw new Error('this game has no index.html at its root — publish needs an entry page.');
+  }
+
+  // Server-backed game — it has primitives of its own. The SAME predicate `joystack
+  // dev` uses (isServerBacked), so a game can never be server-backed in one and
+  // not the other. Two different checks would let them disagree, and a
+  // creator's primitive would run in production and silently not on their
+  // machine.
+  //
+  // Two files are GENERATED into the upload; neither is in the creator's git:
+  //
+  //   the SERVER barrel — bundled here, not at the endpoint (a Pages Function has
+  //     no bundler, and real primitives import npm packages and WASM). The engine
+  //     is marked external and rewritten to the release's pre-bundled runtime, so
+  //     the worker's room code is always ours.
+  //
+  //   the BROWSER registry — shadows the engine's primitive registry, merged, so
+  //     the CLIENT predicts with the game's classes too. Without it the server
+  //     runs the creator's primitive while the client predicts with the engine's
+  //     class of the same name, and the game rubber-bands. The creator never
+  //     wires this up (`createRoom({ extraPrimitives })`).
+  // Refuse to SHIP an override the server can never honour. dev catches this
+  // first, but publish must not trust that dev ran: the whole failure mode we
+  // are killing is an override that uploads, serves, and silently never runs.
+  // A framework-v2 game authors entities + traits + a world; it has no
+  // overrides/ or components/ folder. It ships a single generated module — the
+  // lowered room module (built HERE by the framework compiler) — plus its
+  // skeleton in meta, and takes none of the primitive/entity-component scan
+  // path below.
+  let frameworkMeta = {};
+  if (isFrameworkV2(project.dir)) {
+    const { source, skeleton } = await buildV2PublishModule({ projectDir: project.dir, engine });
+    files.set(SERVER_V2_ROOM, Buffer.from(source, 'utf8'));
+    frameworkMeta = { framework: 'v2', skeleton };
+    log(`Built the framework-v2 room module (${(source.length / 1024).toFixed(0)} KB) — lowered to v1 on your machine.`);
+  } else {
+    assertNoInertOverride({ projectDir: project.dir, engine });
+    const serverPrimitives = scanPrimitives(project.dir); // throws on a reserved index.js
+    const entityComponents = await scanEntityComponents(project.dir, engine.sharedDir); // throws on a malformed component
+    if (serverPrimitives.length || entityComponents.length) {
+      const { source, externals } = await bundlePrimitives(project.dir, { engineSharedDir: engine.sharedDir });
+      files.set(SERVER_BARREL, Buffer.from(source, 'utf8'));
+      // The browser prediction registry exists for PRIMITIVES only — entity
+      // components' client/shared files ship as ordinary game files, and the
+      // client imports its own manifests directly.
+      if (serverPrimitives.length) {
+        files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
+      }
+      const names = [
+        ...serverPrimitives.map((p) => p.type),
+        ...entityComponents.map((c) => `${c.name} (component)`),
+      ].join(', ');
+      log(
+        `Bundled server code — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
+      );
+    }
+  }
+
+  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));
+
+  log(`Publishing ${targetSlug} (${files.size} files, engine ${engine.version}, build ${build.id}) → ${apiBase}…`);
+  const token = getToken();
+  const res = await fetch(`${apiBase}/api/creator/publish`, {
+    method: 'POST',
+    headers: token ? { Authorization: `Bearer ${token}` } : {},
+    body: form,
+  });
+  if (!res.ok) {
+    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 };
+}