@joystack/cli 0.1.46 → 0.1.48

package/CHANGELOG.md

@@ -14,6 +14,56 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.48] - 2026-10-10
+
+### Added
+
+- `joystack publish --open` makes a copy published with `--slug` open to
+  anyone with a Joystack account. Without it, a `--slug` copy (an A/B copy, a
+  review build) opens only for accounts invited to Joystack.
+
+### Changed
+
+- Your game at its own address (`joystack publish` with no `--slug`, or
+  `--slug` set to the game's own name) is open to anyone with a Joystack
+  account, invited or not. A player who is not signed in is asked to sign in
+  first. A game published before this version opens only for invited accounts
+  until you publish it again.
+
+- `joystack dev` reloads the game only when one of the game's own files
+  changes: the files `joystack publish` would upload, plus `package.json`.
+  Notes, tests, agent instructions and anything your `.gitignore` leaves out
+  no longer reload it. A log you write into the game folder used to reload
+  the game over and over until the page stopped loading; with `*.log` in
+  `.gitignore` (new games have it) that can no longer happen.
+- `joystack dev` writes everything it prints to `.joystack/dev/last.log` as
+  well, and names that file when it starts, so its output can be read later
+  without sending it to a file of your own.
+
+### Fixed
+
+- Sessions recorded under `joystack dev` carry the build of the game they ran
+  on. They were stamped with an empty build, because the copy `joystack dev`
+  serves sits in the ignored `.joystack/` folder and every file in it read as
+  ignored.
+- A game folder inside a larger git repository that ignores that folder is
+  published whole. Every file in it used to read as ignored.
+- `joystack create` gives a new game an exact Playwright version (1.64.0)
+  instead of "1.61.1 or any newer 1.x". Every game made on this CLI gets the
+  same Playwright and Chromium, and creating a game no longer downloads a new
+  Chromium each time Playwright publishes a release. Games you already have
+  keep the Playwright they have.
+
+## [0.1.47] - 2026-10-09
+
+### Added
+
+- `joystack setup` prints the guide an AI agent follows to make your first
+  game: ask what to call it, run `create`, then hand off into the new folder.
+  It works from any folder, before you have signed in, so the way to start is
+  now to ask your agent to run `npx -y joystack@latest setup` and follow what
+  it prints.
+
 ## [0.1.46] - 2026-10-09
 
 ### Changed

package/README.md

@@ -9,8 +9,9 @@ cd my-game
 npx joystack dev
 ```
 
-New here? Point your AI agent at **https://docs.joystack.ai/setup.md** and say
-"set me up to make Joystack games."
+New here? Ask your AI agent to run **`npx -y joystack@latest setup`** and follow
+what it prints. It asks what to call your game, creates the folder, and tells
+you how to carry on from inside it.
 
 ## License
 

package/bin/joystack.mjs

@@ -9,6 +9,7 @@ import { lane } from '../lib/lane.mjs';
 import { login, logout, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
+import { setupGuide } from '../lib/setup.mjs';
 import { parseTestArgs, TEST_HELP } from '../lib/test-policy.mjs';
 import { testCmd } from '../lib/test-cmd.mjs';
 import { lintCmd } from '../lib/lint.mjs';
@@ -28,6 +29,7 @@ function flag(name) {
 const HELP = `joystack — build and run Joystack games
 
 Usage:
+  joystack setup                The guide an AI agent follows to make your first game folder
   joystack create <name>        Bootstrap a new game folder (multiplayer works out of the box)
   joystack dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
   joystack dev --share          ...and print a public link testers can play (needs cloudflared)
@@ -44,9 +46,11 @@ Usage:
   joystack changelog [<v>]      What changed in the engine (default: everything newer than your pin)
   joystack update [--rc <v>]    Move this game to the latest engine release (--rc <v> takes a specific pre-release)
   joystack model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
-  joystack publish [--slug <s>] [--dev-tools]
-                              Publish this game to <slug>.joystack.games (--slug for an A/B copy;
-                              --dev-tools makes that copy a review build with Tweaks on)
+  joystack publish [--slug <s>] [--dev-tools] [--open]
+                              Publish this game to <slug>.joystack.games, open to anyone with a
+                              Joystack account (--slug for an A/B copy, open only to invited
+                              accounts unless --open; --dev-tools makes that copy a review build
+                              with Tweaks on)
   joystack build-id             The id of this game's code as it is now, with its git commit
   joystack replay list          Every recorded session: when, how long, on what device, which build
   joystack replay export [<id>]  Turn a recorded session into tables you can query (Parquet)
@@ -190,6 +194,9 @@ try {
       console.log(`\nWork in it:\n  cd ${dir} && npx joystack dev\n`);
       break;
     }
+    case 'setup':
+      process.stdout.write(setupGuide());
+      break;
     case 'create':
       await create({ name: rest.find((a) => !a.startsWith('--')) });
       break;
@@ -265,7 +272,7 @@ try {
       break;
     }
     case 'publish':
-      await publish({ slug: flag('slug'), devTools: rest.includes('--dev-tools') });
+      await publish({ slug: flag('slug'), devTools: rest.includes('--dev-tools'), open: rest.includes('--open') });
       break;
     case 'feedback':
       // Send first, then sync: a report filed this run is already stamped with

package/lib/create.mjs

@@ -65,7 +65,13 @@ const ALLOW_SCRIPTS = { esbuild: true, workerd: true, fsevents: true };
 // devDependencies and the Chromium binary is fetched at create time — a
 // surprise "npm i -D playwright" + browser download mid-build is exactly
 // what create-time provisioning exists to prevent.
-const PLAYWRIGHT_SPEC = '^1.61.1';
+//
+// An exact version, so a game's Playwright, and the Chromium build it needs,
+// changes only when this line does, never when Playwright publishes a release.
+// The maker's machine image carries the Chromium for this version
+// (maker/container/Dockerfile): changing it means rebuilding and redeploying
+// the maker, or every game the maker creates downloads its own Chromium.
+const PLAYWRIGHT_SPEC = '1.64.0';
 
 // The Joystack rules ship as an ESLint config (the scaffold's eslint.config.js,
 // importing the rules from the installed engine), so they squiggle in the

package/lib/dev-log.mjs

@@ -0,0 +1,48 @@
+// `.joystack/dev/last.log`: everything an interactive `joystack dev` prints,
+// written by `joystack dev` itself.
+//
+// An agent runs `joystack dev` in the background and needs its output later.
+// Sending that output to a file of its own puts the file wherever the agent
+// chose, often inside the game folder, where the file is mistaken for part of
+// the game. This file is inside the game's state folder, which nothing treats
+// as the game: no version, no publish, no commit. The game's AGENTS.md tells
+// agents to read it.
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findProject } from './project.mjs';
+import { stateDir } from './legacy-names.mjs';
+
+/**
+ * Starts a fresh log for the game around `cwd`. Returns null when `cwd` is not
+ * in a game (startDev reports that) or the log cannot be written; a dev
+ * server that cannot keep a log still runs.
+ * @returns {{ path: string, write: (line: string) => void, tee: (log: (line: string) => void) => (line: string) => void } | null}
+ */
+export function openDevLog(cwd) {
+  let path;
+  try {
+    const dir = join(stateDir(findProject(cwd).dir), 'dev');
+    mkdirSync(dir, { recursive: true });
+    path = join(dir, 'last.log');
+    writeFileSync(path, '');
+  } catch {
+    return null;
+  }
+  let broken = false;
+  const write = (line) => {
+    if (broken) return;
+    try {
+      appendFileSync(path, `${line}\n`);
+    } catch {
+      broken = true;
+    }
+  };
+  return {
+    path,
+    write,
+    tee: (log) => (line) => {
+      log(line);
+      write(String(line));
+    },
+  };
+}

package/lib/dev.mjs

@@ -23,7 +23,8 @@ import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
 import { createLiveVersions, snapshotFiles } from './live-versions.mjs';
 import { hasDeclaredAssets, assetsPageUrl } from './assets-page.mjs';
 import { openTunnel, shareBanner, engineCanShare } from './share.mjs';
-import { freezeGame, frozenFiles } from './freeze.mjs';
+import { createVersionFiles, freezeGame } from './freeze.mjs';
+import { openDevLog } from './dev-log.mjs';
 import { STATE_DIR_NAMES, readEnv, stateDir } from './legacy-names.mjs';
 
 // The route a room under `joystack dev` answers with the name of the build it
@@ -84,6 +85,12 @@ export async function waitForRoomServer(port, { timeoutMs = 30_000, intervalMs =
 // `share` opens a public link to the stack for testers (share.mjs); `openShare`
 // replaces the tunnel for tests.
 export async function dev(opts = {}) {
+  // An interactive `joystack dev` (watch on, the default) also writes
+  // everything it prints to .joystack/dev/last.log, so an agent that started
+  // it in the background reads its output there instead of sending it to a
+  // file of its own (dev-log.mjs).
+  const devLog = opts.watch === false ? null : openDevLog(opts.cwd ?? process.cwd());
+  if (devLog) opts = { ...opts, log: devLog.tee(opts.log ?? console.log), devLogPath: devLog.path };
   // Whatever startup has made so far, undone if a later step throws: a room
   // build that fails on the creator's code, a port already taken, a tunnel
   // that never opens. A frozen copy of the game is among it.
@@ -94,6 +101,7 @@ export async function dev(opts = {}) {
     for (const fn of undo.reverse()) {
       try { fn(); } catch { /* the original error is the one to report */ }
     }
+    devLog?.write(`joystack dev: ${err?.message ?? err}`);
     throw err;
   }
 }
@@ -102,7 +110,7 @@ export async function dev(opts = {}) {
 // (agent-session.mjs). Only the interactive `joystack dev` and `joystack assets`
 // commands pass one; a stack started by `joystack test` or any other caller has
 // none, so no test run can wake the agent that started it.
-async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null } = {}, onFailure) {
+async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, devLogPath = null } = {}, onFailure) {
   const project = findProject(cwd);
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
@@ -204,8 +212,9 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   };
   // What a version is made from: the game's files, and the engine's, which the
   // room bundle includes. Engine files are served as they are, not copied.
+  const gameFiles = createVersionFiles(project.dir);
   const sourceFiles = () => {
-    const files = frozenFiles(project.dir);
+    const files = gameFiles();
     for (const [k, v] of snapshotFiles([engine.sharedDir], (name) => name.startsWith('.') || name === 'node_modules')) files.set(k, v);
     return files;
   };
@@ -562,6 +571,7 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   if (hasDeclaredAssets(project.dir)) {
     log(`   🔍  ${assetsPageUrl(url)}   (your models, sounds and assets, one at a time)`);
   }
+  if (devLogPath) log(`   📄  ${relative(project.dir, devLogPath).split(sep).join('/')}   (everything this server prints, for reading later)`);
   if (share) {
     log('');
     log('→ share       opening a public link (cloudflared)…');

package/lib/freeze.mjs

@@ -9,7 +9,8 @@
 import { constants, copyFileSync, cpSync, existsSync, linkSync, mkdirSync, readdirSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
-import { collectGameFiles } from './game-files.mjs';
+import { statSync } from 'node:fs';
+import { collectGameFiles, gitIgnored, isGameFilePath } from './game-files.mjs';
 import { gameBuild } from './build-id.mjs';
 import { snapshotFiles } from './live-versions.mjs';
 import { STATE_DIR_NAMES, stateDir } from './legacy-names.mjs';
@@ -39,6 +40,60 @@ export function frozenFiles(dir) {
   return snapshotFiles([dir], (name, depth) => depth === 0 && LEFT_OUT.has(name), { hashBelow: 256 * 1024 });
 }
 
+// Files a version also needs that are not part of the published game:
+// package.json says which framework the game is built on and which engine.
+const BUILD_FILES = new Set(['package.json']);
+const IGNORE_MAX_AGE_MS = 5000;
+
+/**
+ * The files a version of the game is made from, as path → `mtime:size`: the
+ * game's own files by the definition `joystack publish` uses (game-files.mjs),
+ * which leaves out notes, tests, agent instructions and everything the game's
+ * .gitignore excludes, plus BUILD_FILES. A change to any other file in the
+ * folder (a log, a scratch file, a test) is not a change to the game and does
+ * not make a version.
+ *
+ * Asking git which paths the .gitignore excludes is the costly part, so the
+ * answer is kept until the list of paths or an ignore file in the game
+ * changes, and for at most IGNORE_MAX_AGE_MS, which bounds how long a change
+ * git reads from elsewhere (a .gitignore above the game, the global excludes
+ * file, `git add -f`) takes to apply. If git fails after the first answer, the
+ * last answer stands and git is asked again on the next look, so a passing
+ * git failure never stops the dev server.
+ */
+export function createVersionFiles(dir) {
+  let key = null;
+  let askedAt = 0;
+  let ignored = null;
+  const exclude = join(dir, '.git', 'info', 'exclude');
+  return () => {
+    const all = frozenFiles(dir);
+    const rels = new Map();
+    for (const path of all.keys()) rels.set(path, relative(dir, path).split(sep).join('/'));
+    const candidates = [...rels.values()].filter((rel) => BUILD_FILES.has(rel) || isGameFilePath(rel));
+    let excludeStamp = '';
+    try { excludeStamp = String(statSync(exclude).mtimeMs); } catch { /* none */ }
+    const ignoreFiles = [...all].filter(([path]) => basename(path) === '.gitignore').map(([, entry]) => entry);
+    const nextKey = `${candidates.join('\0')}|${ignoreFiles.join('|')}|${excludeStamp}`;
+    if (nextKey !== key || Date.now() - askedAt > IGNORE_MAX_AGE_MS) {
+      try {
+        ignored = gitIgnored(dir, candidates);
+        key = nextKey;
+        askedAt = Date.now();
+      } catch (err) {
+        if (ignored === null) throw err;
+        key = null;
+      }
+    }
+    const out = new Map();
+    for (const [path, entry] of all) {
+      const rel = rels.get(path);
+      if ((BUILD_FILES.has(rel) || isGameFilePath(rel)) && !ignored.has(rel)) out.set(path, entry);
+    }
+    return out;
+  };
+}
+
 /**
  * Copies the game at `dir` into `.joystack/frozen/<pid>-<random>/<folder name>`.
  * `build()` is the game's build as the copy has it, the one every session

package/lib/game-files.mjs

@@ -40,6 +40,12 @@ const SKIP_FILES = [
 // files the .gitignore was written to keep out.
 export function gitIgnored(dir, rels) {
   if (!rels.length) return new Set();
+  // A folder that is itself ignored by an enclosing repository is not part of
+  // that repository, so no .gitignore is in force inside it: git would report
+  // every file under it as ignored. A copy of the game that `joystack dev`
+  // serves lives in the game's ignored .joystack/ folder, and a game folder can
+  // sit in an ignored folder of a larger repository; both keep all their files.
+  if (folderIgnored(dir)) return new Set();
   try {
     const out = execFileSync('git', ['check-ignore', '--stdin', '-z'], {
       cwd: dir,
@@ -59,6 +65,17 @@ export function gitIgnored(dir, rels) {
   }
 }
 
+function folderIgnored(dir) {
+  try {
+    execFileSync('git', ['check-ignore', '-q', '.'], { cwd: dir, stdio: 'ignore', timeout: 30_000 });
+    return true;
+  } catch {
+    // Exit 1 (not ignored), 128 (no repository) or no git: the .gitignore, if
+    // any, is read as usual below.
+    return false;
+  }
+}
+
 /**
  * Whether a path, relative to the game folder with `/` separators, is one the
  * walk below would take by its name alone — before the .gitignore check. A

package/lib/publish.mjs

@@ -41,6 +41,7 @@ export async function publish({
   apiBase = getApiBase(DEFAULT_API_BASE),
   slug,
   devTools = false,
+  open = false,
   log = console.log,
 } = {}) {
   const project = findProject(cwd);
@@ -90,6 +91,14 @@ export async function publish({
   // ensureEngine keeps the local install synced to the game's pin.
   const engine = await ensureEngine(project.dir, { apiBase, log });
   const targetSlug = slug ?? project.slug;
+  // Who may open the published game. The game under its own name is open to
+  // every signed-in Joystack account; a copy under another name (an A/B copy, a
+  // pull request's or a lane's review link) is open only to invited accounts,
+  // unless --open asks otherwise. Inside a lane the game's own name is that of
+  // the game the lane was opened from, since the lane folder is named after the
+  // lane.
+  const ownSlug = laneParentSlug(project.dir) ?? project.slug;
+  const openToAll = open || targetSlug === ownSlug;
 
   const files = collectGameFiles(project.dir);
   // The build id of the creator's own files, before the generated ones below
@@ -156,7 +165,7 @@ export async function publish({
     }
   }
 
-  const meta = { slug: targetSlug, entry: 'index.html', engineVersion: engine.version, build, files: {}, ...frameworkMeta, ...(devTools ? { devTools: true } : {}) };
+  const meta = { slug: targetSlug, entry: 'index.html', engineVersion: engine.version, build, files: {}, ...frameworkMeta, ...(devTools ? { devTools: true } : {}), open: openToAll };
   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

package/lib/setup-guide.md

@@ -0,0 +1,122 @@
+# Make games on Joystack
+
+Joystack is a place to make multiplayer browser games and play them with
+friends; each game lives at its own address, `https://<name>.joystack.games/`.
+Anyone can make one. You don't
+need to know how to code: your AI coding agent does the technical work; you
+describe the game you want and play-test it.
+
+Joystack is **agent-agnostic**: it works with Claude Code, Gemini CLI, Codex,
+opencode, or any agent that reads a project's instruction files. There is no
+plugin or extension to install. Every game folder carries its own agent
+instructions (`AGENTS.md`, with `CLAUDE.md` / `GEMINI.md` pointers, and skills
+under `.claude/skills/`), so whatever tool you use picks them up.
+
+This guide is what `npx -y joystack@latest setup` prints. It is written for
+the AI agent: **if you are the agent, follow these steps.** If you are the
+human, ask your agent to run that command and follow what it prints.
+
+**Your whole job here is: create the folder, then hand off.** Two steps, and the
+page ends. You are *not* going to build, run, or publish the game from where you
+are now — and this page deliberately doesn't tell you how, because that isn't
+your task and those instructions are not yours to hold.
+
+**They live in the game folder.** The scaffold you're about to create carries its
+own `AGENTS.md`, its own skills (`/build`, `/qa`, `/feedback`, …), its own
+handbook, and the engine's craft docs. An agent picks all of that up **only when
+its working directory is that folder**. That is the entire reason for the
+handoff: not bureaucracy, but the fact that the knowledge for building the game
+is *inside* the thing you're creating, and you can't reach it from out here.
+
+## 1. Prerequisites
+
+- Node.js 20.11+ (`node --version`; install from https://nodejs.org if missing).
+- A Joystack account. You don't need one *before* you start — `create` signs the
+  human in as part of making the folder (step 2). It's free, and it takes a
+  click.
+- Nothing else. The engine, its libraries, and the craft docs download during
+  `create`, into the game folder. There is no global install.
+
+## 2. Create the game
+
+Ask the human what to name the game. The name becomes both the folder and the
+published URL slug, so it must be **lowercase letters, numbers and dashes**
+(e.g. `neon-racer`). Don't invent one silently. It's theirs to choose.
+
+```bash
+npx -y joystack@latest create <name>
+```
+
+This scaffolds `<name>/` as its own git repo: a working multiplayer game plus
+all the agent instructions and the `/build` workflow, inside the folder.
+
+**This command will pause and ask the human to sign in.** That is expected — not
+a hang, and nothing has gone wrong. Joystack's engine downloads with the game, and
+that download is tied to their account. What happens:
+
+1. A browser window opens on the Joystack activation page.
+2. The command prints a short code (like `WXYZ-1234`) and waits.
+3. The human enters that code in the browser and approves.
+4. `create` continues on its own.
+
+**Tell them this is coming, before you run it** — a browser opening by itself and
+a command that stops mid-way is alarming if nobody warned you. Say something
+like: *"This will open your browser to sign you in to Joystack — enter the code it
+shows and approve, and it'll carry on."* Then read them the code from the output.
+
+If they close the window or it times out, nothing is left behind: `create`
+removes the half-made folder so you can simply run it again.
+
+Once signed in, this machine stays signed in — no other command in Joystack will
+ask again.
+
+## 3. Hand off — and stop
+
+**Say this to the human, and end your turn:**
+
+> "Your game is ready, in the folder `<name>`. Now open your agent again **with
+> that folder as its working directory** — a fresh session inside the folder —
+> and tell it what you want to build. Everything needed to make the game lives
+> in there; I can't reach it from here."
+
+Then stop. **Do not** `cd` in and keep working. **Do not** start the dev server,
+install anything, write files into the new repo, take screenshots, or "just check
+that it works" — it already works, and the folder ships with its own test that
+the next session will run. Anything you do from out here is done *without* the
+game's instructions, on a repo that isn't shaped for your current habits. That is
+how creators end up with stray files in their first commit and confident, wrong
+answers about their own game.
+
+**If the human doesn't know how to do that** — and many won't, this is the one
+genuinely technical moment in Joystack — walk them through it rather than doing it
+for them. Explain it plainly:
+
+> "Whatever you're using me through — a terminal, an editor, a desktop app —
+> point it at the `<name>` folder and start a new chat there. It's the same as
+> opening a project: the folder *is* the game, and it carries its own
+> instructions for me. Once I'm in there I'll know how to run it, build it, test
+> it and publish it — none of which I know from here."
+
+If they're in a terminal, that's usually: close this session, `cd <name>`, and
+start the agent again. If they're in an editor or a desktop app, it's "open
+folder" / "open project" → `<name>` → new chat. Adapt it to their tool; you know
+what they're using and this page doesn't.
+
+That's the last step on this page. The next session takes it from there: it will
+boot the game and build it with them. They're already signed in, and the engine
+is already downloaded — so in there, `joystack dev` just runs.
+
+## What Joystack provides
+
+- **Multiplayer built in.** Rooms, presence, physics authority, identity.
+  Locally `joystack dev` runs the full stack; published games use the platform's.
+- **The engine.** A versioned library of game components and craft docs,
+  downloaded per game and pinned in package.json's `joystack.engine`. Upgrade when
+  you choose.
+- **Services.** LLM-driven NPCs and more, platform-authenticated. No API keys
+  to acquire, ever.
+- **Hosting.** `<name>.joystack.games`, instantly, from `joystack publish`.
+
+Your game's folder is yours: its own git repo, private if you like, hosted
+wherever you like (or nowhere). Joystack never needs to see your source beyond
+what you publish.

package/lib/setup.mjs

@@ -0,0 +1,9 @@
+// `joystack setup`: the guide an AI agent follows to create a creator's first
+// game folder and hand off into it. It ships inside this package, so an agent
+// reads it with one command it can run from any folder, signed in or not, and
+// the steps always match the `create` of the same release.
+import { readFileSync } from 'node:fs';
+
+export function setupGuide() {
+  return readFileSync(new URL('./setup-guide.md', import.meta.url), 'utf8');
+}

package/package.json

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