@homie-rocks/studio 0.35.0 → 0.36.0

package/lib/rules-types.mjs

@@ -0,0 +1,167 @@
+/** A compiler-only facade: declarations supply contextual types without changing a game's source or its bundle. */
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from './studio.mjs';
+
+const q = JSON.stringify;
+const record = (entries) => `{ ${entries.map(([n, t]) => `${q(n)}: ${t}`).join('; ')} }`;
+function field(f) {
+  if (f.t === 'bit' || f.t === 'press') return 'boolean';
+  if (f.t === 'ref' || f.t === 'text') return 'string';
+  if (f.t === 'vec3' || f.t === 'dir') return 'Vec3';
+  if (f.t === 'list') return `ReadonlyArray<${field(f.of)}>`;
+  if (f.t === 'map') return `Record<string, ${field(f.of)}>`;
+  if (f.t === 'struct') return fields(Object.entries(f.fields));
+  return 'number';
+}
+const fields = (list) => `{ ${list.map(([n, f]) => `get ${q(n)}(): ${field(f)}; set ${q(n)}(value: WriteState<${field(f)}>);`).join(' ')} }`;
+const shapes = (table) => record(Object.entries(table).map(([n, fs]) => [n, fs.length ? fields(fs) : 'Record<string, never>']));
+const value = (v) => v === null ? 'null' : Array.isArray(v) ? `Array<${[...new Set(v.map(value))].join(' | ') || 'never'}>` : typeof v === 'object' ? record(Object.entries(v).map(([n, x]) => [n, value(x)])) : typeof v;
+const picks = (questions) => record(Object.entries(questions).map(([name, question]) => [name,
+  question.type === 'choice' ? (Array.isArray(question.criteria) ? question.criteria : Object.keys(question.criteria)).map(q).join(' | ')
+    : question.type === 'score' ? 'number' : 'boolean']));
+// Vocabulary arguments are admitted by argsWhy; object offers expose their id.
+function vocabularyTypes(vocab, view) {
+  if (!vocab) return { goals: 'Goal', asks: 'GuideRequest', floorAsks: 'GuideRequest', decision: 'GuideDecision' };
+  const argument = source => {
+    if (source === 'player') return 'number';
+    if (Array.isArray(source)) return source.map(q).join(' | ') || 'never';
+    let fd = view[source?.slice(5)];
+    if (fd?.t === 'list') fd = fd.of;
+    if (fd?.t === 'struct') fd = fd.fields.id;
+    return fd && ['text', 'ref', 'u8', 'i8', 'u16', 'i16', 'u32', 'i32', 'fix', 'tick', 'ticks'].includes(fd.t) ? field(fd) : 'never';
+  };
+  const union = (table, discriminator, metadata) => Object.entries(table ?? {}).map(([name, def]) =>
+    `{ readonly ${discriminator}: ${q(name)}; readonly args: Readonly<${record(Object.entries(def.args ?? {}).map(([key, source]) => [key, argument(source)]))}>; ${metadata} }`).join(' | ') || 'never';
+  // A floor names one goal and one line, each with exactly its declared arguments, as argsWhy admits them.
+  const choice = (table, name, args) => [`{ ${name}?: null; ${args}?: Record<string, never> }`, ...Object.entries(table ?? {}).map(([n, def]) => {
+    const list = Object.entries(def.args ?? {}).map(([key, source]) => [key, argument(source)]);
+    return `{ ${name}: ${q(n)}; ${args}${list.length ? `: Readonly<${record(list)}>` : '?: Record<string, never>'} }`;
+  })].join(' | ');
+  return { goals: union(vocab.goals, 'goal', "readonly from: 'brain' | 'floor'; readonly at: number; readonly asked: boolean; readonly state: 'active' | 'done' | 'failed'"),
+    asks: union(vocab.asks, 'k', 'readonly from: number; readonly at: number'),
+    // The arguments of a request the server admitted carry a compile-time mark, so a floor may forward
+    // { goal: ask.k, args: ask.args } without narrowing while arguments it writes itself must fit their goal.
+    floorAsks: 'GameRequest extends infer A ? A extends { args: object } ? Omit<A, \'args\'> & { readonly args: A[\'args\'] & Admitted } : never : never',
+    decision: `(${choice(vocab.goals, 'goal', 'args')} | { goal: Extract<GameRequest['k'], GameGoal['goal']>; args: FloorRequest['args'] }) & (${choice(vocab.lines, 'say', 'sayArgs')})` };
+}
+export function rulesTypes(checked, tune) {
+  const { schema: s, declarations: d } = checked;
+  const vocabulary = vocabularyTypes(checked.vocab, d.view);
+  const kind = (k) => `Self<${fields(k.fields)}, ${fields(k.motion)}, ${fields(k.input)}, ${q(k.name)}, ${k.player}, GameGoal>`;
+  const all = record(s.kinds.map((k) => [k.name, kind(k)]));
+  const create = record(s.kinds.filter((k) => !k.player).map((k) => [k.name, k.fields.length ? fields(k.fields) : 'Record<string, never>']));
+  const asks = record(Object.entries(d.asks).map(([n, a]) => [n, fields(a.state)]));
+  const tunables = { ...Object.fromEntries(Object.entries(tune.public ?? {}).map(([n, v]) => [n, v?.value ?? v])), ...Object.fromEntries(Object.entries(tune).filter(([n]) => n !== 'public').map(([n, v]) => [n, v?.value ?? v])) };
+  const parameters = `${shapes(d.events)}, ${shapes(s.effects)}, ${fields(s.shared)}, ${all}, ${create}, ${asks}, ${value(tunables)}`;
+  const answer = scope => checked.answerScopes ? `Extract<Answers, { ask: ${[...new Set([...(checked.answerScopes.scopes[scope] ?? []), ...checked.answerScopes.common])].map(q).join(' | ') || 'never'} }>` : 'Answers';
+  const entities = record(s.kinds.map((k) => [k.name, `Entity<W, ${kind(k)}, ${fields(k.input)}, Events, Commands, ${fields(Object.entries(d.view))}, ${answer(k.name)}, GameGoal, FloorRequest, GameDecision>`]));
+  const joins = s.kinds.filter((k) => k.player).map((k) => `{ kind: ${q(k.name)}; at: Point; heading?: Point; fields?: Partial<WriteState<${fields(k.fields)}>>; motion?: Partial<WriteState<${fields(k.motion)}>> }`).join(' | ') || 'never';
+  const moves = `{ ${s.kinds.filter((k) => k.radius > 0).map((k) => `${q(k.name)}${k.player ? '' : '?'}: (body: MoveBody<${fields(k.motion)}>, input: ReadonlyState<${fields(k.input)}>, ctx: MoveContext<${value(checked.publicTune)}, ${fields(k.motion)}>) => undefined`).join('; ')} }`;
+  return `// Generated from this game's checked declarations. The build always uses strict compiler settings.
+export * from ${q(join(PACKAGE_ROOT, 'rules/rules.ts'))};
+import type { RulesDef, Vec3, Fields } from ${q(join(PACKAGE_ROOT, 'rules/rules.ts'))};
+import type { World, Self, Entity, Point, MoveBody, MoveContext, ReadonlyState, WriteState, EventData, RoomEvents, Goal, GuideRequest, GuideDecision } from ${q(join(PACKAGE_ROOT, 'rules/types.ts'))};
+export type GameGoal = ${vocabulary.goals};
+export type GameRequest = ${vocabulary.asks};
+declare const admitted: unique symbol;
+type Admitted = { readonly [admitted]: true };
+type FloorRequest = ${vocabulary.floorAsks};
+type GameDecision = ${vocabulary.decision};
+type Events = ${shapes(d.events)};
+type Commands = ${shapes(s.commands)};
+type Answers = ${Object.entries(d.asks).map(([n, a]) => `{ ask: ${q(n)}; by: 'local' | 'ai' | 'floor'; picks: ${picks(a.questions)}; why?: string }`).join(' | ') || 'never'};
+type GameRoomEvents = Omit<RoomEvents<Events>, 'answer'> & { answer: ${answer('room')} };
+export type GameWorld = W;
+export type GameSelf<K extends keyof GameEntities> = GameEntities[K];
+type GameEntities = ${all};
+type W = World<${parameters}>;
+type RW = World<${parameters}, true>;
+type Definition = Omit<RulesDef, 'entities' | 'room' | 'move' | 'asks'> & {
+  entities: ${entities}; move?: Moves;
+  room?: { rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number };
+    start?: (world: RW) => void;
+    join?: (ctx: Pick<W, 'map' | 'shared' | 'tune' | 'math' | 'round'>, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string }) => ${joins};
+    on?: { [K in keyof (Omit<Events, keyof GameRoomEvents> & GameRoomEvents)]?: (world: RW, event: EventData<(Omit<Events, keyof GameRoomEvents> & GameRoomEvents)[K]>) => void };
+  };
+  asks?: ${record(Object.entries(d.asks).map(([n, a]) => [n, `{ state: Fields; questions: ${value(a.questions)}; floor: (state: ReadonlyState<${fields(a.state)}>) => ${picks(a.questions)} }`]))};
+};
+type Moves = ${moves};
+export declare function defineRules(def: Definition): Definition;
+export declare function defineMove(def: Moves): Moves;
+`;
+}
+
+/** The view reads the same declared fields and names as the rules. */
+export function rulesViewTypes(checked) {
+  const s = checked.schema;
+  const entities = record(s.kinds.map(k => [k.name, `ReadonlyState<Omit<GameSelf<${q(k.name)}>, 'input'>> & { readonly mine?: boolean }`]));
+  const effects = record(Object.entries(s.effects).map(([n, fs]) => [n, `ReadonlyState<${fields(fs)}> & { readonly at?: Vec3; readonly id?: string; readonly tick: number }`]));
+  const input = s.kinds.filter(k => k.player).map(k => `Partial<${fields(k.input)}>`).join(' | ') || 'Record<string, never>';
+  return `export * from ${q(join(PACKAGE_ROOT, 'rules/view.ts'))};
+import type { Room as BaseRoom, OpenRoomOptions, RoomRound, RoomStatus } from ${q(join(PACKAGE_ROOT, 'rules/view.ts'))};
+import type { ReadonlyState, WriteState } from ${q(join(PACKAGE_ROOT, 'rules/types.ts'))};
+import type { Vec3 } from ${q(join(PACKAGE_ROOT, 'rules/rules.ts'))};
+import type { GameSelf, GameGoal, GameRequest } from './rules';
+type Entities = ${entities};
+type Commands = ${shapes(s.commands)};
+type Effects = ${effects} & { enter: Entity; leave: Entity; placed: Entity; round: RoomRound | null; status: RoomStatus; say: { readonly slot: number; readonly seat: number | null; readonly text: string; readonly line?: string; readonly kind?: string; readonly args: Readonly<Record<string, unknown>> }; goal: { readonly slot: number; readonly goal: GameGoal; readonly prev: GameGoal | null; readonly askAt: number | null }; ask: { readonly slot: number; readonly k: string; readonly ask?: string; readonly from: number; readonly at: number; readonly args: Readonly<Record<string, unknown>> } };
+export type Entity = Entities[keyof Entities];
+// A request's own arguments; a button's k and args, still a union, pass together.
+type AskArgs<K> = GameRequest extends infer A ? A extends { k: infer N; args: infer X } ? K extends N ? X : never : never : never;
+export type Room<R = never> = Omit<BaseRoom<R>, 'me' | 'each' | 'get' | 'on' | 'shared' | 'input' | 'command' | 'tune' | 'ask' | 'askButtons'> & {
+ // A name written out must be one of the vocabulary's, with its arguments. A name the view only has as a text (a list
+ // of buttons it built itself) passes as it is, with any arguments: the server checks those when they arrive.
+ ask<K extends string>(id: string, k: string extends K ? K : K extends GameRequest['k'] ? K : GameRequest['k'], ...args: string extends K ? [args?: Readonly<Record<string, unknown>>] : {} extends AskArgs<K> ? [args?: AskArgs<K>] : [args: AskArgs<K>]): void;
+ askButtons(id: string, offer?: Record<string, unknown>): Array<GameRequest extends infer A ? A extends { k: string; args: object } ? Pick<A, 'k' | 'args'> & { readonly text: string } : never : never>;
+ readonly me: Extract<Entity, { seat: number }> | null;
+ readonly shared: ReadonlyState<${fields(s.shared)}>;
+ readonly tune: ReadonlyState<${value(checked.publicTune)}>;
+ each<K extends keyof Entities>(kind: K, fn: (entity: Entities[K]) => void): void;
+ get(id: string): Entity | null;
+ on<K extends keyof Effects>(name: K, fn: (event: Effects[K]) => void): () => void;
+ input(sample: ${input}): void;
+ command<K extends keyof Commands>(name: K, ...data: {} extends Commands[K] ? [data?: Commands[K]] : [data: Commands[K]]): void;
+};
+export declare function openRoom<R = never>(options?: OpenRoomOptions): Room<R>;
+`;
+}
+
+/** Answers return to their caller. A room cannot receive an entity's ask response.
+ * Literal asks in a known handler restrict that scope; shared helpers conservatively
+ * contribute their asks to every scope, and a dynamic name retains the full union.
+ */
+export async function rulesAnswerScopes(entry) {
+  const [{ parse }, { default: traverseModule }, fs, path] = await Promise.all([
+    import('@babel/parser'), import('@babel/traverse'), import('node:fs'), import('node:path'),
+  ]);
+  const traverse = traverseModule.default ?? traverseModule;
+  const scopes = new Map(); const common = new Set(); const seen = new Set(); let dynamic = false;
+  const key = node => node?.key?.name ?? node?.key?.value;
+  function read(file) {
+    if (seen.has(file)) return; seen.add(file);
+    const ast = parse(fs.readFileSync(file, 'utf8'), { sourceType: 'module', plugins: ['typescript'] });
+    traverse(ast, {
+      ImportDeclaration(p) {
+        const name = p.node.source.value; if (!name.startsWith('.')) return;
+        const base = path.resolve(path.dirname(file), name);
+        const target = [base, `${base}.ts`, `${base}.js`, path.join(base, 'index.ts')].find(f => fs.existsSync(f) && fs.statSync(f).isFile());
+        if (target) read(target);
+      },
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (callee.type !== 'MemberExpression' || (callee.property.name ?? callee.property.value) !== 'ask') return;
+        const name = p.node.arguments[0];
+        if (name?.type !== 'StringLiteral') { dynamic = true; return; }
+        let scope;
+        for (let a = p.parentPath; a; a = a.parentPath) {
+          if (a.isObjectProperty() && key(a.node) === 'room') { scope = 'room'; break; }
+          if (a.isObjectProperty() && a.parentPath?.isObjectExpression() && key(a.parentPath.parentPath?.node) === 'entities') { scope = key(a.node); break; }
+        }
+        if (!scope) common.add(name.value);
+        else { const names = scopes.get(scope) ?? new Set(); names.add(name.value); scopes.set(scope, names); }
+      },
+    });
+  }
+  read(entry);
+  return dynamic ? null : { common: [...common], scopes: Object.fromEntries([...scopes].map(([k, names]) => [k, [...names]])) };
+}

package/lib/shop-catalog.mjs

@@ -22,7 +22,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { readStudio } from './studio.mjs';
 import { readShop } from './shop.mjs';
 import { defaultTaxCode, money } from '../worker/shop-rules.mjs';
-import { productIdOf } from '../worker/stripe.mjs';
+import { productIdOf, redactStripe } from '../worker/stripe.mjs';
 
 const MARK = 'shop-v1';
 
@@ -58,6 +58,22 @@ export function productsIn(value, out = [], depth = 0) {
   return out;
 }
 
+// Saved MCP responses can wrap a Stripe refusal in text or structured content.
+function catalogError(value, depth = 0) {
+  if (depth > 8 || value == null) return null;
+  if (typeof value === 'string') {
+    try { return catalogError(JSON.parse(value), depth + 1); } catch { return null; }
+  }
+  if (typeof value !== 'object') return null;
+  if (typeof value.error?.message === 'string') return value.error.message;
+  if (value.isError === true) return (value.content ?? []).filter((c) => c.type === 'text').map((c) => c.text).join(' ');
+  for (const child of Array.isArray(value) ? value : ['data', 'content', 'text', 'result', 'results', 'structuredContent'].map((k) => value[k])) {
+    const error = catalogError(child, depth + 1);
+    if (error) return error;
+  }
+  return null;
+}
+
 const taxCodeOf = (p) => (typeof p?.tax_code === 'string' ? p.tax_code : p?.tax_code?.id ?? null);
 
 /** The plan: the read first, then (with what Stripe answered) the writes still needed. */
@@ -83,6 +99,8 @@ export async function catalogPlan(root, { have = null, mode = null, record = tru
       ],
     };
   }
+  const error = catalogError(have);
+  if (error) return { ok: false, command: 'shop catalog', why: `Stripe said: “${redactStripe(error).slice(0, 400)}” (GET /v1/products). Read the catalog again after resolving it.` };
   const products = productsIn(have);
   const ours = products.filter((p) => p.metadata?.homie_studio === String(slug) || wanted.some((w) => w.id === p.id));
   const modes = [...new Set(ours.map((p) => (p.livemode ? 'live' : 'test')))];
@@ -149,6 +167,7 @@ export async function catalogPlan(root, { have = null, mode = null, record = tru
 
 export function catalogLines(r) {
   const lines = [];
+  if (!r.ok) return [r.why];
   if (r.step === 'read') {
     lines.push('The catalog shop.json asks for (one Product an item, the same ids in the sandbox and live):');
     for (const p of r.products) lines.push(`  ${p.id}  ${p.name}  ${p.price}  (tax code ${p.tax_code})`);

package/lib/shop-links.mjs

@@ -37,8 +37,10 @@ export async function syncPaymentLinks({ api, shop, slug, site, mode, w, receipt
     let product = products.find((p) => p.id === id);
     if (!product) product = await api('POST', '/v1/products', { id, ...fields }, `product-${hash(id)}`);
     else if (!same(product.metadata, metadata) || product.name !== fields.name || (product.description ?? '') !== fields.description || (product.tax_code?.id ?? product.tax_code) !== fields.tax_code || !product.active) await api('POST', `/v1/products/${id}`, fields);
+    // Omit an unset minimum: Stripe applies its settlement-currency floor itself.
+    // https://docs.stripe.com/api/prices/create#create_price-custom_unit_amount-minimum
     const priceFields = { product: id, currency: shop.currency, tax_behavior: 'exclusive', ...(item.price === 'choose'
-      ? { custom_unit_amount: { enabled: true, minimum: item.min, ...(item.max !== null ? { maximum: item.max } : {}) } }
+      ? { custom_unit_amount: { enabled: true, ...(item.min > 0 ? { minimum: item.min } : {}), ...(item.max !== null ? { maximum: item.max } : {}) } }
       : { unit_amount: item.price }) };
     const revision = hash(priceFields);
     let price = prices.find((p) => own(p) && p.product === id && p.metadata?.revision === revision);

package/lib/shop.mjs

@@ -205,7 +205,7 @@ async function makeWebhook(env, site, { fetcher }) {
     const list = await listWebhookEndpoints(env, { fetcher });
     older = (list?.data ?? []).filter((e) => e?.url === url && e?.metadata?.homie === HOOK_MARK && e?.status !== 'disabled').map((e) => e.id).filter((id) => typeof id === 'string');
   } catch (error) {
-    if (isPermissionError(error)) return { ok: false, page: said(400, 'This key cannot make webhooks: it needs Webhook Endpoints: Write. In Stripe, open the key (… → Edit key), set Webhook Endpoints to Write and save, then go back and press Save again. Or make the webhook yourself and paste its signing secret under "I made the webhook myself".') };
+    if (isPermissionError(error)) return { ok: false, page: said(400, 'This key cannot make webhooks: it needs Webhook Endpoints: Write. In Stripe, open the key (… → Edit key), set Webhook Endpoints to Write and save, then go back and press Save again. Or make the webhook yourself and paste its signing secret under "I made the webhook myself".' + ` Stripe said: ${error.message}`) };
     return { ok: false, page: said(502, `Stripe did not answer the webhook list (${error instanceof StripeError ? error.message : 'no answer'}). Nothing was saved. Go back and try again.`) };
   }
   let made = null;
@@ -215,7 +215,7 @@ async function makeWebhook(env, site, { fetcher }) {
       description: 'Homie shop (made by homie-studio shop connect)', metadata: { homie: HOOK_MARK },
     }, { fetcher });
   } catch (error) {
-    if (isPermissionError(error)) return { ok: false, page: said(400, 'This key cannot make webhooks: it needs Webhook Endpoints: Write. In Stripe, open the key (… → Edit key), set Webhook Endpoints to Write and save, then go back and press Save again. Or make the webhook yourself and paste its signing secret under "I made the webhook myself".') };
+    if (isPermissionError(error)) return { ok: false, page: said(400, 'This key cannot make webhooks: it needs Webhook Endpoints: Write. In Stripe, open the key (… → Edit key), set Webhook Endpoints to Write and save, then go back and press Save again. Or make the webhook yourself and paste its signing secret under "I made the webhook myself".' + ` Stripe said: ${error.message}`) };
     return { ok: false, page: said(502, `Stripe did not make the webhook (${error instanceof StripeError ? error.message : 'no answer'}). Nothing was saved. Go back and try again.`) };
   }
   const secret = typeof made?.secret === 'string' ? made.secret : '';
@@ -236,7 +236,7 @@ async function probeManaged(env, shop, { fetcher }) {
       line_items: [{ quantity: 1, price_data: { currency: shop?.currency ?? 'usd', unit_amount: item?.price ?? 500, tax_behavior: 'exclusive', product_data: { name: 'Homie shop check (test, expired at once)', tax_code: defaultTaxCode(item ?? {}) } } }],
       managed_payments: { enabled: true }, metadata: { homie: 'shop-check' },
     }, { fetcher, idempotencyKey: `homie-check-${randomBytes(8).toString('hex')}` });
-    if (typeof s?.id === 'string') { try { await expireCheckoutSession(env, s.id, { fetcher }); } catch { /* it expires by itself */ } }
+    if (typeof s?.id === 'string') { try { await expireCheckoutSession(env, s.id, { fetcher }); } catch (error) { return { ok: false, words: `Stripe took the test checkout but could not expire it (${error instanceof StripeError ? error.message : 'no answer'}). It will expire by itself.` }; } }
     return { ok: true, words: 'Stripe took a test checkout with Managed Payments: it is on for this account (test mode).' };
   } catch (error) {
     return { ok: false, words: `Stripe refused a test checkout with Managed Payments (${error instanceof StripeError ? error.message : 'no answer'}). Finish Managed Payments in Stripe (Settings → Managed Payments: accept the terms, pass the eligibility review), or pick "You are" the seller.` };
@@ -284,14 +284,16 @@ export async function shopConnectManual(root, { managed = null, live = false, lo
             // One read with the key, so a typo is caught here and not at the first sale. It never leaves this computer
             // except to Stripe itself.
             if (verify) {
-              try { await stripeCall(sk, 'GET', '/v1/checkout/sessions', { limit: 1 }, { fetcher }); } catch {
-                say(said(400, 'Stripe did not accept that key for reading checkouts. Check its permissions (Checkout Sessions: Write) and that it is the account you mean, then go back and paste it again.')); return;
+              try { await stripeCall(sk, 'GET', '/v1/checkout/sessions', { limit: 1 }, { fetcher }); } catch (error) {
+                const reason = error instanceof StripeError ? ` Stripe said: ${error.message}` : '';
+                log(`Stripe could not read checkouts.${reason}`);
+                say(said(400, 'Stripe did not accept that key for reading checkouts. Check its permissions (Checkout Sessions: Write) and that it is the account you mean, then go back and paste it again.' + reason)); return;
               }
             }
             let webhook = { made: false };
             if (!hook) {
               const m = await makeWebhook(sk, site, { fetcher });
-              if (!m.ok) { say(m.page); return; }
+              if (!m.ok) { log(m.page.text); say(m.page); return; }
               hook = m.secret;
               webhook = { made: true, id: m.id, older: m.older };
             }
@@ -303,10 +305,13 @@ export async function shopConnectManual(root, { managed = null, live = false, lo
             // The new secret is saved: the older endpoints this kit made for the same address stop sending (turned off,
             // not deleted: the owner can turn one back on in Stripe).
             let disabled = 0;
+            const warnings = [];
             if (okay && webhook.made) {
-              for (const id of webhook.older) { try { await updateWebhookEndpoint(sk, id, { disabled: true }, { fetcher }); disabled += 1; } catch { /* left on; Stripe retries and says so */ } }
+              for (const id of webhook.older) { try { await updateWebhookEndpoint(sk, id, { disabled: true }, { fetcher }); disabled += 1; } catch (error) { warnings.push(`Stripe could not turn off webhook ${id}: ${error instanceof StripeError ? error.message : 'no answer'}`); } }
             }
             const check = okay && !live && chosen === 'stripe-managed' ? await probeManaged(sk, shopNow.shop, { fetcher }) : null;
+            if (check && !check.ok) warnings.push(check.words);
+            for (const warning of warnings) log(warning);
             let tillNote = '';
             if (okay && shopNow.shop && !shopNow.absent && chosen !== shopNow.shop.till) {
               try {
@@ -317,13 +322,14 @@ export async function shopConnectManual(root, { managed = null, live = false, lo
               } catch { tillNote = ''; }
             }
             const narrow = webhook.made ? ' Recommended, 20 seconds: in Stripe, open this key (… → Edit key) and set Webhook Endpoints back to None. The shop never needs it again.' : '';
-            say(said(okay ? 200 : 500, okay ? `Saved to your Worker (${modeOf(key)} mode).${webhook.made ? ' Stripe made the webhook; its secret went straight to your Worker.' : ''}${check ? ` ${check.words}` : ''}${narrow} You can close this page.` : 'Wrangler could not save it (is this computer signed in to Cloudflare? npx wrangler login). Nothing was kept.'));
+            say(said(okay ? 200 : 500, okay ? `Saved to your Worker (${modeOf(key)} mode).${webhook.made ? ' Stripe made the webhook; its secret went straight to your Worker.' : ''}${check?.ok ? ` ${check.words}` : ''}${warnings.length ? ` ${warnings.join(' ')}` : ''}${narrow} You can close this page.` : 'Wrangler could not save it (is this computer signed in to Cloudflare? npx wrangler login). Nothing was kept.'));
             server.close();
             done(okay
               ? {
                 ok: true, command: 'shop connect', saved: true, mode: modeOf(key), till: chosen,
                 webhook: webhook.made ? { made: true, id: webhook.id, url: hookUrlOf(site), turnedOff: disabled } : { made: false, url: hookUrlOf(site) },
                 ...(check ? { managedPayments: check } : {}),
+                ...(warnings.length ? { warnings } : {}),
                 message: `Saved as the Worker secrets STRIPE_KEY and STRIPE_WEBHOOK_SECRET (never shown), ${modeOf(key)} mode, seller: ${chosen === 'stripe-managed' ? 'Stripe (Managed Payments)' : 'the studio'}.${webhook.made ? ` Stripe made the webhook ${webhook.id} for ${hookUrlOf(site)}${disabled ? ` and ${disabled} older one(s) were turned off` : ''}.` : ''}${tillNote}${narrow} homie-studio shop says whether anything else is missing.`,
               }
               : { ok: false, command: 'shop connect', why: 'wrangler secret put failed (sign in with npx wrangler login, then run this again)' });

package/lib/standalone-files.mjs

@@ -105,8 +105,8 @@ export function projectPackage(meta, { targets = TARGETS } = {}) {
 }
 
 /** web/config.js: everything the shell knows about the game it frames. `site` '' is a copy that only plays offline. */
-export function configScript(meta, { target, site = '', share, colours = null, movement = null, params = {} }) {
-  const cfg = { v: 1, game: meta.id, name: meta.name, site: String(site ?? '').replace(/\/+$/, ''), ver: meta.netplayVersion ?? '', ...(movement ? { movement } : {}), params, share, colours, version: meta.version, target };
+export function configScript(meta, { target, site = '', share, colours = null, movement = null, params = {}, room = null }) {
+  const cfg = { v: 1, game: meta.id, name: meta.name, site: String(site ?? '').replace(/\/+$/, ''), ver: meta.netplayVersion ?? '', ...(movement ? { movement } : {}), params, share, colours, ...(room ? { room } : {}), version: meta.version, target };
   return `window.__HOMIE_APP = ${JSON.stringify(cfg, null, 2).replace(/</g, '\\u003c')};\n`;
 }
 

package/lib/standalone.mjs

@@ -388,6 +388,7 @@ export async function standalonePlan(root, id, opts = {}) {
 
 /* ------------------------------------------------------------------ the web folder */
 
+const readJson = (file) => { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } };
 const copyTree = (from, to) => { rmSync(to, { recursive: true, force: true }); cpSync(from, to, { recursive: true, dereference: true }); };
 
 /**
@@ -401,8 +402,11 @@ export function webBundle(root, game, dir, { meta, target = 'web', site = '', st
   rmSync(web, { recursive: true, force: true });
   mkdirSync(web, { recursive: true });
   for (const f of ['index.html', 'shell.js', 'shell.css']) copyFileSync(join(SHELL, f), join(web, f));
-  const m = meta ?? standaloneMeta(studio ?? readStudio(root), game);
-  writeFileSync(join(web, 'config.js'), configScript(m, { target, site, share: sharePlaces(game.screen?.share), colours: uiOf(game), movement: game.netplay?.movement ?? game.movement ?? null }));
+  const row = (readJson(join(root, 'site', 'dist', 'games.json'))?.games ?? []).find((g) => g.id === game.id);
+  const m = { ...(meta ?? standaloneMeta(studio ?? readStudio(root), game)), ...(row?.room ? { netplayVersion: row.netplay?.version ?? null } : {}) };
+  const rules = readJson(join(built, 'rules.json'));
+  if (rules) for (const file of rules.files ?? []) if (!existsSync(join(built, file))) throw new Error(`The rules build is incomplete: ${file} is missing. Build the game again before making its app.`);
+  writeFileSync(join(web, 'config.js'), configScript(m, { target, site, share: sharePlaces(game.screen?.share), colours: uiOf(game), movement: game.netplay?.movement ?? game.movement ?? null, room: row?.room ?? null }));
   copyTree(built, join(web, 'game'));
   const index = join(web, 'game', 'index.html');
   writeFileSync(index, withNetScript(readFileSync(index, 'utf8')));

package/lib/stripe-connect.mjs

@@ -11,7 +11,7 @@ import { readStudio, siteUrl } from './studio.mjs';
 import { hookUrlOf, readShop, shopConnectManual } from './shop.mjs';
 import { syncPaymentLinks } from './shop-links.mjs';
 import { LINKS_STRIPE_VERSION, fullerReason } from '../worker/shop-links.mjs';
-import { formEncode } from '../worker/stripe.mjs';
+import { formEncode, redactStripe } from '../worker/stripe.mjs';
 
 const hash = (s) => createHash('sha256').update(s).digest('hex');
 const failure = (needs, why, extra = {}) => ({ ok: false, command: 'shop connect', needs, why, ...extra });
@@ -28,6 +28,14 @@ export function stripeConnectionInfo(root, { storage = receiptHome(), now = Date
 }
 
 const json = (s) => { try { return JSON.parse(s); } catch { return null; } };
+// Stripe CLI also prints login failures on stderr (stripe/stripe-cli pkg/cmd/root.go).
+// Never fall back to stdout: successful login output can contain credentials.
+const stripeReason = (result, call) => {
+  const message = (json(result?.stdout)?.error ?? json(result?.stderr)?.error)?.message
+    ?? (result?.code !== 0 ? result?.stderr?.trim() : null);
+  return typeof message === 'string' ? ` Stripe said: “${redactStripe(message).slice(0, 400)}” (${call}).` : '';
+};
+
 // This output stays private, including CLI config, completion, errors and API responses.
 export function stripeProcess(args, { cwd, env = process.env } = {}) {
   const childEnv = { ...env, CI: '1', NO_COLOR: '1' };
@@ -94,15 +102,15 @@ export async function shopConnect(root, options = {}) {
       const login = json(start.stdout);
       const complete = completionArgs(login?.next_step);
       if (start.code !== 0 || !stripeURL(login?.browser_url) || !complete || !/^[a-zA-Z0-9 -]{1,100}$/.test(login?.verification_code ?? '')) {
-        return failure('stripe-login', 'Stripe could not start browser approval. Update the official Stripe CLI and try shop connect again. An account administrator may need to enable CLI access in Stripe’s MCP and CLI access settings.');
+        return failure('stripe-login', 'Stripe could not start browser approval. Update the official Stripe CLI and try shop connect again. An account administrator may need to enable CLI access in Stripe’s MCP and CLI access settings.' + stripeReason(start, 'login'));
       }
       log(`Approve your studio’s Stripe account in your browser. Pairing code: ${login.verification_code}. ${login.browser_url}`);
       open(login.browser_url);
       const finished = await cli(complete);
-      if (finished.code !== 0) return failure('stripe-login', 'Stripe approval did not finish. Run shop connect again when ready.');
+      if (finished.code !== 0) return failure('stripe-login', 'Stripe approval did not finish. Run shop connect again when ready.' + stripeReason(finished, 'login completion'));
 
       probe = await cli(['get', '/v1/products', '-d', 'limit=1', ...(live ? ['--live'] : [])]);
-      if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) return failure('stripe-access', 'Stripe is signed in but cannot read Products in the requested mode. Review the account, sandbox and permissions in Stripe, then run shop connect --renew again.');
+      if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) return failure('stripe-access', 'Stripe is signed in but cannot read Products in the requested mode. Review the account, sandbox and permissions in Stripe, then run shop connect --renew again.' + stripeReason(probe, 'GET /v1/products'));
     }
     const site = siteUrl(root);
     if (!site) return failure('deploy', 'Stripe is connected on this computer. Deploy the studio with studio_deploy (Cloudflare approval first if needed), then run shop connect again.', { mode, connected: true });
@@ -114,7 +122,9 @@ export async function shopConnect(root, options = {}) {
       for (const [k, v] of formEncode(params)) args.push('-d', `${k}=${v}`);
       const r = await cli(args);
       const body = json(r.stdout);
-      if (r.code !== 0 || !body || body.error) throw new Error('Stripe API operation failed');
+      if (r.code !== 0 || !body || body.error) {
+        throw Object.assign(new Error('Stripe API operation failed'), { stripeReason: stripeReason(r, `${method} ${path.replace(/\/[^/]*_[A-Za-z0-9]+$/, '/…')}`) });
+      }
       return body;
     };
     const reason = fullerReason(checked.shop);
@@ -129,7 +139,8 @@ export async function shopConnect(root, options = {}) {
         renameSync(`${receiptFile}.tmp`, receiptFile);
       } });
     return { ...result, profile };
-  } catch {
-    return failure('stripe-setup', 'Stripe setup could not finish. Check the studio’s Stripe session and Products, Prices, Payment Links and Webhook Endpoints write permissions, and the Cloudflare login, then run shop connect again. No credentials were printed.');
+  } catch (e) {
+    const said = e?.stripeReason ?? '';
+    return failure('stripe-setup', 'Stripe setup could not finish. Check the studio’s Stripe session and Products, Prices, Payment Links and Webhook Endpoints write permissions, and the Cloudflare login, then run shop connect again. No credentials were printed.' + said);
   } finally { lock.release(); }
 }

package/lib/template-history.json

@@ -1868,6 +1868,89 @@
    }
   },
   "0.35.0": {
+   "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": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": [
+      "57c04f6526e16890",
+      "9e020d69dd6a954e"
+     ],
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
+  },
+  "0.35.1": {
+   "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": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
+  },
+  "0.36.0": {
    "files": {
     "CLAUDE.md": "ddf2b2a0376202f6",
     "README.md": "684b3cca8001673c",

package/lib/typecheck.mjs

@@ -1,3 +1,4 @@
+import { runRulesCompiler } from './rules-compiler.mjs';
 /**
  * `homie-studio build --types` — the games' TypeScript, checked before anything is built.
  *
@@ -6,15 +7,15 @@
  * of its own to run `npx tsc` with.
  *
  *   - The compiler is the STUDIO'S OWN (`typescript` in its node_modules, which a new studio's package.json asks
- *     for). @homie-rocks/studio does not depend on it: the check is something a studio opts into, and a studio that
- *     never does pays nothing for it. Without it the command stops and says the one line that installs it.
+ *     for). This optional check for legacy games keeps using that compiler. Rules games use the toolkit's own
+ *     pinned compiler through typecheckRules below, on every build.
  *   - A game with a tsconfig.json of its own is checked with it. Any other game is checked the way esbuild reads
  *     it: its entry and whatever that imports, as ES2022 for a browser, strictly, with the pictures, sounds and
  *     models it imports as addresses (the build's own loaders).
  *   - Only errors in the game's own files stop the build. A game imports the toolkit's helpers as TypeScript
  *     source, and a creator can do nothing about a line in node_modules; those are counted and said, never fatal.
  *
- * Never run unasked: a plain `build` is exactly as fast as it was.
+ * The legacy check runs only when asked with --types. The rules check is mandatory.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
@@ -105,3 +106,51 @@ export function typecheck(root, games, { log = () => {} } = {}) {
   }
   return { typescript: ts.version, games: rows };
 }
+
+/** Every rules build uses the toolkit's pinned compiler, its own strict settings and declaration-derived faces. */
+export async function typecheckRules(root, g, checked, tune, { log = () => {} } = {}) {
+  const [{ PACKAGE_ROOT }, { rulesTypes, rulesViewTypes, rulesAnswerScopes }] = await Promise.all([import('./studio.mjs'), import('./rules-types.mjs')]);
+  const compiler = createRequire(import.meta.url).resolve('typescript/bin/tsc');
+  const dir = join(root, '.studio', 'types', g.id);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'rules.d.ts'), rulesTypes({ ...checked, answerScopes: await rulesAnswerScopes(join(g.dir, 'src/rules.ts')) }, tune));
+  writeFileSync(join(dir, 'view.d.ts'), rulesViewTypes(checked));
+  writeFileSync(join(dir, 'files.d.ts'), AMBIENT);
+  const project = join(dir, 'tsconfig.json');
+  writeFileSync(project, `${JSON.stringify({ compilerOptions: { ...OPTIONS, checkJs: true, paths: {
+    ...Object.fromEntries(Object.entries(JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).exports)
+      .filter(([, entry]) => entry?.types).map(([name, entry]) => [`@homie-rocks/studio/${name.slice(2)}`, [join(PACKAGE_ROOT, entry.types)]])),
+    '@homie-rocks/studio/rules': [join(dir, 'rules.d.ts')],
+    '@homie-rocks/studio/rules/view': [join(dir, 'view.d.ts')],
+    '@homie-rocks/studio/*': [join(PACKAGE_ROOT, '*')],
+  } }, files: [join(g.dir, 'src/rules.ts'), join(g.dir, g.entry ?? 'src/view.ts'), join(dir, 'files.d.ts')] }, null, 2)}\n`);
+  const res = await runRulesCompiler(compiler, ['-p', project, '--pretty', 'false']);
+  if (res.error) throw new Error(`games/${g.id}: the rules type check could not finish: ${res.error.message}`);
+  const messages = [];
+  for (const line of `${res.stdout ?? ''}\n${res.stderr ?? ''}`.split(/\r?\n/)) {
+    const at = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(line);
+    if (at) {
+      const file = resolve(at[1]);
+      // Imported game helpers count too. Only the toolkit's own implementation is outside the author's remit.
+      if (!file.startsWith(`${PACKAGE_ROOT}${sep}`) && !file.includes(`${sep}node_modules${sep}`) || file.startsWith(`${g.dir}${sep}`)) {
+        const sourceLine = readFileSync(file,'utf8').split(/\r?\n/)[Number(at[2])-1] ?? '';
+        const advice = /Property 'ask'.*type 'never'/.test(at[5]) ? 'This handler scope never calls world.ask, so no answer can arrive here. Handle the answer in the scope that asks.'
+          : /world\.round\.end/.test(sourceLine) && at[4] === 'TS2339' ? 'Only room handlers end a round. Send a declared event to a room handler that calls world.round.end().'
+          : /'check'.*does not exist/.test(at[5]) ? 'Remove the obsolete check key. Generated observations require no exemption.'
+          : /=> (?:GameDecision|GuideDecision)'/.test(at[5]) ? 'A floor returns goal and say names from agents.json with exactly the args and sayArgs each declares, or {} to decline. Forward a request as { goal: ask.k, args: ask.args }.'
+          : /\.args\./.test(sourceLine) ? 'Use the argument names and types declared in agents.json and shapes.view; for a union, narrow its goal or request name before reading variant-specific arguments.'
+          : /unknown/.test(at[5]) ? 'Validate this external value with a type check before reading it.'
+          : /e\.picks/.test(sourceLine) ? 'Check e.ask before reading a question specific to one ask. Picks use the declared choice names, booleans and numbers.'
+          : at[4] === 'TS2339' && /self\./.test(sourceLine) ? 'Declare the field on this entity kind, or use an existing declared name.'
+          : at[4] === 'TS2322' && /join|kind:/.test(sourceLine) ? `room.join returns a player kind: ${checked.schema.kinds.filter(k => k.player).map(k => k.name).join(', ')}.`
+          : at[4] === 'TS2345' && /world\.despawn\s*\(/.test(sourceLine) ? 'world.despawn takes self, the non-player entity running this handler. Send an event to ask another entity to remove itself.'
+          : at[4] === 'TS2345' && /world\.send\s*\(/.test(sourceLine) && /Argument of type.*(?:readonly|pos:)/.test(at[5]) ? 'world.send takes an entity ID. Pass entity.id rather than the entity record.' : '';
+        messages.push(`${relative(root, file)}:${at[2]}:${at[3]} ${at[4]} ${at[5].length > 360 ? at[5].slice(0, 220) + ' … ' + at[5].slice(-100) : at[5]}${advice ? `\n  Repair: ${advice}` : ''}`);
+      }
+    } else if (/^error TS/.test(line)) messages.push(line);
+    else if (/^\s+\S/.test(line) && messages.length) messages[messages.length - 1] += `\n${line.length > 360 ? line.slice(0, 220) + ' … ' + line.slice(-100) : line}`;
+  }
+  if (messages.length) throw new Error(`games/${g.id}: its rules have type errors:\n${messages.slice(0, 30).map((m) => `  ${m}`).join('\n')}`);
+  if (res.status !== 0 && !res.stdout) throw new Error(`games/${g.id}: TypeScript stopped without diagnostics (${res.signal ?? res.status})`);
+  log(`types: games/${g.id}: rules, move and view checked with the toolkit's strict compiler`);
+}