@homie-rocks/studio 0.30.2 → 0.31.1

package/lib/directory.mjs

@@ -5,24 +5,187 @@
  * nobody can list games under someone else's site.
  */
 import { request } from './net.mjs';
-import { listGames, readStudio, siteUrl } from './studio.mjs';
+import { listGames, readLocal, readStudio, siteUrl, writeLocal } from './studio.mjs';
 import { licenceProblems, readManifest } from './asset-manifest.mjs';
+import { partsPlanLines, partsPublishReport } from './parts-build.mjs';
 
-export async function publish(root, { homie, site } = {}) {
-  const studio = readStudio(root);
-  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
-  const url = site || siteUrl(root, studio);
-  // Licences first: a public game may ship only assets with a licence record that allows it.
+/*
+ * HOW MANY PUBLISHES ARE LEFT TODAY. In the beta the directory lets a studio publish only so many times a day, and
+ * the first a person heard of it was the refusal. The directory's answer is the only place the real number can come
+ * from, so `quotaOf` reads it wherever the directory puts it: a count in the body (`remaining`, `left`,
+ * `publishesLeft`, or those inside `quota` / `limits` / `rateLimit`), or the standard rate-limit headers
+ * (`ratelimit-remaining`, `x-ratelimit-remaining`, `retry-after`). What it finds is said after every publish.
+ *
+ * Before a publish, `publishBefore` asks the directory itself, with a read (GET /api/studio/publish?site=<origin>
+ * answers { ok, site, listed, limit, remaining, resetsAt } and changes nothing). When the directory cannot be
+ * reached, or is one that has no such read, it says so plainly and falls back to what THIS COMPUTER knows: how many
+ * it has sent today (UTC, the day the cap counts in), and what the directory said was left after the last one. That
+ * is a floor, never a promise: a publish from another computer or from the Homie connector is not counted here.
+ */
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : typeof v === 'string' && /^\d+$/.test(v.trim()) ? Number(v) : null);
+const first = (...values) => { for (const v of values) { const n = num(v); if (n !== null) return n; } return null; };
+const utcDay = (at = Date.now()) => new Date(at).toISOString().slice(0, 10);
+
+/** What the directory's answer says about the day's publishes: { remaining, limit, resetsAt, retryAfter }, each null when it did not say. */
+export function quotaOf(body, headers = null) {
+  const b = body && typeof body === 'object' ? body : {};
+  const nests = [b, b.quota, b.limits, b.limit, b.rateLimit, b.publishes, b.cap].filter((x) => x && typeof x === 'object');
+  const pick = (...keys) => first(...nests.flatMap((n) => keys.map((k) => n[k])));
+  const head = (k) => headers?.get?.(k) ?? null;
+  const reset = nests.map((n) => n.resetsAt ?? n.resetAt ?? n.reset).find((v) => typeof v === 'string' && !Number.isNaN(Date.parse(v))) ?? null;
+  return {
+    remaining: first(pick('remaining', 'left', 'publishesLeft', 'publishesRemaining'), head('ratelimit-remaining'), head('x-ratelimit-remaining')),
+    limit: first(pick('limit', 'max', 'perDay', 'daily', 'cap'), num(b.limit), head('ratelimit-limit'), head('x-ratelimit-limit')),
+    resetsAt: reset,
+    retryAfter: first(head('retry-after')),
+  };
+}
+
+/** Whether a refusal is the day's cap (a 429, or the directory's own words for it). */
+export function isPublishCap(sent) {
+  if (sent?.ok) return false;
+  const words = `${sent?.body?.error ?? ''} ${sent?.body?.code ?? ''} ${sent?.body?.message ?? ''} ${sent?.why ?? ''}`;
+  return sent?.status === 429 || /\b(daily|per day|today)\b.*\b(cap|limit|quota|publish)|\b(cap|limit|quota)\b.*\b(reached|exceeded|used up|hit)\b|too many publish|rate.?limit/i.test(words);
+}
+
+/** One sentence about the day's publishes, from the directory's own numbers when it gave any. */
+export function quotaLine(q, { sentToday = 0, refused = false } = {}) {
+  const when = q.resetsAt ? ` It resets at ${q.resetsAt}.` : q.retryAfter !== null ? ` Try again in ${q.retryAfter >= 120 ? `${Math.ceil(q.retryAfter / 60)} min` : `${q.retryAfter} s`}.` : refused ? ' The count is per UTC day: it resets at 00:00 UTC.' : '';
+  if (q.remaining !== null) return `Publishes left today: ${q.remaining}${q.limit !== null ? ` of ${q.limit}` : ''}.${when}`;
+  if (refused) return `The directory's daily publish cap for the beta is used up${q.limit !== null ? ` (${q.limit} a day)` : ''}.${when} Nothing is wrong with the studio: the listing it has stays as it is until then.`;
+  const mine = `This computer has sent ${sentToday} publish${sentToday === 1 ? '' : 'es'} today (UTC)`;
+  return `${mine}${q.limit !== null ? `, of the ${q.limit} a day the directory allows` : '; the directory has a daily cap in the beta and did not say how many are left'}.`;
+}
+
+/** What this computer knows before a publish: how many it sent today and what the directory last said was left. */
+export function publishesSoFar(root, now = Date.now()) {
+  const p = readLocal(root).publishes;
+  if (!p || p.day !== utcDay(now)) return { day: utcDay(now), sent: 0, remaining: null, limit: null };
+  return { day: p.day, sent: Number(p.sent) || 0, remaining: num(p.remaining), limit: num(p.limit) };
+}
+
+/** The line said BEFORE a publish goes out. */
+export function beforeLine(so) {
+  if (so.remaining !== null) return so.remaining > 0
+    ? `Publishing to the directory: it said ${so.remaining} publish${so.remaining === 1 ? ' was' : 'es were'} left today after the last one${so.limit !== null ? ` (of ${so.limit} a day)` : ''}.`
+    : `Publishing to the directory: it said none were left today after the last one${so.limit !== null ? ` (of ${so.limit} a day)` : ''}, so this one may be refused until 00:00 UTC.`;
+  return `Publishing to the directory: publish ${so.sent + 1} from this computer today (UTC). The beta has a daily cap; the directory's answer says how many are left when it gives the number.`;
+}
+
+/**
+ * The parts report for a listing: lib/parts-build.mjs partsPublishReport, for the games a listing shows (a private
+ * or invite-only game is not listed, so its parts are not this moment's question).
+ */
+export function partsForListing(root) {
+  const report = partsPublishReport(root);
+  const hidden = new Set(listGames(root).filter((g) => g.launch === 'private' || g.launch === 'invite').map((g) => g.id));
+  const games = report.games.filter((g) => !hidden.has(g.game));
+  return { ...report, games, ok: games.every((g) => g.ok) && !report.why };
+}
+
+/** The asset licence problems that stop a listing: a public game may ship only assets with a licence record that allows it. */
+function licenceRefusals(root) {
   const refused = [];
   for (const g of listGames(root)) {
     if (g.launch === 'private' || g.launch === 'invite') continue;
-    for (const p of licenceProblems(root, g.id, readManifest(root, g.id), { public: g.share?.source !== false })) if (p.level === 'refuse') refused.push({ game: g.id, ...p });
+    for (const p of licenceProblems(root, g.id, readManifest(root, g.id))) if (p.level === 'refuse') refused.push({ game: g.id, ...p });
   }
+  return refused;
+}
+
+/**
+ * `homie-studio publish --before` and the studio_publish tool's `before: true`, one code path: what a publish would
+ * meet, and NOTHING is published. It sends one GET (the directory's own read-only count for this site), never a
+ * POST, and writes no file, not even this computer's count. { ok: true, published: false, listed, publishes: {
+ * remaining, limit, resetsAt, sentToday, from: 'directory' | 'this computer', line }, parts?, refused? }, and
+ * `unreached: { why }` when the directory could not be asked. `ok` says the preflight ran, never that a publish
+ * would go through.
+ */
+export async function publishBefore(root, { homie, site, log = () => {}, fetchFn } = {}) {
+  const studio = readStudio(root);
+  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const url = site || siteUrl(root, studio);
+  const refused = licenceRefusals(root);
+  const parts = partsForListing(root);
+  const local = publishesSoFar(root);
+  const mine = `this computer has sent ${local.sent} publish${local.sent === 1 ? '' : 'es'} today (UTC)${local.remaining !== null ? `, and the directory said ${local.remaining === 0 ? 'none were' : `${local.remaining} ${local.remaining === 1 ? 'was' : 'were'}`} left after the last one${local.limit !== null ? ` (of ${local.limit} a day)` : ''}` : ''}; a publish from another computer or from the Homie connector is not counted here`;
+  let origin = null;
+  try { origin = url ? new URL(url).origin : null; } catch { origin = null; }
+  let asked = null;
+  if (origin) asked = await request(`${directory}/api/studio/publish?site=${encodeURIComponent(origin)}`, { method: 'GET', headers: { accept: 'application/json' } }, { timeout: 15_000, ...(fetchFn ? { fetchFn } : {}) });
+  const q = asked?.ok ? quotaOf(asked.body, asked.headers) : null;
+  const counted = Boolean(q && q.remaining !== null);
+  const listed = asked?.ok && typeof asked.body?.listed === 'boolean' ? asked.body.listed : null;
+  const why = !origin ? null : asked.ok ? 'it answered without a count' : String(asked.body?.message ?? asked.why ?? 'no answer').split('\n')[0];
+  const line = !origin
+    ? 'Not published. This studio has no live site yet, so there is nothing to list: put it online first (npm run deploy).'
+    : counted
+      ? `Not published. The directory says: this site is ${listed === true ? 'listed' : listed === false ? 'not listed yet' : 'known to it or not, it did not say'}; ${quotaLine(q).replace(/^P/, 'p')}`
+      : `Not published. The directory could not be asked how many publishes are left (${why}), so this is only what this computer knows: ${mine}.`;
+  const lines = [
+    line,
+    ...(refused.length ? [`A publish now would be refused: ${refused.length} asset licence problem${refused.length === 1 ? '' : 's'} (${refused.slice(0, 6).map((p) => `${p.game}/${p.asset}: ${p.problem}`).join('; ')}${refused.length > 6 ? '; …' : ''}). homie-studio assets check <id> says how to fix each.`] : []),
+    ...partsPlanLines(parts, { at: 'publish' }),
+  ];
+  for (const l of lines) log(l);
+  return {
+    ok: true, command: 'publish before', published: false, directory, site: url ?? null, listed,
+    publishes: { remaining: counted ? q.remaining : local.remaining, limit: (counted ? q.limit : null) ?? local.limit, resetsAt: q?.resetsAt ?? null, sentToday: local.sent, from: counted ? 'directory' : 'this computer', line },
+    ...(origin && !counted ? { unreached: { why, ...(asked.status !== undefined ? { status: asked.status } : {}) } } : {}),
+    ...(refused.length ? { refused } : {}),
+    ...(parts.games.length || parts.sharing.length || parts.why ? { parts } : {}),
+    lines,
+  };
+}
+
+export async function publish(root, { homie, site, log = () => {}, fetchFn } = {}) {
+  const studio = readStudio(root);
+  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const url = site || siteUrl(root, studio);
+  // Licences first: a public game may ship only assets with a licence record that allows it.
+  const refused = licenceRefusals(root);
   if (refused.length) return { ok: false, command: 'publish', refused, why: `not listed: ${refused.length} asset licence problem${refused.length === 1 ? '' : 's'}:\n${refused.map((p) => `  ${p.game}/${p.asset}: ${p.problem}${p.fix ? ` (${p.fix})` : ''}`).join('\n')}\nhomie-studio assets check <id> says the same; fix them, deploy, then publish again.` };
   if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
+  // Parts from other studios in the games about to be listed: their licences and credits, and plainly when two
+  // cannot be combined, in the same lines the deploy plan gave (lib/parts-build.mjs). Said before anything is sent.
+  // It does not stop the listing: the person decides, having been told.
+  const parts = partsForListing(root);
+  for (const line of partsPlanLines(parts, { at: 'publish' })) log(line);
+  const before = publishesSoFar(root);
+  log(beforeLine(before));
   const sent = await request(`${directory}/api/studio/publish`, {
     method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ site: url }),
-  }, { timeout: 30_000 });
+  }, { timeout: 30_000, ...(fetchFn ? { fetchFn } : {}) });
+  const quota = quotaOf(sent.body, sent.headers);
+  const capped = isPublishCap(sent);
+  // A request that reached the directory counts against the day whether it listed or not; one that never got
+  // there (no network) does not.
+  const reached = sent.ok || sent.status !== undefined;
+  const sentToday = before.sent + (reached ? 1 : 0);
+  try {
+    writeLocal(root, {
+      publishes: { day: before.day, sent: sentToday, remaining: quota.remaining ?? (capped ? 0 : null), limit: quota.limit ?? before.limit },
+      // That THIS computer listed the studio: what lets a later deploy ask the directory to read it again (the one
+      // deploy that withdraws the whole-game source an older toolkit offered), and never lists a studio that was not
+      // listed (a deploy alone lists nothing).
+      ...(sent.ok ? { listed: { at: new Date().toISOString(), site: url, directory } } : {}),
+    });
+  } catch { /* a read-only folder: the count is only a convenience */ }
+  // The day's limit, once the directory has said it, is remembered for the answers that leave it out.
+  const known = { ...quota, limit: quota.limit ?? before.limit };
+  const publishes = { ...known, sentToday, before: before.remaining, line: quotaLine(known, { sentToday, refused: capped }) };
   // The directory's own answer (what it listed, or why not), or the connection's error as it is.
-  return { ...(sent.body ?? {}), ok: sent.ok, command: 'publish', directory, site: url, ...(sent.ok ? {} : { why: sent.body?.message ?? sent.why, ...(sent.code ? { code: sent.code } : {}), ...(sent.needs ? { needs: sent.needs } : {}) }) };
+  return {
+    ...(sent.body ?? {}), ok: sent.ok, command: 'publish', directory, site: url, publishes,
+    ...(parts.games.length || parts.sharing.length || parts.why ? { parts } : {}),
+    ...(sent.ok ? {} : { why: `${sent.body?.message ?? sent.why}${capped ? `\n${publishes.line}` : ''}`, ...(sent.code ? { code: sent.code } : {}), ...(capped ? { needs: 'publish-cap' } : sent.needs ? { needs: sent.needs } : {}) }),
+  };
+}
+
+/** Whether this computer listed the studio at this site in this directory (lib/directory.mjs `publish` records it). */
+export function listedHere(root, { site = null, directory = null } = {}) {
+  const l = readLocal(root).listed;
+  if (!l?.at) return null;
+  const same = (a, b) => !a || !b || String(a).replace(/\/+$/, '') === String(b).replace(/\/+$/, '');
+  return same(l.site, site) && same(l.directory, directory) ? l : null;
 }

package/lib/doctor.mjs

@@ -4,15 +4,15 @@
  * unlocks, and the exact fix: one command the AI runs, or one page the person taps.
  *
  *   Node.js            required    the toolkit runs on it
- *   Homie connector    recommended the directory's search and remixes, the cards and notes to Homie (the AI says
+ *   Homie connector    recommended the directory's search, the cards and notes to Homie (the AI says
  *                                  whether its Homie tools are there: --connector yes|no). A session with a shell makes,
  *                                  deploys and lists a studio without it, so a missing connector never blocks. When
  *                                  the tools are missing and the app in use (Codex, Grok) has another MCP server named
  *                                  homie in its own config, the row says so: that name is the plugin's connector's
  *   Homie's holds      in Codex and Grok Build only: whether the plugin's hooks ran just now (they leave a dated
  *                                  mark, hooks/codex.mjs), so a session where nothing is held says so, and how to turn
- *                                  them on (Codex: trust them in /hooks; Grok Build 1.0.41 runs no plugin's hooks, so
- *                                  there the row is off until a Grok that runs them). The app is the one the AI names
+ *                                  them on (Codex: trust them in /hooks; Grok Build: trust the plugin, which
+ *                                  `grok plugin install … --trust` does). The app is the one the AI names
  *                                  (--client codex|grok) or its environment shows
  *   Cloudflare         to go online: signed in, and the account's email verified (Cloudflare checks that at the
  *                                  first deploy; a deploy that went through proves it)
@@ -263,7 +263,7 @@ export async function setupStatus({
     else { state = 'unknown'; detail = net.ok ? `${host} answers; your AI knows whether its Homie tools (studio_scaffold) are here` : `this computer's request to the directory failed: ${net.why}`; }
     rows.push({
       id: 'connector', label: 'Homie connector', need: 'recommended', state, detail,
-      unlocks: 'searching the homie.rocks directory and remixing a game from it, the cards where your app draws them, and notes to Homie; a session with a shell makes, deploys and lists a studio without it',
+      unlocks: 'searching the homie.rocks directory, the cards where your app draws them, and notes to Homie; a session with a shell makes, deploys and lists a studio without it',
       fix: state === 'ok' ? null : net.blocked
         ? { who: 'person', say: `In claude.ai/code, open this environment's settings, set Network access to Custom, add ${host} (keep the default package managers), and start a new session.` }
         : fixClash ?? (said === 'no' || net.ok ? fixConnector : null),
@@ -271,26 +271,27 @@ export async function setupStatus({
     });
   }
 
-  // Homie's holds, in Codex and Grok Build: Codex runs the plugin's hooks only once the person has trusted them, Grok
-  // Build 1.0.41 was seen to run no plugin's hooks at all, and neither app says so. The hooks leave a dated mark at
-  // every message and tool call; a fresh one means they are on. Off in Grok is Grok's doing, so it is said as that.
+  // Homie's holds, in Codex and Grok Build: each app runs a plugin's hooks only once the person has trusted them
+  // (Codex in /hooks, Grok by trusting the plugin), and neither says so when it skips them. The hooks leave a dated
+  // mark at every message and tool call; a fresh one means they are on. (0.30.2 said Grok runs no plugin's hooks.
+  // It does: the plugin's root manifest named no hooks file, so Grok loaded the Claude Code mod's and found none.)
   if (app === 'codex' || app === 'grok') {
     const name = APPS[app].name;
     const seen = holdsMark(app, { env, now: nowMs });
     const on = Boolean(seen && seen.ageMs <= HOLDS_FRESH_MS);
     rows.push({
-      // Off in Codex is the person's to fix now (trust the hooks); off in Grok is nothing they can fix.
-      id: 'holds', label: 'Homie\'s holds', need: 'recommended', state: on ? 'ok' : app === 'codex' ? 'act' : 'optional', on, app,
+      // Off is the person's to fix now, in either app: trust the hooks.
+      id: 'holds', label: 'Homie\'s holds', need: 'recommended', state: on ? 'ok' : 'act', on, app,
       detail: on ? `on: Homie's hooks ran in ${name} ${ago(seen.ageMs)} ago`
         : seen ? `off: Homie's hooks last ran in ${name} ${ago(seen.ageMs)} ago, and not for this session's calls`
-          : app === 'grok' ? 'off: Grok Build runs no plugin\'s hooks yet (1.0.41), so nothing is held in Grok' : `off: Homie's hooks have not run in ${name} on this computer`,
+          : `off: Homie's hooks have not run in ${name} on this computer`,
       ...(seen ? { seen: { at: new Date(seen.at).toISOString(), event: seen.event } } : {}),
       unlocks: 'a wait for your own "proceed <code>" before a production deploy, an edit to a file the studio protects, a Cloudflare change outside the deploy, a paid call past the budget and a model download; and secrets taken out of what your AI reads',
       fix: on ? null : {
         who: 'person',
         say: app === 'codex'
           ? 'In Codex, open /hooks and trust Homie\'s three hooks: Codex runs no plugin\'s hooks until you do. Then run this again. Until then nothing is held, so your AI asks you before each of those itself.'
-          : 'Nothing to do on your side: Grok Build 1.0.41 runs no plugin\'s hooks (none are registered in its headless and agent sessions, from any plugin; checked 2026-10-04), so Homie\'s holds are off in Grok. Nothing is held and no secret is taken out of what your AI reads, so your AI asks you before each of those itself. This row turns on by itself when a Grok that runs them leaves the hooks\' mark.',
+          : 'Grok runs a plugin\'s hooks only once the plugin is trusted, and only from a Homie plugin new enough to name them for Grok. Install it again with trust (grok plugin install homie-rocks/homie#plugins/homie --trust), start a new session (/hooks lists Homie\'s three), then run this again. Until then nothing is held, so your AI asks you before each of those itself.',
       },
     });
   }

package/lib/handoff.mjs

@@ -54,10 +54,6 @@ export function stepsFor(h, { games = [], client = 'chat' } = {}) {
     port: [
       `npx --no-install homie-studio port plan ${h.folder ? q(line(h.folder, 200)) : '<the game\'s folder>'}, then port import${id ? ` --id ${id}` : ''} (the plugin's port skill has the whole job).`,
     ],
-    remix: [
-      h.source && id ? `npx --no-install homie-studio game remix ${line(h.source, 300)} --id ${id}` : 'npx --no-install homie-studio game remix <source.json> --id <new id>',
-      'Then make it the brief\'s own.',
-    ],
     change: ['Make the change the brief asks for, in small steps.'],
   }[h.kind] ?? ['Do what the brief asks.'];
   return [
@@ -91,11 +87,11 @@ export async function handoff(root, build, { homie, client, fetchFn = globalThis
   const here = want ? (repoOf(root) ?? null)?.toLowerCase() ?? null : null;
   if (want && here && here !== want) return { ok: false, command: 'handoff', build, why: `this build is for ${body.repo}, but this session is in ${here}: open it in ${body.repo} (the card's Build it does), and change nothing here` };
   const h = {
-    kind: ['make', 'port', 'remix', 'change', 'setup'].includes(body.kind) ? body.kind : 'change',
+    kind: ['make', 'port', 'change', 'setup'].includes(body.kind) ? body.kind : 'change',
     what: ['game', 'song', 'video'].includes(body.what) ? body.what : 'game',
     title: line(body.title, 120), studio: line(body.studio, 60) || studio.name, brief: lines(body.brief, 1200),
     id: ID.test(String(body.id ?? '')) ? body.id : null, name: line(body.name, 60) || null, from: ID.test(String(body.from ?? '')) ? body.from : null,
-    source: /^https:\/\/\S{8,300}$/.test(String(body.source ?? '')) ? body.source : null, folder: line(body.folder, 200) || null,
+    folder: line(body.folder, 200) || null,
     setup: /^hs_[a-f0-9]{32}$/.test(String(body.setup ?? '')) ? body.setup : null,
   };
   let setup = null;

package/lib/library.mjs

@@ -157,7 +157,7 @@ export async function addFromLibrary(root, game, itemId, { as = null, height = n
     id, kind: item.kind === 'creature' ? 'creature' : item.kind, tier: item.tier ?? 'prop', card, route: 'library',
     from: { library: 'homie-starter', version: idx.version ?? 'v0', pack: item.pack, packLabel: idx.packs?.find((p) => p.id === item.pack)?.label ?? item.pack, packUrl: idx.packs?.find((p) => p.id === item.pack)?.url ?? null, item: item.id, author: item.author ?? null, origin: item.origin ?? null, sha256: item.files?.[0]?.sha256 ?? null, paletteSwap: Boolean(item.paletteSwap) },
     files,
-    license: { kind: 'cc0', spdx: 'CC0-1.0', owner: item.author ?? null, attribution: null, remix: 'include', notes: `From the Homie starter library (${item.pack}); the pack's own licence text: ${idx.packs?.find((p) => p.id === item.pack)?.licenseFile ?? 'licenses/'}` },
+    license: { kind: 'cc0', spdx: 'CC0-1.0', owner: item.author ?? null, attribution: null, notes: `From the Homie starter library (${item.pack}); the pack's own licence text: ${idx.packs?.find((p) => p.id === item.pack)?.licenseFile ?? 'licenses/'}` },
     measured: measured ? { tris: measured.triangles, materials: measured.materials, drawCalls: measured.drawCalls, textures: measured.textures.map((t) => ({ px: t.px, format: t.mimeType, gpuKB: Math.round(t.gpuBytes / 1024) })), bones: measured.bones, clips: measured.clips.length, heightM: measured.heightM, box: measured.box, glbKB: Math.round(files[0].bytes / 1024), flat: Boolean(item.paletteSwap) }
       : { tris: item.tris ?? null, materials: item.materials ?? null, drawCalls: item.drawCalls ?? null, bones: item.bones ?? 0, clips: (item.clips ?? []).length, heightM: item.heightM ?? null, box: item.box ? { size: item.box } : null, glbKB: Math.round((files[0]?.bytes ?? 0) / 1024), flat: Boolean(item.paletteSwap) },
     made: { steps: [{ what: 'library', item: item.id, sha256: item.files?.[0]?.sha256 ?? null }, ...(files[0]?.ops ? [{ what: 'optimise', tool: '@gltf-transform/functions', ops: files[0].ops }] : [])] },

package/lib/mcp-tools.mjs

@@ -2,7 +2,7 @@
  * THE LOCAL MCP SERVER'S TOOLS (`homie-studio mcp`, lib/mcp.mjs): the studio toolkit as MCP tools, so the Claude
  * desktop app (through the Homie extension), Claude Code or any MCP client builds games in the SAME chat that shows
  * the cards. Where a tool overlaps the remote Homie MCP (homie.rocks/mcp) it has the same name and the same input
- * shape: studio_scaffold, studio_card, game_make, game_remix, game_port, preview_run, studio_deploy,
+ * shape: studio_scaffold, studio_card, game_make, game_port, preview_run, studio_deploy,
  * studio_publish, build_open, build_progress, build_stop. The remote ones say what to run; these run it, here.
  *
  * Long work never holds a tool call: a check, a playtest, a deploy or an npm install starts as a job (lib/jobs.mjs)
@@ -28,7 +28,10 @@ import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs,
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
-import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl } from './studio.mjs';
+import { runningDev } from './dev.mjs';
+import { deployWords } from './deploy-state.mjs';
+import { partsForListing, publishBefore, publishesSoFar } from './directory.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
 import { pinnedVersion } from './upgrade.mjs';
@@ -37,6 +40,9 @@ import { detectLocalAi } from './local-ai.mjs';
 import { LAB_PORT, runningLab } from './lab.mjs';
 import { pictureFor } from './pictures.mjs';
 import { ART_UI, artToolDefs } from './art-tools.mjs';
+// GAME PARTS (parts/PARTS.md): parts_find, part_add, part_new and part_share are lib/parts-tools.mjs.
+import { PARTS_FIRST, partsToolDefs } from './parts-tools.mjs';
+import { partsPlanLines } from './parts-build.mjs';
 import { FEEDBACK_APPS, FEEDBACK_KINDS, FEEDBACK_LIMITS, appOf, cleanNote, draftId, noteBlock, sendNote, withLine } from './feedback.mjs';
 
 export const UI = Object.freeze({
@@ -285,12 +291,9 @@ function coverData(dir) {
   return null;
 }
 
+/** This studio's dev server when it really runs (lib/dev.mjs: a stale record, or a recycled process id, is not one). */
 function devOf(root) {
-  try {
-    const rec = JSON.parse(readFileSync(join(workerDir(root), '.wrangler', 'homie-dev.json'), 'utf8'));
-    process.kill(rec.pid, 0);
-    return { url: `http://127.0.0.1:${rec.port}`, port: rec.port, pid: rec.pid };
-  } catch { return null; }
+  try { return runningDev(root); } catch { return null; }
 }
 
 function published(root, kind) {
@@ -419,6 +422,10 @@ function buildCard(ctx, root, found) {
     feed.error ? `Last error: ${feed.error}` : null,
     ...(run?.look ? [`Pictures of the site (file_read shows one): ${run.look.join(', ')}`] : []),
     ...jobs.filter((j) => j.state === 'failed').map((j) => `${j.label} failed: ${j.result?.why ?? j.tail.slice(-2).join(' ')}`),
+    // A deploy that went through: which games it changed with each one's content hash, and anything it had to say
+    // about the studio's domain or the directory (lib/cloudflare.mjs).
+    ...jobs.filter((j) => j.result?.command === 'deploy' && j.result?.ok && (j.result.games ?? []).some((g) => g.hash)).map((j) => `Deployed: ${j.result.games.map((g) => `${g.id} ${deployWords(g)}`).join('; ')}.`),
+    ...jobs.filter((j) => j.result?.command === 'deploy').flatMap((j) => (j.result.notes ?? []).map((n) => `Note: ${n}`)),
     feed.state === 'running' ? 'The card on screen follows it live; you need not call this again to watch it.' : null,
   ].filter(Boolean).join('\n');
   // A check, playtest or deploy inside a build the person opened (build_open) ends before the build does: say so.
@@ -857,7 +864,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'game_make', title: 'Make a multiplayer game',
-      description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart), gem-rush-3d (the same arena in three.js, dressed with free CC0 models through @homie-rocks/studio/assets: the start for a 3D game), hero-rush-3d (the arena with animated CC0 heroes that run, jump and swing through @homie-rocks/studio/animate, a shared clip library per skeleton, a jump and a swing tuned in the Game Lab: the start for a 3D game with characters) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays.',
+      description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart), gem-rush-3d (the same arena in three.js, dressed with free CC0 models through @homie-rocks/studio/assets: the start for a 3D game), hero-rush-3d (the arena with animated CC0 heroes that run, jump and swing through @homie-rocks/studio/animate, a shared clip library per skeleton, a jump and a swing tuned in the Game Lab: the start for a 3D game with characters) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays. Before writing one of its systems from scratch, look for a piece of an existing game that does it (parts_find; part_add brings it in), and for the general mechanism in the @homie-rocks/* packages.',
       inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens): its address'), name: str('The game\'s display name'), from: str('Starter id (default gem-rush)'), ...STUDIO_ARG }, required: ['id', 'name'] },
       annotations: { title: 'Make a game', ...RW },
       run: async (a) => {
@@ -883,24 +890,6 @@ export function toolDefs(ctx, avail = {}) {
         return ok(`games/${a.id} is ${a.name}, from the ${a.from ?? 'gem-rush'} starter (${(r.result?.files ?? []).length} files).${got}${install} Change it in games/${a.id}/src/main.ts: file_read it once (a long file in two or three reads), decide every change, and make them in ONE file_edit with an edits list (never a call per change: twenty single edits use up a turn before the game is checked); then build and preview_run; check proves two browsers finish a round.`, { kind: 'game', ...r.result });
       },
     },
-    {
-      name: 'game_remix', title: 'Remix a shared game',
-      description: 'Bring a game another studio shared in the Homie directory into this studio as a new game of its own. The original stays credited: game.json remixOf says "Remix of <game> by <studio>" with a link back, shown on the new game\'s landing and in its credits. A game whose owner\'s licence says no remix is refused.',
-      inputSchema: { type: 'object', properties: { game: str('The directory game: "<studio site>/<game id>" or its play URL'), id: str('The new game id in this studio'), name: str('Optional: its new name'), ...STUDIO_ARG }, required: ['game', 'id'] },
-      annotations: { title: 'Remix a game', ...RW, openWorldHint: true },
-      run: async (a) => {
-        const root = ctx.root(a.studio);
-        let site; let gameId;
-        try { const u = new URL(String(a.game ?? '')); site = u.origin; gameId = u.pathname.split('/').filter(Boolean)[0]; } catch { return fail('game is "<studio site>/<game id>" or its play URL'); }
-        if (!/^https:\/\//.test(site) || !GAME_ID.test(String(gameId ?? '')) || !GAME_ID.test(String(a.id ?? ''))) return fail('game is "https://<studio site>/<game id>", and id a new lowercase id');
-        const source = `${site}/games/${gameId}/source.json`;
-        const r = await cli(ctx, root, `game remix ${a.id}`, ['game', 'remix', source, '--id', a.id, ...(a.name ? ['--name', String(a.name).slice(0, 60)] : [])]);
-        if (!r.ended) return stillRunning(r.job, 'The remix');
-        if (r.job.code !== 0) return fail(`Not remixed: ${whyOf(r.job)}`);
-        const credit = r.result?.credit ? ` Its game.json credits the original: "${r.result.credit}"${r.result.page ? ` (${r.result.page})` : ''}, on its landing and in its credits; keep it.` : '';
-        return ok(`games/${a.id} is a remix of ${site}/${gameId} (${(r.result?.files ?? []).length} files).${credit}`, { kind: 'game', ...r.result });
-      },
-    },
     {
       name: 'game_port', title: 'Make an existing game multiplayer',
       description: 'Read an existing single-player web game on this computer and grade how hard making it multiplayer will be (easy, medium, hard, not a fit, with its risks); with id, also bring it into the studio as games/<id>/ for the port. studio_guide { "topic": "port" } has the whole job; check (and studio_run ["port","check",…]) proves it.',
@@ -928,7 +917,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'game_plan', title: 'Plan a game (its Game Codex)',
-      description: 'Step 4: start the game\'s Game Codex (games/<id>/CODEX.md, every section) and get the plan interview to run with the person: two or three questions a message, each with options and your pick, about game type and genre, style, devices, players and rooms, art and film, music and sound, and scope. A game is planned before it is made: with no game <id> yet, this starts its folder with only the codex. Fill CODEX.md from their answers in one call (file_write of the whole file, or one file_edit with an edits list), then game_codex shows it.',
+      description: 'Step 4: start the game\'s Game Codex (games/<id>/CODEX.md, every section) and get the plan interview to run with the person: two or three questions a message, each with options and your pick, about game type and genre, style, devices, players and rooms, art and film, music and sound, and scope. A game is planned before it is made: with no game <id> yet, this starts its folder with only the codex. Fill CODEX.md from their answers in one call (file_write of the whole file, or one file_edit with an edits list), then game_codex shows it. While planning, run `parts find` (the parts_find tool) for each system the game needs, so the plan starts from pieces of existing games and the @homie-rocks/* packages rather than from nothing; the codex\'s Built from section records what was found.',
       inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens)'), name: str('Its name, when the game is not made yet'), ...STUDIO_ARG }, required: ['id'] },
       annotations: { title: 'Plan a game', ...RW },
       run: async (a) => {
@@ -943,6 +932,7 @@ export function toolDefs(ctx, avail = {}) {
         return ok([
           made ? `Wrote games/${a.id}/CODEX.md (every section${made.planned ? '; the game is planned here before it is made' : ''}).` : `games/${a.id}/CODEX.md is there already: change it, never replace it.`,
           'Now the interview: two or three questions a message, each with concrete options and your pick, so "yes" is an answer. Say back what you heard in one line before the next. Stop after three or four rounds; "just build it" means fill the rest with your own choices and list them under Open questions. Then fill CODEX.md in one call (file_read it once; then file_write the whole file, or one file_edit whose edits list has every section) and show it with game_codex.',
+          '', PARTS_FIRST,
           ...(guide ? ['', guide] : []),
         ].join('\n'), { kind: 'plan', id: a.id, file: `games/${a.id}/CODEX.md`, created: Boolean(made) });
       },
@@ -977,7 +967,8 @@ export function toolDefs(ctx, avail = {}) {
         if (!r.ended) return stillRunning(r.job, 'The build');
         if (r.job.code !== 0) return fail(`The build failed: ${whyOf(r.job)}`);
         const g = r.result?.games ?? [];
-        return ok(`Built ${g.length ? g.map((x) => `${x.id} (${Math.round(x.bytes / 1024)} KB)`).join(', ') : 'the home page (no game yet)'}.${devOf(root) ? ' Reload the preview to see it.' : ''}`, { kind: 'built', ...r.result });
+        // Each game's build hash, in the words the terminal prints: the hash a deploy reports and the live site answers with.
+        return ok(`Built ${g.length ? g.map((x) => `${x.id} (${Math.round(x.bytes / 1024)} KB${x.hash ? `, ${x.changed ?? 'new'}${x.changed && x.changed !== 'new' ? ' since the last build here' : ''}, build ${x.hash}` : ''})`).join(', ') : 'the home page (no game yet)'}.${devOf(root) ? ' Reload the preview to see it.' : ''}`, { kind: 'built', ...r.result });
       },
     },
     {
@@ -1008,7 +999,9 @@ export function toolDefs(ctx, avail = {}) {
       run: async (a) => {
         const root = ctx.root(a.studio);
         const r = await cli(ctx, root, 'dev --stop', ['dev', '--stop'], { wait: 20_000 });
-        return ok(r.result?.stopped?.length ? 'Stopped the studio\'s site here.' : 'It was not running.', { kind: 'preview', stopped: r.result?.stopped ?? [] });
+        // What a server stopped another way left behind is cleaned up and said (lib/dev.mjs).
+        const note = r.result?.why && (r.result?.stale || r.result?.stopped?.length) ? ` ${r.result.why[0].toUpperCase()}${r.result.why.slice(1)}.` : '';
+        return ok(`${r.result?.stopped?.length ? 'Stopped the studio\'s site here.' : 'It was not running.'}${note}`, { kind: 'preview', stopped: r.result?.stopped ?? [], ...(r.result?.stale ? { stale: true } : {}) });
       },
     },
     {
@@ -1092,7 +1085,7 @@ export function toolDefs(ctx, avail = {}) {
     {
       name: 'studio_deploy', title: 'Put the studio online',
       description: 'Put the studio\'s site online on the studio\'s OWN Cloudflare account: one Worker, one D1 database and two Durable Objects, free plan, no payment method. Call it with plan: true first and tell the person in two or three lines what it creates and costs. If Cloudflare is not signed in, cloudflare_login opens it in their browser to approve once. Runs in the background with the build card.',
-      inputSchema: { type: 'object', properties: { plan: { type: 'boolean', description: 'Only say what it will create and what it costs; change nothing' }, ...STUDIO_ARG } },
+      inputSchema: { type: 'object', properties: { plan: { type: 'boolean', description: 'Only say what it will create and what it costs; change nothing' }, ownRoute: { type: 'boolean', description: 'Only after the plan or a deploy warned that another site\'s route on the studio\'s custom domain covers its hostname, and the person agreed: add the studio\'s own exact-host route (the one line the warning gives) and deploy. It never edits or removes any other route' }, ...STUDIO_ARG } },
       annotations: { title: 'Put the studio online', readOnlyHint: false, destructiveHint: false, openWorldHint: true }, _meta: ui(UI.build),
       run: async (a) => {
         const root = ctx.root(a.studio);
@@ -1102,10 +1095,10 @@ export function toolDefs(ctx, avail = {}) {
           if (!r.ended) return stillRunning(r.job, 'The deploy plan');
           if (r.job.code !== 0) return fail(whyOf(r.job));
           const p = r.result;
-          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
+          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, ...(p.parts ? partsPlanLines(p.parts) : []), ...(p.zone?.warning ? [`Warning (say this to the person as it is): ${p.zone.warning}`] : p.zone?.why ? [p.zone.why] : []), 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
         }
         const studio = readStudio(root);
-        return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy'] }] });
+        return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy', ...(a.ownRoute === true ? ['--own-route'] : [])] }] });
       },
     },
     {
@@ -1126,15 +1119,26 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_publish', title: 'List the studio in the Homie directory',
-      description: 'List a deployed studio\'s games, songs and videos in the homie.rocks directory, with their Play links (at most 12 games per studio in the beta).',
-      inputSchema: { type: 'object', properties: { site: str('Optional: the live site address (default: the one deploy got)'), ...STUDIO_ARG } },
+      description: 'List a deployed studio\'s games, songs and videos in the homie.rocks directory, with their Play links (at most 12 games per studio in the beta). The beta also caps how many times a studio may publish in a day: the answer says how many are left when the directory gives the number, and before: true publishes nothing: it asks the directory how many are left and whether the site is listed (a read), and says so plainly when the directory cannot be reached.',
+      inputSchema: { type: 'object', properties: { site: str('Optional: the live site address (default: the one deploy got)'), before: { type: 'boolean', description: 'Publish nothing: ask the directory (a read) whether this site is listed and how many publishes are left today, and say the parts\' licence lines. When the directory cannot be reached it says so, with what this computer has sent today' }, ...STUDIO_ARG } },
       annotations: { title: 'List in the directory', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio);
+        // The parts in the games a listing shows, in the deploy plan's own lines (licences, credits, and plainly when
+        // two cannot be combined): said before the studio is listed, and again with the answer.
+        const partsNow = partsForListing(root);
+        const partsSaid = partsPlanLines(partsNow, { at: 'publish' });
+        // before: true is `publish --before`, the same function the terminal runs (lib/directory.mjs publishBefore):
+        // the directory's read-only count for this site, the parts' lines, and nothing published. Run here, by THIS
+        // toolkit, never handed to the studio's pinned one: a 0.31.0 toolkit reads `publish --before` as `publish`.
+        if (a.before === true) {
+          const b = await publishBefore(root, { site: a.site ? String(a.site) : undefined });
+          return ok(b.lines.join('\n'), { kind: 'publish-count', ...publishesSoFar(root), ...b });
+        }
         const r = await cli(ctx, root, 'publish', ['publish', ...(a.site ? ['--site', String(a.site)] : [])]);
         if (!r.ended) return stillRunning(r.job, 'Listing');
-        if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`);
-        return ok(`Listed: ${r.result?.studioPage ?? r.result?.directory ?? ''}\n${(r.result?.games ?? []).map((g) => `  ${g.name}: ${g.play}`).join('\n')}`, { kind: 'publish', ...r.result });
+        if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`, r.result?.publishes ? { kind: 'publish', ok: false, needs: r.result.needs ?? null, publishes: r.result.publishes } : undefined);
+        return ok(`Listed: ${r.result?.studioPage ?? r.result?.directory ?? ''}\n${(r.result?.games ?? []).map((g) => `  ${g.name}: ${g.play}`).join('\n')}${r.result?.publishes?.line ? `\n${r.result.publishes.line}` : ''}${partsSaid.length ? `\n${partsSaid.join('\n')}` : ''}`, { kind: 'publish', ...r.result });
       },
     },
     {
@@ -1184,7 +1188,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_run', title: 'Run a studio command',
-      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
+      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["shoot","<id>","--preview"], ["build","--types"], ["assets","use","<id>","<asset>","unused"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
       inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' }, description: 'The command\'s words after `homie-studio`' }, ...STUDIO_ARG }, required: ['args'] },
       annotations: { title: 'Run a studio command', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
@@ -1361,6 +1365,7 @@ export function toolDefs(ctx, avail = {}) {
   ];
   // Art direction, the cast, the starter library, generated props, checks, the lineup and the rights (lib/art-tools.mjs).
   tools.push(...artToolDefs(ctx, { ok, fail, cli, stillRunning, whyOf, needsInstall, ui, str, STUDIO_ARG, RO, RW, pictureFor, findNode, startJob, waitJob }));
+  tools.push(...partsToolDefs(ctx, { ok, fail, str, STUDIO_ARG, RO, RW }));
   const topics = guideTopics(ctx);
   if (topics.length) {
     tools.push({

package/lib/mcp.mjs

@@ -38,7 +38,7 @@ A new studio follows one checklist, in order and never ahead. Show it in your fi
 1. The studio (studio_scaffold): it has NO game; its home page says "First game coming soon".
 2. See a working game (game_demo): a live game on Homie Arcade with its Play link, nothing copied in. Copy a starter in (game_make) only if they ask.
 3. One small change from one sentence of theirs: to the copied game, or to the studio's home (site/theme.json colours, a tagline in studio.json, a first post in posts/). Then build and preview_run, and they reload.
-4. Plan their game (game_plan): a short interview, two or three questions a message with options and your pick; then fill games/<id>/CODEX.md and show it (game_codex).
+4. Plan their game (game_plan): a short interview, two or three questions a message with options and your pick; then fill games/<id>/CODEX.md and show it (game_codex). Look for pieces first: the @homie-rocks/* packages for general mechanisms, and parts_find for pieces other studios shared (part_add brings one in).
 5. Build it: build_open, then game_make under the planned id (the codex stays), file edits (few and large: one file_edit carries every change to a file in its edits list, never a call per change), build, preview_run, check. The card follows every build.
 6. Playtest it (playtest), then put it online: studio_deploy with plan: true first (say what it creates and costs, free), cloudflare_login when not signed in (they approve once in their browser), studio_deploy, then studio_publish.
 If they ask for everything at once, show the list, make your own choices for steps 2 to 4 in one line each, and go on.