@homie-rocks/studio 0.50.5 → 0.50.7

package/lib/app-ready.mjs

@@ -0,0 +1,49 @@
+/** One arrival barrier for baseline proof, needs reloads and rebuilt frames. */
+export async function appReady(surface, {timeout=60000}={}) {
+  const end=Date.now()+timeout;
+  let error;
+  do {
+    try {
+      await surface.page.waitForFunction(() => {
+        const cover=document.querySelector('[data-arrive]');
+        return window.__shell?.link?.state==='online' && window.__shell?.arrival?.phase==='done' && (!cover || (getComputedStyle(cover).opacity==='0' && getComputedStyle(cover).visibility==='hidden'));
+      },{timeout:Math.max(1,end-Date.now())});
+      const frame=surface.page.frames().find(f=>/\/__game\//.test(f.url()));
+      if(!frame)throw new Error('app frame missing');
+      await frame.evaluate(()=>new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve))));
+      surface.frame=frame;return;
+    } catch(e) {error=e;if(!/context|detach|navigat|frame missing/i.test(e.message))break;}
+  } while(Date.now()<end);
+  throw new Error(`${surface.name}: waiting for online app, arrival phase done, hidden [data-arrive], and two frames: ${error?.message}`);
+}
+/** Installed before any app script. Observes actual platform calls, without faking their outcome. */
+export function observeEffects() {
+  window.__homieNeedsEffects=[];
+  const record=(effect,name)=>window.__homieNeedsEffects.push({effect,name});
+  addEventListener('homie-effect',e=>{if(e.detail?.effect)record(e.detail.effect,e.detail.name);});
+  const wrap=(obj,key,effect,name)=>{const original=obj?.[key];if(typeof original!=='function')return;try{obj[key]=function(...args){record(effect,typeof name==='function'?name(args):name);return Reflect.apply(original,this,args);};}catch{}};
+  wrap(globalThis.AudioScheduledSourceNode?.prototype,'start','sound','audio');
+  wrap(globalThis.HTMLMediaElement?.prototype,'play','sound','media');
+  wrap(navigator,'vibrate','haptic','vibrate');
+  if(globalThis.Notification) {const Original=Notification;globalThis.Notification=new Proxy(Original,{construct(target,args){record('notification',String(args[0]));return Reflect.construct(target,args);}});}
+  wrap(globalThis.ServiceWorkerRegistration?.prototype,'showNotification','notification',args=>String(args[0]));
+}
+
+/** Retry reads after navigation; never repeat a dispatched click or record mutation. */
+export async function waitInApp(surface,label,read,{ready=appReady,timeout=60000}={}) {
+ const end=Date.now()+timeout;
+ for(;;) {
+  try {return await read(surface.frame);}
+  catch(error) {
+   if(Date.now()>=end||!/context.*destroy|detach|navigat|cannot find context/i.test(error.message))throw new Error(`${surface.name}: waiting for ${label}: ${error.message}`);
+   await ready(surface,{timeout:Math.max(1,end-Date.now())});
+  }
+ }
+}
+export function answerDialogs(page,surface,dialogs,report) {
+ page.on('dialog',async dialog=>{
+  const item={surface,type:dialog.type(),message:dialog.message(),answer:'accepted'};dialogs.push(item);
+  report?.check?.('dialog-'+dialogs.length,'pass',{note:`${surface}: automatically accepted ${item.type}: ${item.message}`});
+  await dialog.accept().catch(()=>{});
+ });
+}

package/lib/build.mjs

@@ -513,7 +513,7 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   if (Object.hasOwn(studio, 'referrals')) log('studio.json referrals: ignored; Homie has no referral system.');
   if (listGames(root).some(g => isRulesGame(g) && g.room?.host !== 'browser' && g.room?.host !== 'offline')) await (await import('./rules-wiring.mjs')).ensureRulesWiring(root);
   await (await import('./tools-build.mjs')).buildTools(root, esbuild);
-  await (await import('./functions-build.mjs')).buildFunctions(root, esbuild);
+  await (await import('./functions-build.mjs')).buildFunctions(root, esbuild, { log });
   // The shop first (shop/SHOP.md): invalid shop settings stop the build before anything is built.
   const shop = shopForBuild(root, { log });
   const live = join(root, 'site', 'dist');

package/lib/check.mjs

@@ -1,3 +1,6 @@
+import {randomBytes} from 'node:crypto';
+import {appReady,observeEffects,waitInApp,answerDialogs} from './app-ready.mjs';
+import {localCredential,localCookie} from './local-test.mjs';
 import { readAppNeeds, proveAppNeeds, saveAppNeeds } from './app-needs.mjs';
 /**
  * `homie-studio check [<game>] [--url <site> | --live]` — the promise, measured (where it runs and on which games
@@ -128,7 +131,7 @@ export function judgeRounds(browsers, missed = new Map()) {
   return null;
 }
 
-export async function check({ root = null, url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
+export async function check({ isolate = true, root = null, url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
   if (!url || !game) throw new Error('usage: homie-studio check <game> --url <site url>');
   const base = String(url).replace(/\/+$/, '');
   const play = `${base}/${game}/play`;
@@ -149,7 +152,7 @@ export async function check({ root = null, url, game, roundTimeoutMs = 150_000,
   if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
-  if (appMeta) return checkApp({ root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
+  if (appMeta) return checkApp({ isolate, root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
   if (shots) mkdirSync(shots, { recursive: true });
   const profiles = [];
   const browsers = [];
@@ -344,59 +347,72 @@ export async function check({ root = null, url, game, roundTimeoutMs = 150_000,
 }
 
 /** Apps prove a real action crossing surfaces and a reconnect, without inventing a round. */
-export async function checkApp({ root = null, url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
+export async function checkApp({ isolate = true, root = null, url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
   let plan;
   try { plan = readAppNeeds(root, game); } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
-  const proof = meta.check;
-  if (!proof || typeof proof.action !== 'string' || typeof proof.observe !== 'string') return { ok: false, command: 'check', kind: 'app', why: 'app.json check needs action and observe CSS selectors for a real shared action' };
+  const secret=localCredential(root,url);
+  if(isolate && !secret)return {ok:false,command:'check',why:'Fresh isolated records are on by default. Run dev in this studio and check its localhost URL, or explicitly use --no-isolate.'};
+  log(isolate ? 'Fresh isolated records: on (this check only).' : 'Fresh isolated records: off; using existing records.');
+  const dialogs=[];
+  const proof = meta.check??{};
+  const baseline=typeof proof.action==='string'&&typeof proof.observe==='string';
+  if (!baseline && !plan) return { ok: false, command: 'check', kind: 'app', why: 'app.json check needs action and observe CSS selectors for a real shared action' };
   if (shots) mkdirSync(shots, { recursive: true });
   const profile = mkdtempSync(join(tmpdir(), 'homie-app-check-'));
   let browser;
   const surfaces = [];
-  const room = `check-${Date.now().toString(36)}`;
+  const room = `check-${randomBytes(10).toString('hex')}`;
   try {
     browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
-    for (const [name, width, height, path] of [['wall', 1280, 720, 'tv'], ['phone', 390, 844, 'open'], ['phone-two', 390, 844, 'open']]) {
-      const context = await browser.createBrowserContext();
-      const page = await context.newPage();
-      await page.setViewport({ width, height, isMobile: name !== 'wall', hasTouch: name !== 'wall' });
-      const params = new URLSearchParams(proof.params ?? {}); params.set('room', room);
-      await page.goto(`${url}/${game}/${path}?${params}`, { waitUntil: 'domcontentloaded', timeout: 90_000 });
-      await page.waitForFunction(() => window.__shell?.link?.state === 'online', { timeout: 90_000 });
-      const frame = page.frames().find((f) => /\/__game\//.test(f.url()));
-      if (!frame) throw new Error(`${name} never loaded the app`);
-      await frame.waitForSelector(proof.observe, { timeout: 30_000 });
-      surfaces.push({ name, page, frame });
-      log(`${name} connected to ${room}`);
-    }
+    const openSurface = async (name, role) => {
+      const dimensions={wall:[1280,720],phone:[390,844],'phone-two':[390,844],tablet:[1024,768],staff:[1024,768],kiosk:[1080,1920]};
+      if(!dimensions[name])throw new Error(`Unknown needs surface ${name}`);
+      role ??= meta.surfaces?.[name==='phone-two'?'phone':name] ?? (name==='staff'?'staff':undefined);
+      if(!meta.roles?.[role])throw new Error(`${name}: unknown role ${role}`);
+      if(meta.roles[role].signIn && !secret)throw new Error(`${name}: local staff proof needs dev's test session`);
+      const context=await browser.createBrowserContext();
+      if(secret)await context.setCookie({name:'homie_test',value:localCookie(secret,{app:game,role,scope:isolate?room:null}),url,httpOnly:true,sameSite:'Strict'});
+      const page=await context.newPage();
+      answerDialogs(page,name,dialogs,report);
+      await page.evaluateOnNewDocument(observeEffects);
+      const [width,height]=dimensions[name];
+      await page.setViewport({width,height,isMobile:name!=='wall',hasTouch:name!=='wall'});
+      const params=new URLSearchParams(proof.params??{});params.set('room',room);params.set('role',role);params.set('surface',name==='staff'?'tablet':name==='phone-two'?'phone':name);
+      await page.goto(`${url}/${game}/${name==='wall'?'tv':'open'}?${params}`,{waitUntil:'domcontentloaded',timeout:90000});
+      const surface={name,role,page};await appReady(surface);
+      surfaces.push(surface);log(`${name} connected as ${role} to ${room}`);return surface;
+    };
+    let before=null,after=null;
+    if(baseline) {
+    for(const name of ['wall','phone','phone-two'])await openSurface(name);
     const textOf = (f) => f.$eval(proof.observe, (e) => e.textContent);
     const actor = surfaces[1];
-    await actor.frame.waitForFunction((selector) => { const el = document.querySelector(selector); return el && !el.disabled && !el.hidden; }, {}, proof.action);
-    const before = await textOf(actor.frame);
+    await waitInApp(actor,proof.action,f=>f.waitForFunction((selector) => { const el = document.querySelector(selector); return el && !el.disabled && !el.hidden; }, {}, proof.action));
+    before = await waitInApp(actor,proof.observe,textOf);
     await actor.frame.click(proof.action);
-    await actor.frame.waitForFunction((selector, was) => document.querySelector(selector)?.textContent !== was, {}, proof.observe, before);
-    const after = await textOf(actor.frame);
-    for (const s of surfaces) await s.frame.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after);
+    await waitInApp(actor,proof.observe+' changes after action',f=>f.waitForFunction((selector, was) => document.querySelector(selector)?.textContent !== was, {}, proof.observe, before));
+    after = await waitInApp(actor,proof.observe,textOf);
+    for (const s of surfaces) await waitInApp(s,proof.observe+' equals '+after,f=>f.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after));
     // The actor reloads with its ticket and room. The other screens remain live.
     await actor.page.reload({ waitUntil: 'domcontentloaded' });
-    await actor.page.waitForFunction(() => window.__shell?.link?.state === 'online', { timeout: 90_000 });
-    actor.frame = actor.page.frames().find((f) => /\/__game\//.test(f.url()));
-    await actor.frame.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after);
+    await appReady(actor);
+    await waitInApp(actor,proof.observe+' retained after reload',f=>f.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after));
     const rooms = await Promise.all(surfaces.map((s) => s.page.evaluate(() => window.__shell.room)));
     if (rooms.some((r) => r !== room)) throw new Error('surfaces did not retain the same room');
     for (const s of surfaces) {
-      await s.page.waitForFunction(() => {
-        const cover = document.querySelector('[data-arrive]');
-        return window.__shell?.arrival?.phase === 'done' && (!cover || (getComputedStyle(cover).opacity === '0' && getComputedStyle(cover).visibility === 'hidden'));
-      }, { timeout: READY_TIMEOUT_MS });
-      await s.frame.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+      await appReady(s);
       if (shots) await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });
     }
     report?.check?.('app-action', 'pass', { note: 'action reached wall and both phones; reconnect retained it' });
-    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report }) : null;
+    }
+    for(const need of plan?.needs??[])for(const item of [...(need.steps??[]),...(need.assertions??[])]) {
+      const role=item.role??need.role??meta.surfaces?.[item.surface]??(item.surface==='staff'?'staff':undefined);
+      if(!surfaces.some(s=>s.name===item.surface&&s.role===role))await openSurface(item.surface,role);
+    }
+    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady }) : null;
     if (plan) { saveAppNeeds(root, game, plan, needs); const { refreshCodexFile } = await import('./codex.mjs'); refreshCodexFile(root, game); }
     const ok = !needs || needs.every(n => n.status === 'met');
-    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: true };
-  } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
+    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', isolatedRecords:isolate, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
+  } catch (error) { return { ok: false, command: 'check', kind: 'app', dialogs, why: error.message }; }
   finally { await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
 }

package/lib/cloudflare.mjs

@@ -201,6 +201,7 @@ export function deployPlan(root) {
   return {
     ok: true, command: 'deploy plan', studio: studio.name, account: cf.accountId ?? null,
     cloudflare: [
+      {kind:'Cron triggers',name:(readConfig(root)?.triggers?.crons??[]).join('; ')||'none',what:'Installs these UTC triggers; the Worker dispatches due functions and retries. Studio custom triggers are retained.',state:'installed on deploy'},
       { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`) },
       { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`) },
       { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker' },
@@ -376,6 +377,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   refreshWorkerConfig(root, {d1Id: db.uuid});
+  step(`Cron triggers: ${(readConfig(root)?.triggers?.crons??[]).join("; ")||"none (remove toolkit triggers)"}`);
   if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
@@ -591,6 +593,7 @@ export function configNames(root) {
  */
 export async function ciDeploy(root, { log = () => {} } = {}) {
   const w = runner(root, {});
+  refreshWorkerConfig(root);
   const names = configNames(root);
   const steps = [];
   const step = (what) => { steps.push({ what }); log(what); };
@@ -602,6 +605,10 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);
   if (migrate.code !== 0 && !first) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   if (!first) step('D1 migrations applied');
+  const register=()=>w(['d1','execute',names.binding,'--remote','--command',functionDeploymentSQL(root)]);
+  const {functionDeploymentSQL}=await import('./functions-build.mjs');
+  if(!first) {const registered=register();if(registered.code!==0)return refuse('Could not register studio functions',registered.out);}
+  step(`Cron triggers: ${(readConfig(root)?.triggers?.crons??[]).join('; ')||'none (remove toolkit triggers)'}`);
   // Workers AI (0.17.0): bound only when a server's AI guides think with it. The checkout is thrown away after.
   if (!first && needsWorkersAi(root, w, names.binding)) {
     try {
@@ -620,6 +627,7 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
     migrate = apply();
     if (migrate.code !== 0) return refuse(`D1 migrations failed after the first deploy: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
     step('D1 migrations applied (the database was created with this first deploy)');
+    const registered=register();if(registered.code!==0)return refuse('Could not register studio functions',registered.out);
   }
   // The live address, from what Wrangler printed (a custom domain in studio.json wins).
   const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? null;

package/lib/dev.mjs

@@ -1,3 +1,4 @@
+import {createLocalCredential} from './local-test.mjs';
 import {workerEntry} from './worker-build.mjs';
 import { networkInterfaces } from 'node:os';
 /**
@@ -132,7 +133,7 @@ export function devState(root) {
 export function runningDev(root) {
   const st = devState(root);
   if (st.state !== 'running' || !st.port) return null;
-  return { url: `http://127.0.0.1:${st.port}`, port: st.port, pid: st.rec.pid ?? st.pids[0] };
+  return { url: `http://localhost:${st.port}`, port: st.port, pid: st.rec.pid ?? st.pids[0] };
 }
 
 async function endAll(pids, ms = 8000) {
@@ -292,15 +293,14 @@ function passLines(stream, to, opts) {
  * saved. `rulesStamp` is what it compares: the newest change among them, and how many there are.
  */
 export function rulesStamp(g) {
-  const files = [join(g.dir, g.kind === 'app' ? 'app.json' : 'game.json'), join(g.dir, 'tunables.json')];
-  for (const sub of ['src', 'map']) {
-    const dir = join(g.dir, sub);
-    if (existsSync(dir)) for (const name of readdirSync(dir, { recursive: true })) files.push(join(dir, String(name)));
-  }
-  let newest = 0;
-  let n = 0;
-  for (const f of files) { try { const st = statSync(f); if (st.isFile()) { n += 1; newest = Math.max(newest, st.mtimeMs); } } catch { /* gone */ } }
-  return `${n}:${Math.round(newest)}`;
+  const rows=[];
+  const walk=dir=>{for(const entry of readdirSync(dir,{withFileTypes:true})) {
+    if(['node_modules','.git','.wrangler','.studio','.port','.cache','.parcel-cache','.vite','.DS_Store','coverage','dist','codex'].includes(entry.name))continue;
+    const file=join(dir,entry.name);
+    if(entry.isDirectory())walk(file);
+    else if(entry.isFile()){const st=statSync(file);rows.push(`${file}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`);}
+  }};
+  walk(g.dir);return rows.sort().join('|');
 }
 
 const builtIds = (root) => { try { return JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')).games.map((g) => g.id); } catch { return null; } };
@@ -316,8 +316,8 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
   // What is really there, before anything is built or started (the header: stale state heals itself).
   const st = devState(root);
   if (st.state === 'running') {
-    const at = st.port ? `http://127.0.0.1:${st.port}/` : 'an unknown port';
-    return { ok: false, command: 'dev', already: true, ...(st.port ? { url: `http://127.0.0.1:${st.port}` } : {}), why: `this studio's dev server is already running at ${at} (process ${st.pids.join(', ')}). Use that one, or stop it first: ${stop}` };
+    const at = st.port ? `http://localhost:${st.port}/` : 'an unknown port';
+    return { ok: false, command: 'dev', already: true, ...(st.port ? { url: `http://localhost:${st.port}` } : {}), why: `this studio's dev server is already running at ${at} (process ${st.pids.join(', ')}). Use that one, or stop it first: ${stop}` };
   }
   if (st.state === 'stale') {
     rmSync(st.file, { force: true });
@@ -329,7 +329,7 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
     if (p === Number(port) && left.open) {
       const busy = port;
       do { port = String(Number(port) + 1); } while (Number(port) < 65535 && await portOpen(Number(port)));
-      log(`Port ${busy} is busy; using http://127.0.0.1:${port}/`);
+      log(`Port ${busy} is busy; using http://localhost:${port}/`);
     }
   }
 
@@ -348,7 +348,8 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
     m.on('error', done);
   });
   const origin = `http://127.0.0.1:${port}`;
-  log(`Local site: ${origin}/  (each game: ${origin}/<id>/play — open it in two browsers)`);
+  const printedOrigin = `http://localhost:${port}`;
+  log(`Local site: ${printedOrigin}/  (each game: ${printedOrigin}/<id>/play — open it in two browsers)`);
   if (lan) for (const address of lanAddresses()) log(`Same Wi-Fi: http://${address}:${port}/ (open this address on phones and wall screens)`);
   const ai = devConfig(root, remoteAi);
   if (ai.note) log(ai.note);
@@ -362,7 +363,8 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
   }
   // --remote-ai: Wrangler's --local turns every remote binding off ("not supported"), so a dev with the real Workers AI
   // (the guides' brains, room chat's review) runs without it; everything else stays local all the same.
-  const args = ['dev', ...(remoteAi ? [] : ['--local']), '--ip', lan ? '0.0.0.0' : '127.0.0.1', '--port', port, '--var', 'HOMIE_EMBED_PREVIEW:1', ...ai.args, ...localVars];
+  const localSecret = createLocalCredential(root);
+  const args = ['dev', '--var', `HOMIE_LOCAL_TEST_SECRET:${localSecret}`, ...(remoteAi ? [] : ['--local']), '--ip', lan ? '0.0.0.0' : '127.0.0.1', '--port', port, '--var', 'HOMIE_EMBED_PREVIEW:1', ...ai.args, ...localVars];
   log(`Stop it with: ${stop}   (this studio's dev server only)`);
 
   let child = null;
@@ -417,13 +419,13 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
     } finally { busy = false; }
   };
   // A rules game saved while dev runs is built again (see rulesStamp), one game at a time.
-  const stamps = new Map(listGames(root).filter(isRulesGame).map((g) => [g.id, rulesStamp(g)]));
+  const stamps = new Map(listGames(root).map((g) => [g.id, rulesStamp(g)]));
   const timingRetries = new Map();
   let rebuilding = false;
   let published = Promise.resolve();
   const rulesLook = async () => {
     if (rebuilding || ending) return;
-    for (const g of listGames(root).filter(isRulesGame)) {
+    for (const g of listGames(root)) {
       const now = rulesStamp(g);
       const retry = timingRetries.get(g.id);
       if (stamps.get(g.id) === now && !(retry?.stamp === now && Date.now() >= retry.at)) continue;

package/lib/events-cli.mjs

@@ -31,7 +31,11 @@ export async function eventsWebhook(root,action,name,url,{run,connect=connectToo
   writeStudio(root,studio);
   return {ok:true,command:'events webhook '+action,feed:name,...(secret?{secret}:{}),next:action==='rotate'?'Key replaced in the Worker. Configure the receiver with this key; it is shown only here.':'Build, commit and deploy the updated feed declaration through your usual authorized workflow.'};
 }
-export function eventsCommand(root,sub,positional,flags,options={}) {
+export async function eventsCommand(root,sub,positional,flags,options={}) {
+  if(sub==='clear'||sub==='read') {
+    const client=await connectToolClient(root,flags.get('url')??'http://localhost:8787',options);
+    try {const result=await client.callTool({name:'studio_events_'+sub,arguments:sub==='clear'?{through:Number(flags.get('through'))}:{feed:positional[2],after:Number(flags.get('after')??0)}});return {ok:!result.isError,result};} finally {await client.close();}
+  }
   if(sub!=='webhook')throw new Error('Use events webhook <add|remove|rotate|status|test>');
   return eventsWebhook(root,positional[2],positional[3],positional[4]??flags.get('url'),{...options,after:flags.get('after')??0});
 }

package/lib/functions-build.mjs

@@ -1,12 +1,13 @@
 import {validateWebhook,webhookName} from '../worker/event-webhook-config.mjs';
+import {parseSchedule,nextDue,scheduleStatus} from '../worker/function-schedule.mjs';
 import {existsSync,readdirSync,mkdirSync,writeFileSync,readFileSync} from 'node:fs';
 import {join} from 'node:path';
-import {readStudio} from './studio.mjs';
+import {readStudio,configPath} from './studio.mjs';
 import {pathToFileURL} from 'node:url';
 import {createRequire} from 'node:module';
 const require=createRequire(import.meta.url);
 export function functionFiles(root) { const dir=join(root,'functions');return existsSync(dir)?readdirSync(dir).filter(f=>/^[a-z][a-z0-9-]*\.ts$/.test(f)).sort().map(f=>join(dir,f)):[]; }
-export async function buildFunctions(root,esbuild) {
+export async function buildFunctions(root,esbuild,{log=()=>{}}={}) {
   const feeds=readStudio(root).mcp?.events??{};
   if(!feeds||typeof feeds!=='object'||Array.isArray(feeds))throw new Error('mcp.events must be a map of named event feeds');
   for(const [name,feed] of Object.entries(feeds)) {
@@ -29,13 +30,19 @@ export async function buildFunctions(root,esbuild) {
   const names=new Set();
   for(const fn of definitions) {
     if(!/^[a-z][a-z0-9-]*$/.test(fn.name)||names.has(fn.name)||typeof fn.handler!=='function'||typeof fn.event!=='string'||!fn.event.trim())throw new Error('Function needs a unique name, event and handler');
-    if(fn.schedule && (typeof fn.schedule!=='string'||fn.schedule.trim().split(/\s+/).length!==5))throw new Error('Function schedule needs a Cloudflare cron expression');
+    if(fn.schedule!==undefined) {
+      try {if(nextDue(parseSchedule(fn.schedule))===null)throw new Error('no matching date');}
+      catch(error) {throw new Error(`Function ${fn.name} cannot run: invalid schedule ${JSON.stringify(fn.schedule)} (${error.message})`);}
+    }
     names.add(fn.name);
   }
   const worker=join(root,'site/src/worker.mjs');
   if(existsSync(worker)) {let text=readFileSync(worker,'utf8');if(!text.includes('useFunctions(')){text+="\nimport { useFunctions } from '@homie-rocks/studio/worker';\nuseFunctions(async () => (await import('./functions/index.mjs')).default);\n";writeFileSync(worker,text);}}
   writeFileSync(join(dir,'declarations.json'),JSON.stringify(definitions.map(({name,event,schedule,replay})=>({name,event,schedule,replay})),null,2)+'\n');
   (await import('./worker-config.mjs')).refreshWorkerConfig(root);
+  const config=existsSync(configPath(root))?JSON.parse(readFileSync(configPath(root),'utf8').replace(/^\s*\/\/.*$/gm,'')):{};
+  for(const status of scheduleStatus(definitions,config.triggers?.crons??[]))log(`Function ${status.function}: ${status.schedule} UTC; ${status.status}; next due ${status.nextDue??'none'}`);
+  if(definitions.length)log(`Function cron triggers to install on deploy: ${(config.triggers?.crons??[]).join('; ')||'none'}`);
   return definitions;
 }
 /** Install subscriptions before the new Worker can produce its first event. */

package/lib/functions-cli.mjs

@@ -1,7 +1,13 @@
 import {existsSync,mkdirSync,writeFileSync} from 'node:fs';
 import {join} from 'node:path';
+import {siteUrl} from './studio.mjs';
 import {connectToolClient} from './tools-cli.mjs';
-export async function functionCommand(root,sub,positional,flags,{log=()=>{}}={}) {
+export async function functionCommand(root,sub,positional,flags,{log=()=>{},connect=connectToolClient}={}) {
+  if(sub==='runs') {
+    const url=flags.get('url')??siteUrl(root)??'http://localhost:8787';
+    const client=await connect(root,new URL(url),{log});
+    try {const result=await client.callTool({name:'studio_function_runs',arguments:{...(positional[2]?{name:positional[2]}:{}),errors:flags.has('errors'),...(flags.has('before')?{before:Number(flags.get('before'))}:{})}});return {ok:!result.isError,command:'functions runs',result};}finally{await client.close();}
+  }
   if(sub==='new') {
     const name=positional[2],event=flags.get('event')??'order.paid';
     if(!/^[a-z][a-z0-9-]*$/.test(name??''))throw new Error('Use a lowercase function name');
@@ -12,12 +18,12 @@ export async function functionCommand(root,sub,positional,flags,{log=()=>{}}={})
   }
   if(sub==='replay') {
     if(!flags.has('replay'))throw new Error('Pass --replay to explicitly request retained history');
-    const client=await connectToolClient(root,new URL(flags.get('url')??'http://localhost:8787'),{log});
+    const client=await connect(root,new URL(flags.get('url')??'http://localhost:8787'),{log});
     try {const result=await client.callTool({name:'studio_function_replay',arguments:{name:positional[2]}});return {ok:!result.isError,command:'function replay',result};}finally{await client.close();}
   }
   if(sub!=='fire')throw new Error('Use function new <name> --event <event>, or function fire <event> --input <JSON>');
   const url=new URL(flags.get('url')??'http://localhost:8787');
   if(!['localhost','127.0.0.1','[::1]'].includes(url.hostname))throw new Error('Fire is local testing only');
-  const client=await connectToolClient(root,url,{log});
+  const client=await connect(root,url,{log});
   try {const result=await client.callTool({name:'studio_function_fire',arguments:{event:positional[2],data:JSON.parse(flags.get('input')??'{}'),...(flags.has('id')?{id:flags.get('id')}: {})}});return {ok:!result.isError,command:'function fire',result};}finally{await client.close();}
 }

package/lib/local-test.mjs

@@ -0,0 +1,18 @@
+import {readFileSync,mkdirSync,writeFileSync,chmodSync} from 'node:fs';
+import {join} from 'node:path';
+import {randomBytes,createHmac} from 'node:crypto';
+export function createLocalCredential(root) {
+  const secret=randomBytes(32).toString('hex');
+  mkdirSync(join(root,'.studio'),{recursive:true});
+  const file=join(root,'.studio','local-test.json');
+  writeFileSync(file,JSON.stringify({secret}),{mode:0o600});chmodSync(file,0o600);
+  return secret;
+}
+export function localCredential(root,site) {
+  if(!root||!['localhost','127.0.0.1','[::1]'].includes(new URL(site).hostname))return null;
+  try{return JSON.parse(readFileSync(join(root,'.studio','local-test.json'),'utf8')).secret;}catch{return null;}
+}
+export function localCookie(secret,session) {
+  const data=Buffer.from(JSON.stringify(session)).toString('base64url');
+  return data+'.'+createHmac('sha256',secret).update(data).digest('hex');
+}

package/lib/office.mjs

@@ -29,7 +29,7 @@ const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** Call the studio's office API with a key that lives ten minutes and is dropped as soon as the answer is in. */
 export async function withKey(root, url, fn) {
   const { studio, site } = siteOf(root, url);
-  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://127.0.0.1:8787 for `npm run dev`' };
+  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://localhost:8787 for `npm run dev`' };
   const local = loopback(site);
   const k = mint(root, studio, 'office', 10 * 60_000, { local });
   let expiresAt = Date.now() + 10 * 60_000;

package/lib/scaffold.mjs

@@ -1,4 +1,5 @@
-import { FUNCTIONS_REFERENCE_MIGRATION, FUNCTIONS_REFERENCE_MIGRATION_FILE, FUNCTIONS_META_MIGRATION, FUNCTIONS_META_MIGRATION_FILE, FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
+import {TOOL_DATABASE_MIGRATION,TOOL_DATABASE_MIGRATION_FILE} from '../worker/tool-database.mjs';
+import { FUNCTIONS_RUNS_MIGRATION, FUNCTIONS_RUNS_MIGRATION_FILE, FUNCTIONS_REFERENCE_MIGRATION, FUNCTIONS_REFERENCE_MIGRATION_FILE, FUNCTIONS_META_MIGRATION, FUNCTIONS_META_MIGRATION_FILE, FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
 import { MCP_MIGRATION, MCP_MIGRATION_FILE } from '../worker/mcp-store.mjs';
 import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 import { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from '../worker/purchase-schema.mjs';
@@ -820,11 +821,13 @@ export { default, Table, Lobby, Gate, Concentrator } from '@homie-rocks/studio/w
     [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
     [`site/migrations/${SHOP_REMOVE_REFERRALS_FILE}`]: SHOP_REMOVE_REFERRALS,
     [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
+    [`site/migrations/${TOOL_DATABASE_MIGRATION_FILE}`]: TOOL_DATABASE_MIGRATION,
     [`site/migrations/${MCP_MIGRATION_FILE}`]: MCP_MIGRATION,
     [`site/migrations/${FUNCTIONS_MIGRATION_FILE}`]: FUNCTIONS_MIGRATION,
     [`site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`]: FUNCTIONS_CURSOR_MIGRATION,
     [`site/migrations/${FUNCTIONS_META_MIGRATION_FILE}`]: FUNCTIONS_META_MIGRATION,
     [`site/migrations/${FUNCTIONS_REFERENCE_MIGRATION_FILE}`]: FUNCTIONS_REFERENCE_MIGRATION,
+    [`site/migrations/${FUNCTIONS_RUNS_MIGRATION_FILE}`]: FUNCTIONS_RUNS_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -996,6 +999,11 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_FILE}`;
 }
 
+function ensureFunctionRuns(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_RUNS_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_RUNS_MIGRATION);return `site/migrations/${FUNCTIONS_RUNS_MIGRATION_FILE}`;
+}
 function ensureFunctionReference(root) {
   const file=join(root,'site','migrations',FUNCTIONS_REFERENCE_MIGRATION_FILE);
   if(existsSync(file))return null;
@@ -1021,8 +1029,13 @@ function ensureMcpMigration(root) {
   if(existsSync(file))return null;
   mkdirSync(dirname(file),{recursive:true});writeFileSync(file,MCP_MIGRATION);return `site/migrations/${MCP_MIGRATION_FILE}`;
 }
+function ensureToolDatabase(root) {
+  const file=join(root,'site','migrations',TOOL_DATABASE_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,TOOL_DATABASE_MIGRATION);return `site/migrations/${TOOL_DATABASE_MIGRATION_FILE}`;
+}
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root), ensureShopRemoveReferrals(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root), ensureShopRemoveReferrals(root), ensureFunctionRuns(root), ensureToolDatabase(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */

package/lib/template-history.json

@@ -3408,6 +3408,90 @@
      }
     }
    }
+  },
+  "0.50.6": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "43a3556be93d1235",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
+  },
+  "0.50.7": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "43a3556be93d1235",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/tools-cli.mjs

@@ -1,3 +1,4 @@
+import {localCredential} from './local-test.mjs';
 import {existsSync,mkdirSync,writeFileSync,readFileSync,chmodSync} from 'node:fs';
 import {join,dirname} from 'node:path';
 import {createServer} from 'node:http';
@@ -16,6 +17,8 @@ export async function connectToolClient(root,site,{publicOnly=false,open=default
   const url=new URL('/mcp',site);if(url.protocol!=='https:'&&!['localhost','127.0.0.1','[::1]'].includes(url.hostname))throw new Error('Use HTTPS, or localhost for local development');
   const client=new Client({name:'Homie studio tool CLI',version:'1.0.0'});
   if(publicOnly){await client.connect(new StreamableHTTPClientTransport(url));return client;}
+  const secret=localCredential(root,url);
+  if(secret){await client.connect(new StreamableHTTPClientTransport(url,{requestInit:{headers:{authorization:`Bearer ${secret}`}}}));return client;}
   const file=join(root,'.studio','mcp',Buffer.from(url.origin).toString('base64url')+'.json');
   let state={};try{state=JSON.parse(readFileSync(file,'utf8'));}catch{}
   // Credentials without an issuer predate the SDK's OAuth binding fix; reconnect safely.