@joystack/cli 0.1.48 → 0.1.50

package/CHANGELOG.md

@@ -14,6 +14,35 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.50] - 2026-10-11
+
+### Changed
+
+- `joystack setup` tells your agent that `create` makes an empty game, ready
+  to be built, rather than a working game to reshape.
+
+## [0.1.49] - 2026-10-10
+
+### Added
+
+- `joystack land <name>` puts a lane's work into your game and removes the
+  lane, from the game folder or from inside the lane. It saves the lane's
+  unsaved work first. When the lane and the game changed the same lines, it
+  stops with the merge in progress and lists the files; once the merge is
+  settled and committed, run it again to remove the lane.
+
+### Changed
+
+- In the Joystack maker, `joystack lane`, `dev`, `publish` and `land` answer
+  for the maker: the folder is already the conversation's lane, its game is
+  already running on the person's page, and publishing does what the page's
+  Publish button does. On your own computer they work as before.
+
+### Fixed
+
+- On Windows, exporting a replay no longer fails now and then with `EPERM`
+  while another program still has the file it just wrote open.
+
 ## [0.1.48] - 2026-10-10
 
 ### Added

package/bin/joystack.mjs

@@ -6,6 +6,8 @@
 import { dev } from '../lib/dev.mjs';
 import { agentSessionFromEnv } from '../lib/agent-session.mjs';
 import { lane } from '../lib/lane.mjs';
+import { land } from '../lib/land.mjs';
+import { MAKER_DEV, MAKER_LANE, makerDraft, makerPublish } from '../lib/maker.mjs';
 import { login, logout, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
@@ -38,6 +40,7 @@ Usage:
   joystack assets <id> --sheet  Draw a view sheet of a 3D asset to .joystack/sheets/ (--help: options)
   joystack assets --json [<id>…]  Print each asset's parameters, measured stats and flags as JSON
   joystack lane <name>          Open an isolated copy of the game to experiment in, safely
+  joystack land <name>          Put a lane's work into the game, then remove the lane
   joystack test [aspect]        Run targeted checks (no aspect: conservative full run)
   joystack test --since <base>  Submission: ordinary + triggered extended checks
   joystack test --all           Explicit full audit; add --list to preview selection
@@ -72,6 +75,10 @@ its own.
 try {
   switch (cmd) {
     case 'dev': {
+      if (makerDraft()) {
+        console.log(MAKER_DEV);
+        break;
+      }
       const handle = await dev({ port: flag('port') ? Number(flag('port')) : undefined, share: rest.includes('--share'), reload: !rest.includes('--no-reload'), agentSession: agentSessionFromEnv() });
       const shutdown = () => {
         handle.stop();
@@ -188,12 +195,24 @@ try {
       break;
     }
     case 'lane': {
+      if (makerDraft()) {
+        console.log(MAKER_LANE);
+        break;
+      }
       const name = rest.find((a) => !a.startsWith('--'));
       if (!name) throw new Error('Name the lane: joystack lane <name>  (e.g. joystack lane judder)');
       const { dir } = await lane(name);
       console.log(`\nWork in it:\n  cd ${dir} && npx joystack dev\n`);
       break;
     }
+    case 'land': {
+      if (makerDraft()) {
+        await makerPublish(makerDraft());
+        break;
+      }
+      await land(rest.find((a) => !a.startsWith('--')));
+      break;
+    }
     case 'setup':
       process.stdout.write(setupGuide());
       break;
@@ -272,6 +291,10 @@ try {
       break;
     }
     case 'publish':
+      if (makerDraft()) {
+        await makerPublish(makerDraft(), { slug: flag('slug') });
+        break;
+      }
       await publish({ slug: flag('slug'), devTools: rest.includes('--dev-tools'), open: rest.includes('--open') });
       break;
     case 'feedback':

package/lib/create.mjs

@@ -1,14 +1,15 @@
 // `joystack create <name>` — bootstrap a standalone Joystack game.
 //
 // The create-next-app gesture: one command → a complete folder that is its
-// own repo, where `joystack dev` immediately serves a WORKING multiplayer game
-// (the platform is not optional — the scaffold joins a room on line one, no
-// "add multiplayer later" tier). The folder name is the slug.
+// own repo, where `joystack dev` immediately serves the game: an empty one, so
+// the first game anyone sees in it is the one they asked for. It is
+// multiplayer from line one (its world.js turns the room on, and `joystack
+// dev` runs one from its first start). The folder name is the slug.
 //
 // ── Where the creator's files come from ─────────────────────────────────────
 //
 // EVERYTHING a creator receives comes from the versioned engine artifact: the
-// starter game (`scaffold/`) and the agent surface (`agent-surface/` — skills
+// skeleton every game starts as (`scaffold/`) and the agent surface (`agent-surface/` — skills
 // plus the Layer-0 managed block). This npm package ships CODE ONLY.
 //
 // Shipping a second copy of the surface (a `template/` folder) inside this
@@ -39,7 +40,8 @@ import { ensureEngine } from './engine.mjs';
 import { reconcileAgentSurface } from './agent-surface.mjs';
 import { readEnv } from './legacy-names.mjs';
 
-// The starter game, inside the installed engine artifact.
+// The skeleton every new game starts as, inside the installed engine artifact.
+// The example games beside it (`examples/`) are read in place, never copied.
 export const SCAFFOLD_DIR = 'scaffold';
 
 const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
@@ -81,7 +83,7 @@ const PLAYWRIGHT_SPEC = '1.64.0';
 // devDependency, exactly like playwright. `joystack test` also runs it.
 const ESLINT_SPEC = '^10.7.0';
 
-// Copy the starter game out of the artifact. One rename: `gitignore` →
+// Copy the skeleton out of the artifact. One rename: `gitignore` →
 // `.gitignore` (npm pack silently strips .gitignore files from a package, so
 // the artifact stores it dot-less).
 function copyScaffold(engineDir, dir, name, version) {
@@ -140,7 +142,7 @@ async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, rec
     runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
   }
 
-  // The engine — and with it the starter game and the agent skills. Signs the
+  // The engine — and with it the skeleton and the agent skills. Signs the
   // creator in via the device flow if this machine has no token yet, and writes
   // the `joystack.engine` pin.
   const engine = await ensure(dir, { apiBase, log });

package/lib/dev.mjs

@@ -110,7 +110,17 @@ 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, devLogPath = null } = {}, onFailure) {
+//
+// `shareIsOwner` is for a host that serves the share link to the creator
+// alone and keeps everyone else off the dev tools' routes (the Joystack
+// maker): a report sent through the link then counts as one from this
+// machine, so it can wake the agent and read its reply.
+//
+// `pollMs` is how often, in milliseconds, the game's files are compared for
+// changes the operating system's events miss (live-versions.mjs); left unset
+// it is that module's default of one second. Tests pass a shorter one so a
+// save is acted on sooner.
+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, shareIsOwner = false, devLogPath = null, pollMs } = {}, 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).
@@ -322,6 +332,7 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     log, // agent-inbox report lines ride the dev logger
     engineVersion: engine.version ?? null, // stamped on agent-inbox reports
     agentSession, // woken by agent-inbox reports sent from this machine
+    shareIsOwner, // and by those sent through the share link, when it is the creator's alone
     mounts: mountsFor(codeDir),
     ...(first ? { fixedBuild: first.build } : {}),
     versions: live ? {
@@ -539,6 +550,7 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     versions = createLiveVersions({
       first,
       auto: reload,
+      ...(pollMs ? { intervalMs: pollMs } : {}),
       log,
       snapshot: sourceFiles,
       make: (o) => makeVersion(o),

package/lib/land.mjs

@@ -0,0 +1,63 @@
+// `joystack land <name>`: put a lane's work into the game, then remove the
+// lane (the /worktree skill, "Land the winner").
+//
+// Run from the game folder or from inside the lane. The lane's unsaved work
+// is saved first, since landing is what the creator asked for. The game
+// folder then merges the lane's branch. On a clean merge the lane's folder
+// and branch go; on a clash the merge is left in progress in the game folder,
+// with the rule for settling it, and running `land` again once it is settled
+// and committed removes the lane.
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { isLane } from './lane.mjs';
+import { findProject } from './project.mjs';
+
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+export const CLASH_RULE =
+  'Keep both changes wherever both can be kept. Stop and ask the creator only where the two truly ' +
+  'contradict, in game terms ("both versions change how jumping feels"), never in git terms.';
+
+export async function land(name, { cwd = process.cwd(), log = console.log } = {}) {
+  if (!name) throw new Error('Name the lane: joystack land <name>  (the name it was opened with: joystack lane <name>)');
+  const here = findProject(cwd).dir;
+  const main = isLane(here) ? findProject(dirname(git(here, 'rev-parse', '--path-format=absolute', '--git-common-dir'))).dir : here;
+  const slug = findProject(main).slug;
+  const branch = `lane/${name}`;
+  const dir = resolve(main, '..', `${slug}-${name}`);
+  try {
+    git(main, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`);
+  } catch {
+    throw new Error(`There is no lane called "${name}" (no branch ${branch}).`);
+  }
+
+  if (existsSync(dir) && git(dir, 'status', '--porcelain')) {
+    git(dir, 'add', '-A');
+    git(dir, 'commit', '-q', '-m', `save: lane ${name}`);
+    log(`→ saved       the lane's unsaved work (${branch})`);
+  }
+
+  if (git(main, 'diff', '--name-only', '--diff-filter=U')) {
+    throw new Error(`The game folder ${main} is still in the middle of a merge. Settle it and commit, then run joystack land ${name} again.\n${CLASH_RULE}`);
+  }
+  try {
+    git(main, 'merge', '--no-edit', branch);
+  } catch (err) {
+    const clashed = git(main, 'diff', '--name-only', '--diff-filter=U');
+    if (!clashed) throw new Error(`Landing ${branch} failed: ${String(err.stderr || err.message).trim()}`);
+    throw new Error(
+      `Landing ${branch} clashed with the game in:\n${clashed.split('\n').map((f) => `  ${f}`).join('\n')}\n` +
+        `The merge is in progress in ${main}. ${CLASH_RULE}\n` +
+        `Then commit the merge, and run joystack land ${name} again to remove the lane.`,
+    );
+  }
+  log(`→ landed      ${branch} into the game`);
+
+  if (existsSync(dir)) {
+    git(main, 'worktree', 'remove', dir);
+    log(`→ removed     ${dir}`);
+  }
+  git(main, 'branch', '-d', branch);
+  return { dir, branch };
+}

package/lib/maker.mjs

@@ -0,0 +1,63 @@
+// The commands that answer differently inside the Joystack maker.
+//
+// The maker is a web page around the same agent a creator runs in a game
+// folder: it gives each conversation a lane of its own (a "draft"), runs that
+// lane's dev server on the person's page, and has a Publish button that puts
+// the draft in the game and the game online. Its agent reads the same
+// AGENTS.md and skills as anyone, so it runs the same commands. These answer
+// for the maker instead of doing what they do on a laptop, where they would
+// open a lane the person never sees, start a server nobody looks at, or
+// publish behind the page's back.
+//
+// The maker sets JOYSTACK_MAKER on the agent's process: the address of its
+// own control API for this conversation's draft. Only the agent's commands
+// carry it, never the dev servers the maker starts itself.
+
+export function makerDraft(env = process.env) {
+  const at = String(env.JOYSTACK_MAKER ?? '').trim().replace(/\/+$/, '');
+  return at || null;
+}
+
+export const MAKER_LANE =
+  "You are in the Joystack maker: this folder is already this conversation's lane " +
+  '(the person sees it as a draft on their page). Build here. No new lane was made.';
+
+export const MAKER_DEV =
+  "You are in the Joystack maker: this folder's dev server is already running, and the " +
+  'person plays the game on their page, beside the chat. Every file you save shows up ' +
+  'there. Nothing was started.';
+
+// `publish` and `land` both do what the page's Publish button does: the draft
+// goes into the game, and the game goes online under the name it has. The
+// maker does it once the agent's turn ends, since it merges the files the
+// agent is still working in. A game that has never been online has no name
+// yet; the person picks one on the page.
+export async function makerPublish(at, { slug = null, log = console.log, fetchImpl = fetch } = {}) {
+  if (slug) {
+    throw new Error(
+      'You are in the Joystack maker: a game here has one name, which the person picks on their page, ' +
+        'so --slug copies are not available. Run the command without --slug to publish under that name.',
+    );
+  }
+  let res;
+  try {
+    res = await fetchImpl(`${at}/publish`, { method: 'POST', signal: AbortSignal.timeout(15_000) });
+  } catch (err) {
+    throw new Error(`You are in the Joystack maker, and it did not answer (${err?.message ?? err}). Ask the person to press Publish on their page.`);
+  }
+  const body = await res.json().catch(() => ({}));
+  if (body.needsName) {
+    throw new Error(
+      'You are in the Joystack maker, and this game has never been published: its first publish needs ' +
+        'a name, which the person picks. Ask them to press Publish on their page.',
+    );
+  }
+  if (!res.ok || !body.ok) {
+    throw new Error(`You are in the Joystack maker, and it could not publish: ${body.error ?? `HTTP ${res.status}`}. Ask the person to press Publish on their page.`);
+  }
+  log(
+    'You are in the Joystack maker: publishing this draft. When this turn ends, it goes into the game ' +
+      `and the game goes online${body.url ? ` at ${body.url}` : ''}. The person sees it happen on their page.`,
+  );
+  return body;
+}

package/lib/replay-export.mjs

@@ -1064,7 +1064,7 @@ function rowSink({ file, columns, rowsPerGroup }) {
     finish() {
       flush();
       pq.finish();
-      renameSync(partial, file);
+      renameInto(partial, file);
       return rows;
     },
     // Called when the run did not get that far. Best-effort: a leftover
@@ -1075,6 +1075,21 @@ function rowSink({ file, columns, rowsPerGroup }) {
   };
 }
 
+// On Windows a file that was just written can be refused a rename for a moment
+// (EPERM, EBUSY or EACCES) while another process still has it open. The
+// rename is retried for up to two seconds before it fails.
+function renameInto(from, to) {
+  for (let i = 0; ; i++) {
+    try {
+      renameSync(from, to);
+      return;
+    } catch (err) {
+      if (i >= 40 || !['EPERM', 'EBUSY', 'EACCES'].includes(err.code)) throw err;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+  }
+}
+
 /** A streaming Parquet writer for a table of `columns`, sized as the export sizes its own. */
 export function rowSinkFor(file, columns, rowsPerGroup) {
   return rowSink({ file, columns, rowsPerGroup: groupFor(columns, rowsPerGroup) });

package/lib/setup-guide.md

@@ -47,8 +47,9 @@ published URL slug, so it must be **lowercase letters, numbers and dashes**
 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 scaffolds `<name>/` as its own git repo: an empty game that runs, ready
+for the next session to build, 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

package/lib/static-server.mjs

@@ -337,6 +337,9 @@ export function createStaticServer({
   // in agent-session.mjs), or null. When set, an agent-inbox report from this
   // machine also wakes that session.
   agentSession = null,
+  // Whether a request through the share link is the creator's own (startDev's
+  // `shareIsOwner`): its agent-inbox reports then count as from this machine.
+  shareIsOwner = false,
 }) {
   // The tunnel hostname `joystack dev --share` opened to this server, once it is
   // up (setShareHost). See trustedHost.
@@ -858,6 +861,9 @@ export function createStaticServer({
     return turn;
   };
   const agentConnected = () => (sessionAlive(agentSession) ? agentSession.agent : null);
+  // The creator's own browser: on this machine, or through a share link that
+  // only the creator can reach the dev tools by.
+  const fromCreator = (req) => fromThisMachine(req) || (shareIsOwner && isShareHost(req.headers.host, shareHost));
 
   // The reply credential: this server's port and a bearer token, readable only
   // by the owner of the game folder, one file per server, so with two servers
@@ -890,7 +896,7 @@ export function createStaticServer({
       res.writeHead(403, { 'Content-Type': 'text/plain' });
       return res.end('cross-origin post rejected');
     }
-    const local = fromThisMachine(req);
+    const local = fromCreator(req);
     const maxBytes = local ? AGENT_INBOX_LOCAL_MAX_BYTES : AGENT_INBOX_MAX_BYTES;
     const chunks = [];
     let size = 0;
@@ -986,7 +992,7 @@ export function createStaticServer({
   // so only this machine may read its replies. The custom header forces a CORS
   // preflight, which this server never grants, so no foreign page can read it.
   function handleInboxStatus(req, res) {
-    if (!fromThisMachine(req) || !sameOrigin(req, { shareHost }) || req.headers['x-joystack-agent-ui'] !== '1') {
+    if (!fromCreator(req) || !sameOrigin(req, { shareHost }) || req.headers['x-joystack-agent-ui'] !== '1') {
       res.writeHead(403, { 'Content-Type': 'text/plain' });
       return res.end('dev tools only');
     }

package/package.json

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