@joystack/cli 0.0.0-stage → 0.1.43

package/lib/feedback-sync.mjs

@@ -0,0 +1,231 @@
+// `joystack feedback` — the back-channel half. The send half
+// (feedback.mjs) ships reports OUT; this module brings the conversation BACK:
+//
+//   1. Push replies. A report file can carry a `## Reply (unsent)` section —
+//      the agent writes one when something about the outcome still needs
+//      doing. It ships to /api/creator/feedback/reply and the heading is
+//      stamped with the returned fu_ id, so it never ships twice.
+//   2. Fetch outcomes. /api/creator/feedback/status returns, for every report
+//      this account filed: its status (read / done / discarded), the engine
+//      version a fix landed in, and the update thread. Everything is stamped
+//      back INTO the report file — `status:` / `resolved-in:` in frontmatter,
+//      unseen updates appended under `## Updates` — so the file under
+//      notes/feedback/ IS the thread, readable offline by any agent.
+//
+// Idempotency is by fu_ id: every update written into the file carries its
+// `fu_<16 hex>` marker (in an HTML comment, or on a sent-reply heading), and
+// anything whose id already appears in the file is never appended again.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { findProject } from './project.mjs';
+import { DEFAULT_API_BASE, getApiBase, getToken } from './config.mjs';
+import { discoverSent } from './feedback.mjs';
+import { compareVersions } from './changelog.mjs';
+
+const UPDATE_ID = /fu_[0-9a-f]{16}/g;
+const UNSENT_REPLY = /^## Reply \(unsent\)\s*$/m;
+
+// Every unsent reply section: the text between a `## Reply (unsent)` heading
+// and the next `## ` heading (or EOF). A `## ` line inside a ``` / ~~~ fence
+// is CONTENT, not a boundary — replies quote markdown evidence, and stopping
+// at a fenced heading would ship half the reply and strand the rest under an
+// already-stamped heading where it can never be sent.
+export function extractUnsentReplies(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^## Reply \(unsent\)\s*$/.test(lines[i])) continue;
+    const body = [];
+    let fenced = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^(```|~~~)/.test(lines[j])) fenced = !fenced;
+      else if (!fenced && /^## /.test(lines[j])) break;
+      body.push(lines[j]);
+    }
+    out.push({ body: body.join('\n').trim() });
+  }
+  return out;
+}
+
+export function knownUpdateIds(text) {
+  return new Set(text.match(UPDATE_ID) ?? []);
+}
+
+// Upsert `status:` / `resolved-in:` into the frontmatter block. The report was
+// stamped `sent:` + `id:` when it shipped, so a synced file always has
+// frontmatter; a file without one is left alone. CRLF files (a Windows clone
+// with autocrlf) get their line endings preserved.
+export function applyStatus(text, { status, resolved_in }) {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!fm) return text;
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  let block = fm[1];
+  const upsert = (key, value) => {
+    if (value == null) return;
+    const line = `${key}: ${value}`;
+    if (new RegExp(`^${key}:.*$`, 'm').test(block)) block = block.replace(new RegExp(`^${key}:[^\\r\\n]*`, 'm'), line);
+    else block = `${block}${eol}${line}`;
+  };
+  upsert('status', status);
+  upsert('resolved-in', resolved_in);
+  return text.slice(0, fm.index) + `---${eol}${block}${eol}---` + text.slice(fm.index + fm[0].length);
+}
+
+// Append unseen thread updates under `## Updates` (created at EOF if missing).
+// Each entry carries its fu_ marker; `knownIds` is what makes re-runs no-ops.
+//
+// The body is written as a BLOCKQUOTE, not raw markdown. That is a protocol
+// necessity, not styling: this file is re-parsed by the reply/section regexes
+// on every sync, so a message that merely QUOTES a heading like "## Reply
+// (unsent)" must not become one — raw injection would ship the team's own
+// words back as a creator reply (reopening the report it arrived on).
+export function appendUpdates(text, updates, knownIds) {
+  const fresh = updates.filter((u) => !knownIds.has(u.id));
+  if (fresh.length === 0) return { text, appended: 0 };
+
+  let entries = '';
+  for (const u of fresh) {
+    const who = u.author === 'creator' ? 'You' : 'Joystack';
+    const when = new Date(u.created_at * 1000).toISOString().slice(0, 10);
+    const quoted = u.body.split('\n').map((l) => (l.trim() ? `> ${l}` : '>')).join('\n');
+    entries += `\n### ${who} — ${when} <!-- ${u.id} -->\n\n${quoted}\n`;
+  }
+
+  // New entries go at the END OF THE SECTION, not the end of the file: once a
+  // reply section exists below `## Updates`, appending at EOF would interleave
+  // platform messages under the creator's reply and the thread stops reading
+  // in order.
+  const lines = text.split('\n');
+  const head = lines.findIndex((l) => /^## Updates\s*$/.test(l));
+  if (head === -1) {
+    return { text: `${text.trimEnd()}\n\n## Updates\n${entries}`, appended: fresh.length };
+  }
+  let end = lines.length;
+  for (let j = head + 1; j < lines.length; j++) {
+    if (/^## /.test(lines[j])) { end = j; break; }
+  }
+  const section = lines.slice(0, end).join('\n').trimEnd();
+  const rest = lines.slice(end).join('\n');
+  return {
+    text: `${section}\n${entries}${rest ? `\n${rest}` : ''}`,
+    appended: fresh.length,
+  };
+}
+
+// Which reports landed in the versions an engine update just crossed:
+// (from, to], or everything at/below `to` when no previous pin exists.
+// `status` must still be done — a report reopened after its fix shipped keeps
+// the resolved_in stamp as history, but announcing it as "landed" would claim
+// a fix the reply just said didn't hold.
+export function landedIn(reports, { from, to }) {
+  return reports.filter(
+    (r) =>
+      r.status === 'done' &&
+      r.resolved_in &&
+      compareVersions(r.resolved_in, to) <= 0 &&
+      (!from || compareVersions(r.resolved_in, from) > 0),
+  );
+}
+
+export async function fetchStatus({ apiBase, fetchImpl = fetch }) {
+  const token = getToken();
+  if (!token) throw new Error('reading feedback status requires login — run `joystack login` first.');
+  const res = await fetchImpl(`${apiBase}/api/creator/feedback/status`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) throw new Error(`feedback status fetch failed (HTTP ${res.status})`);
+  const { reports } = await res.json();
+  return Array.isArray(reports) ? reports : [];
+}
+
+async function pushReplies({ path, id, apiBase, fetchImpl, log }) {
+  let text = readFileSync(path, 'utf8');
+  let sent = 0;
+  // One at a time: each stamp rewrites the first unsent heading, so the next
+  // loop iteration sees the next reply (if any) as the new first.
+  while (UNSENT_REPLY.test(text)) {
+    const [reply] = extractUnsentReplies(text);
+    if (!reply?.body) {
+      log(`⚠️  ${basename(path)} has an empty "## Reply (unsent)" section — write the reply, then rerun.`);
+      break;
+    }
+    const token = getToken();
+    const res = await fetchImpl(`${apiBase}/api/creator/feedback/reply`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ id, body: reply.body }),
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '');
+      throw new Error(`reply send failed for ${basename(path)} (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+    }
+    const { id: updateId } = await res.json();
+    text = text.replace(UNSENT_REPLY, `## Reply (sent ${new Date().toISOString()}, ${updateId})`);
+    writeFileSync(path, text);
+    sent += 1;
+    log(`↩️  Sent your reply on ${basename(path)} → ${updateId}`);
+  }
+  return sent;
+}
+
+// The whole sync: replies out, outcomes in. Fails soft on nothing-to-do (no
+// sent reports → silent no-op, no login needed); fails LOUD on a send error,
+// leaving the reply unsent so the next run retries it.
+export async function syncFeedback({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  fetchImpl = fetch,
+} = {}) {
+  const project = findProject(cwd);
+  const sentFiles = discoverSent(project.dir);
+  if (sentFiles.length === 0) return { replies: 0, updated: [] };
+
+  if (!getToken()) throw new Error('syncing feedback requires login — run `joystack login` first.');
+
+  // A failing reply must not rob the OTHER reports of their outcomes: push
+  // everything, stamp everything, and only THEN re-throw the first failure —
+  // loud (so the run is visibly not clean) but after the useful work. The
+  // failed reply's heading is still `(unsent)`, so the next run retries it.
+  let replies = 0;
+  let replyError = null;
+  for (const f of sentFiles) {
+    try {
+      replies += await pushReplies({ ...f, apiBase, fetchImpl, log });
+    } catch (err) {
+      replyError ??= err;
+    }
+  }
+
+  // Fetch-and-stamp is best-effort: the send half already succeeded, and a
+  // platform without the endpoint (or a transient failure) must not turn a
+  // delivered report into an apparent failure. The replies stay loud.
+  let reports;
+  try {
+    reports = await fetchStatus({ apiBase, fetchImpl });
+  } catch (err) {
+    log(`(could not check your reports' outcomes right now — ${err.message} They'll sync on the next run.)`);
+    if (replyError) throw replyError;
+    return { replies, updated: [] };
+  }
+  const byId = new Map(reports.map((r) => [r.id, r]));
+
+  const updated = [];
+  for (const { path, id } of sentFiles) {
+    const report = byId.get(id);
+    if (!report) continue;
+    const before = readFileSync(path, 'utf8');
+    let text = applyStatus(before, report);
+    const { text: withUpdates, appended } = appendUpdates(text, report.updates ?? [], knownUpdateIds(text));
+    text = withUpdates;
+    if (text === before) continue;
+    writeFileSync(path, text);
+    updated.push({ file: path, id, status: report.status, resolved_in: report.resolved_in, newUpdates: appended });
+
+    const landed = report.resolved_in ? ` — landed in ${report.resolved_in}` : '';
+    const news = appended ? ` (+${appended} update${appended === 1 ? '' : 's'})` : '';
+    log(`📬 ${basename(path)}: ${report.status}${landed}${news}`);
+  }
+  if (replyError) throw replyError;
+  return { replies, updated };
+}

package/lib/feedback.mjs

@@ -0,0 +1,209 @@
+// `joystack feedback` — send the reports under notes/feedback/ to the Joystack team
+// (the transport behind the template's /feedback skill).
+//
+// Target: /api/creator/feedback — the token-authenticated intake beside
+// creator/publish. Each unsent notes/feedback/*.md ships VERBATIM as the
+// report body (frontmatter, transcript excerpt and all — the agent authors
+// it rich on purpose), with the repo's identity attached: slug, the
+// joystack.engine pin, and this CLI's version. A delivered file is stamped
+// `sent:` + `id:` in its frontmatter so it never ships twice; a failed send
+// leaves the file unstamped and is retried on the next run.
+import { readdirSync, readFileSync, writeFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { basename, join, resolve, relative, isAbsolute, sep } from 'node:path';
+import { findProject } from './project.mjs';
+import { DEFAULT_API_BASE, getApiBase, getToken } from './config.mjs';
+import { gameConfig } from './legacy-names.mjs';
+
+const CLI_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+// Attachment caps. The riven report cited game.js:56 and riven-render.js:302 —
+// source files, not screenshots — so attachments are TEXT. Kept well under the
+// intake's own ceiling so an oversized set is caught HERE, with a readable
+// message: Cloudflare replaces a Pages Function's 5xx body with its own HTML
+// page, which would reach the creator as an unreadable wall.
+export const MAX_ATTACHMENTS = 20;
+export const MAX_ATTACHMENT_BYTES = 256 * 1024; // per file
+export const MAX_ATTACHMENTS_BYTES = 1024 * 1024; // all of them together
+
+// CRLF-tolerant: a Windows clone with autocrlf rewrites these files, and a
+// frontmatter that stops matching means a sent report reads as unsent and is
+// re-filed on every run.
+const frontmatter = (text) => /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? '';
+
+// A report is "sent" when its frontmatter carries a `sent:` stamp.
+function isSent(text) {
+  return /^sent:\s*\S/m.test(frontmatter(text));
+}
+
+// `attachments:` in the report's frontmatter, in either YAML shape agents write:
+//
+//   attachments:          attachments: [game.js, src/render.js]
+//     - game.js
+//     - src/render.js
+export function parseAttachments(text) {
+  const fm = frontmatter(text);
+  const inline = /^attachments:\s*\[(.*)\]\s*$/m.exec(fm);
+  if (inline) {
+    return inline[1]
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+  const block = /^attachments:\s*$/m.exec(fm);
+  if (!block) return [];
+  const out = [];
+  for (const line of fm.slice(block.index).split('\n').slice(1)) {
+    const item = /^\s*-\s*(.+?)\s*$/.exec(line);
+    if (!item) break; // the list ends at the first non-item line
+    out.push(item[1].replace(/^['"]|['"]$/g, ''));
+  }
+  return out;
+}
+
+// The agent chooses this list, so it is arbitrary filesystem read access over a
+// network. Every path must land inside the game folder — resolved, not merely
+// inspected, because a symlink's string looks innocent. An escape is a hard
+// error, never a skipped file.
+function readAttachments(projectDir, paths, reportName) {
+  if (paths.length > MAX_ATTACHMENTS) {
+    throw new Error(
+      `${reportName} lists ${paths.length} attachments (max ${MAX_ATTACHMENTS}) — attach only the files the diagnosis rests on.`,
+    );
+  }
+
+  const root = realpathSync(projectDir);
+  const inside = (candidate) => candidate === root || candidate.startsWith(root + sep);
+  const escaped = (p, resolved) => {
+    throw new Error(
+      `${reportName} attaches "${p}", which resolves outside the game folder (${resolved}). ` +
+        `Feedback may only attach files from this game.`,
+    );
+  };
+
+  const files = [];
+  let total = 0;
+
+  for (const p of paths) {
+    // Containment is checked BEFORE existence, and on the lexical path first:
+    // "../../.ssh/id_rsa" is refused for what it asks for, not for whether it
+    // happens to be there. Then again after realpath — a symlink's string looks
+    // perfectly innocent.
+    const full = resolve(root, p);
+    if (isAbsolute(p) || !inside(full)) escaped(p, full);
+
+    let real;
+    try {
+      real = realpathSync(full);
+    } catch {
+      throw new Error(`${reportName} attaches "${p}", which does not exist in the game folder.`);
+    }
+    if (!inside(real)) escaped(p, real);
+    if (!statSync(real).isFile()) throw new Error(`${reportName} attaches "${p}", which is not a file.`);
+
+    const bytes = statSync(real).size;
+    if (bytes > MAX_ATTACHMENT_BYTES) {
+      throw new Error(
+        `${reportName} attaches "${p}" (${Math.round(bytes / 1024)} KiB) — too large, the per-file cap is ${MAX_ATTACHMENT_BYTES / 1024} KiB.`,
+      );
+    }
+    total += bytes;
+    if (total > MAX_ATTACHMENTS_BYTES) {
+      throw new Error(
+        `${reportName}'s attachments are too large together (over ${MAX_ATTACHMENTS_BYTES / 1024} KiB) — attach fewer files.`,
+      );
+    }
+
+    const content = readFileSync(real, 'utf8');
+    if (content.includes('\0')) {
+      throw new Error(`${reportName} attaches "${p}", which is not a text file. Attach source, logs, or config.`);
+    }
+    // Report the path the creator wrote (project-relative), not the real one —
+    // it is what the report's prose cites.
+    files.push({ path: relative(root, real).split(sep).join('/'), content });
+  }
+  return files;
+}
+
+function titleOf(text, path) {
+  const h1 = /^#\s+(.+)$/m.exec(text);
+  return h1 ? h1[1].trim() : basename(path, '.md');
+}
+
+function stamp(text, id) {
+  const lines = `sent: ${new Date().toISOString()}\nid: ${id}`;
+  if (/^---\r?\n/.test(text)) return text.replace(/^---\r?\n/, (m) => `${m}${lines}\n`);
+  return `---\n${lines}\n---\n${text}`;
+}
+
+export function discoverUnsent(projectDir) {
+  const dir = join(projectDir, 'notes', 'feedback');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => join(dir, name))
+    .filter((path) => !isSent(readFileSync(path, 'utf8')))
+    .sort();
+}
+
+// Delivered reports, with the id the platform stamped into each — what the
+// back-channel (feedback-sync.mjs) replies on and fetches outcomes for.
+export function discoverSent(projectDir) {
+  const dir = join(projectDir, 'notes', 'feedback');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => join(dir, name))
+    .sort()
+    .flatMap((path) => {
+      const id = /^id:\s*(fb_[0-9a-f]{16})\s*$/m.exec(frontmatter(readFileSync(path, 'utf8')))?.[1];
+      return id ? [{ path, id }] : [];
+    });
+}
+
+export async function sendFeedback({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+} = {}) {
+  const project = findProject(cwd);
+  const unsent = discoverUnsent(project.dir);
+  if (unsent.length === 0) {
+    log('Nothing to send — no unsent reports under notes/feedback/.');
+    return { sent: [] };
+  }
+
+  const token = getToken();
+  if (!token) throw new Error('sending feedback requires login — run `joystack login` first.');
+
+  const sent = [];
+  for (const path of unsent) {
+    const body = readFileSync(path, 'utf8');
+    // Read + guard the attachments BEFORE the request: a bad path must fail the
+    // send outright, leaving the report unstamped and retryable.
+    const files = readAttachments(project.dir, parseAttachments(body), basename(path));
+    const report = {
+      title: titleOf(body, path),
+      body,
+      slug: project.slug,
+      engine: gameConfig(project.pkg).engine,
+      cli: CLI_VERSION,
+      ...(files.length ? { files } : {}),
+    };
+    const res = await fetch(`${apiBase}/api/creator/feedback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(report),
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '');
+      throw new Error(`feedback send failed for ${basename(path)} (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+    }
+    const { id } = await res.json();
+    writeFileSync(path, stamp(body, id));
+    const withFiles = files.length ? ` (+${files.length} file${files.length === 1 ? '' : 's'})` : '';
+    log(`✅ Sent ${basename(path)}${withFiles} → ${id}`);
+    sent.push({ file: path, id, files: files.map((f) => f.path) });
+  }
+  log(`${sent.length} report${sent.length === 1 ? '' : 's'} delivered to the Joystack team.`);
+  return { sent };
+}

package/lib/freeze.mjs

@@ -0,0 +1,108 @@
+// `joystack dev --no-reload`: the game as it is at startup, for the whole run.
+//
+// The dev server reads a game's files from disk on every request and rebuilds
+// its room when they change, so switching the watchers off alone does not
+// freeze anything: a page opened after an edit gets the edited files, while the
+// room and the injected entity layout stay as they were, and an edit that adds
+// an entity makes that page fail to boot. Freezing therefore serves, and builds
+// the room from, a copy of the game taken once at startup.
+import { constants, cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { basename, join } from 'node:path';
+import { gameBuild } from './build-id.mjs';
+import { STATE_DIR_NAMES, stateDir } from './legacy-names.mjs';
+
+// Left out of the copy: recordings and generated build output (.joystack), which
+// are written to the real folder or regenerated into the copy; git history;
+// and installed packages, which the copy links to instead, since they do not
+// change while the creator edits the game.
+const LEFT_OUT = new Set([...STATE_DIR_NAMES, '.git', 'node_modules']);
+
+// Where copies live: inside the game's own .joystack, so a copy is on the same
+// disk as the game (cloned rather than copied, on a filesystem that clones)
+// and outside everything the build id and publish read. Each run's copy is
+// named `<pid>-<random>`, so a copy whose process is gone can be told apart
+// from one a running `joystack dev` is serving.
+export function frozenRoot(gameDir) {
+  return join(stateDir(gameDir), 'frozen');
+}
+
+/**
+ * Copies the game at `dir` into `.joystack/frozen/<pid>-<random>/<folder name>`.
+ * `build` is the game's build at the moment of the copy, the one every session
+ * played on the copy is stamped with. `remove()` deletes the copy; it also runs
+ * when the process exits normally, and a copy whose process died without
+ * running it is swept by the next freeze of the same game.
+ *
+ * Symlinks inside the game are copied as what they point to, so a linked
+ * folder is frozen with the rest.
+ * @param {string} dir
+ * @returns {{ dir: string, build: object, remove: () => void }}
+ */
+export function freezeGame(dir) {
+  sweepStale(dir);
+  const build = gameBuild(dir);
+  const run = join(frozenRoot(dir), `${process.pid}-${randomBytes(3).toString('hex')}`);
+  // The folder name is the game's slug unless package.json names one, so the
+  // copy keeps it.
+  const copy = join(run, basename(dir));
+  const modulesLink = join(copy, 'node_modules');
+  let removed = false;
+  const remove = () => {
+    if (removed) return;
+    removed = true;
+    process.off('exit', remove);
+    // The link first, on its own: on Windows it is a junction, and a recursive
+    // delete that followed it would empty the game's real node_modules.
+    try { unlinkSync(modulesLink); } catch { /* never made */ }
+    rmSync(run, { recursive: true, force: true });
+  };
+  process.on('exit', remove);
+  try {
+    mkdirSync(copy, { recursive: true });
+    // Entry by entry, because the copy lives inside the game (under .joystack),
+    // and a copy of a folder into its own subfolder is refused outright.
+    for (const entry of readdirSync(dir)) {
+      if (LEFT_OUT.has(entry)) continue;
+      cpSync(join(dir, entry), join(copy, entry), { recursive: true, dereference: true, mode: constants.COPYFILE_FICLONE });
+    }
+    const modules = join(dir, 'node_modules');
+    if (existsSync(modules)) symlinkSync(modules, modulesLink, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (err) {
+    remove();
+    throw err;
+  }
+  return { dir: copy, build, remove };
+}
+
+// Deletes the copies of runs whose process no longer exists: a `joystack dev`
+// killed outright (a closed terminal, a crash) never ran its cleanup.
+function sweepStale(dir) {
+  const root = frozenRoot(dir);
+  let runs;
+  try { runs = readdirSync(root); } catch { return; }
+  for (const name of runs) {
+    const pid = Number(/^(\d+)-/.exec(name)?.[1]);
+    // This process's own runs are removed by their own remove().
+    if (pid && (pid === process.pid || alive(pid))) continue;
+    const run = join(root, name);
+    for (const game of safeList(run)) {
+      try { unlinkSync(join(run, game, 'node_modules')); } catch { /* not a link, or absent */ }
+    }
+    rmSync(run, { recursive: true, force: true });
+  }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists but belongs to someone else.
+    return err.code === 'EPERM';
+  }
+}
+
+function safeList(dir) {
+  try { return readdirSync(dir); } catch { return []; }
+}

package/lib/game-files.mjs

@@ -0,0 +1,99 @@
+// The files that make up a game: what `joystack publish` uploads, and what a
+// build id (build-id.mjs) is the hash of. One definition, so the id a
+// recording carries and the files a publish ships can never describe
+// different sets.
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { STATE_DIR_NAMES } from './legacy-names.mjs';
+
+// Never shipped: tooling, VCS, agent workspace, notes + handbook + agent
+// instructions (repo knowledge travels with the repo, not the catalog — a
+// published game must not expose it on a public URL), tests/smokes.
+//
+// This list is the floor, not the whole rule: whatever the game's own
+// .gitignore excludes is dropped as well (gitIgnored below). Name-based lists
+// can only ever cover the names somebody thought of, and the folder that
+// prompted this was `screenshots/` — dev captures a test run had left behind,
+// gitignored by the creator and published to their public URL regardless.
+const SKIP_DIRS = new Set(['node_modules', 'notes', 'handbook', '.git', ...STATE_DIR_NAMES, '.claude', '__pycache__']);
+const SKIP_FILES = [
+  /^package(-lock)?\.json$/,
+  /\.(test|smoke)\.(js|mjs|ts)$/,
+  /^\.DS_Store$/,
+  /^gamedev\.toml$/,
+  /^(AGENTS|CLAUDE|GEMINI)\.md$/,
+];
+
+// What the creator's own .gitignore excludes, out of a list of candidate paths.
+//
+// A gitignored path is the creator saying, in the file they already maintain for
+// exactly this, that it is not part of the game — build output, scratch, and the
+// screenshots a test run left behind. Publishing it puts it on a public URL
+// under their name, which is nobody's intent.
+//
+// One `git check-ignore` call for the whole list rather than one per file, and
+// NUL-delimited so a path with a space or a newline in it survives. A folder
+// that is not a git repo, or a machine with no git, has no .gitignore to apply,
+// and the list goes through untouched. A git that fails any other way — it
+// hangs, or answers more than fits — throws: going on would publish the very
+// files the .gitignore was written to keep out.
+export function gitIgnored(dir, rels) {
+  if (!rels.length) return new Set();
+  try {
+    const out = execFileSync('git', ['check-ignore', '--stdin', '-z'], {
+      cwd: dir,
+      input: `${rels.join('\0')}\0`,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: 30_000,
+      maxBuffer: 256 * 1024 * 1024,
+    });
+    return new Set(out.split('\0').filter(Boolean));
+  } catch (err) {
+    // Exit 1 means "nothing on the list is ignored"; git still wrote stdout.
+    if (err?.status === 1) return new Set((err.stdout ?? '').split('\0').filter(Boolean));
+    // No git installed, or not a repository (git exits 128).
+    if (err?.code === 'ENOENT' || err?.status === 128) return new Set();
+    throw new Error(`could not read the game's .gitignore: git check-ignore failed (${err?.code ?? err?.signal ?? err?.status ?? err?.message})`);
+  }
+}
+
+/**
+ * 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
+ * reader holding a path the walk never visited (a deleted file in `git
+ * status`) asks this.
+ */
+export function isGameFilePath(rel) {
+  const parts = String(rel).split('/');
+  const name = parts.pop();
+  if (!name || name.startsWith('.') || SKIP_FILES.some((re) => re.test(name))) return false;
+  return parts.every((d) => d && !SKIP_DIRS.has(d) && !d.startsWith('.'));
+}
+
+export function collectGameFiles(dir) {
+  const found = new Map(); // relative path → absolute path
+  const walk = (d) => {
+    for (const name of readdirSync(d)) {
+      const p = join(d, name);
+      const rel = relative(dir, p).split('\\').join('/');
+      if (statSync(p).isDirectory()) {
+        if (SKIP_DIRS.has(name) || name.startsWith('.')) continue;
+        walk(p);
+      } else {
+        if (name.startsWith('.') || SKIP_FILES.some((re) => re.test(name))) continue;
+        found.set(rel, p);
+      }
+    }
+  };
+  walk(dir);
+
+  const ignored = gitIgnored(dir, [...found.keys()]);
+  const out = new Map(); // relative path → Buffer
+  for (const [rel, p] of found) {
+    if (ignored.has(rel)) continue;
+    out.set(rel, readFileSync(p));
+  }
+  return out;
+}