@homie-rocks/studio 0.51.4 → 0.51.5

package/lib/scaffold.mjs

@@ -535,7 +535,7 @@ where it sells and for Stripe's terms. Homie takes no cut.
   player refund window covers items; a tip is never taken back by the player.
 - Flood settings are configurable: buyer attempts 6/minute, address attempts 600/minute,
   new guest buyers 600/hour. Stripe constraints, integer arithmetic, ownership and signatures protect payments.
-- \`shop check\` validates settings; \`stripe_login\` / \`shop connect\` starts Stripe browser approval.
+- \`shop check\` validates settings; \`stripe_shop_plan\` plans and verifies Stripe official MCP operations; \`stripe_webhook\` installs the signing secret privately.
   Never ask a person for a key. Follow the result's next step: deploy first if needed, then rerun connect.
   The default syncs Products, Prices, Payment Links and the webhook through the approved Stripe CLI.
   The Worker stores only links and a signing secret; buying needs no API key or running AI.
@@ -719,7 +719,7 @@ site/.wrangler/
 .wrangler/
 .dev.vars
 .env
-# Stripe Projects (setup --via stripe-projects): credentials stay in its vault and the .env files it syncs, never in git.
+# Provider-owned credential stores and local environment files never belong in git.
 .env.*
 .projects/vault/
 .projects/cache/

package/lib/shop-links.mjs

@@ -6,7 +6,8 @@ import { LINKS_STRIPE_VERSION, linkSettings, paymentLinkURL } from '../worker/sh
 import { HOOK_EVENTS, SHOP_HOOK_EVENTS } from './shop.mjs';
 const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 const same = (a, b) => Object.keys(a ?? {}).length === Object.keys(b).length && Object.entries(b).every(([k, v]) => a?.[k] === v);
-export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, receipt, saveReceipt, bookingSlots = [], local = false }) {
+export const matchesFields = (actual, expected) => Array.isArray(expected) ? Array.isArray(actual) && actual.length === expected.length && expected.every((v,i)=>matchesFields(actual[i],v)) : expected && typeof expected === 'object' ? Object.entries(expected).every(([k,v]) => matchesFields(actual?.[k],v)) : actual === expected;
+export async function reconcilePaymentLinks({ api, shop, slug, site, mode, bookingSlots = [], verifyObjects = false }) {
   const list = async (path, params = {}) => {
     const all = []; let cursor;
     do {
@@ -19,15 +20,16 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     } while (cursor);
     return all;
   };
-  if(local && mode!=='test')throw new Error('Local checkout requires Stripe test mode');
-  const secrets = local ? {code:0,stdout:'[]'} : await w(['secret', 'list']);
-  if (secrets.code !== 0) return { ok: false, needs: 'cloudflare', why: 'Connect Cloudflare and deploy the studio, then run shop connect again.' };
-  const names = JSON.parse(secrets.stdout ?? secrets.out);
-  const has = (name) => names.some((s) => s.name === name);
   const products = await list('/v1/products');
   const prices = await list('/v1/prices');
   const links = await list('/v1/payment_links');
   const own = (o) => o.metadata?.homie === 'shop-links-v1' && o.metadata?.studio === slug && o.metadata?.origin === site;
+  const verifyLink = async (link, params) => {
+    if (!verifyObjects) return;
+    const actual=await api('GET',`/v1/payment_links/${link.id}`,{expand:['line_items']});
+    const normalized={...actual,line_items:actual.line_items?.data?.map(line=>({...line,price:line.price?.id??line.price}))};
+    if(actual.id!==link.id || actual.active!==link.active || actual.url!==link.url || actual.line_items?.has_more===true || !matchesFields(actual.metadata,link.metadata) || !paymentLinkURL(actual.url) || !matchesFields(normalized,params)) throw new Error(`Stripe Payment Link ${link.id} differs from its planned fields. Restore its configuration through Stripe MCP before verifying.`);
+  };
   const config = { v: 1, mode, settings: linkSettings(shop), items: [] };
   const customText=shop.giving?.receiptText ? {custom_text:{submit:{message:shop.giving.receiptText}}} : {};
   const catalogPrices = new Map();
@@ -36,7 +38,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const id = await productIdOf(slug, item.id);
     keepProducts.add(id);
     const metadata = { homie: 'shop-links-v1', studio: slug, origin: site };
-    const fields = { name: item.name, ...(item.blurb ? {description:item.blurb} : {}), tax_code: item.taxCode ?? defaultTaxCode(item), metadata, active: true };
+    const fields = { name: item.name, description:item.blurb??'', tax_code: item.taxCode ?? defaultTaxCode(item), metadata, active: true };
     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);
@@ -48,6 +50,8 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const revision = hash(priceFields);
     let price = prices.find((p) => own(p) && p.product === id && p.metadata?.revision === revision);
     if (!price) price = await api('POST', '/v1/prices', { ...priceFields, metadata: { ...metadata, revision } }, `price-${hash({ priceFields, metadata })}`);
+    if (verifyObjects && ((price.recurring?.interval_count??1)!==1 || Boolean(price.recurring)!==Boolean(item.interval) || Boolean(price.custom_unit_amount)!==(item.price==='choose'))) throw new Error(`Stripe Price ${price.id} has a different payment type from shop.json`);
+    if (verifyObjects && !matchesFields({...price, product:price.product?.id??price.product, ...(price.custom_unit_amount?{custom_unit_amount:{...price.custom_unit_amount,enabled:true}}:{})},priceFields)) throw new Error(`Stripe Price ${price.id} differs from shop.json; restore or archive it through Stripe MCP before planning again.`);
     if (!price.active) await api('POST', `/v1/prices/${price.id}`, { active: true });
     keepPrices.add(price.id);
     catalogPrices.set(item.id, price.id);
@@ -61,6 +65,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const linkRevision = hash({ params, item, policy: shop.policy });
     let link = links.find((p) => own(p) && p.metadata?.revision === linkRevision);
     if (!link) link = await api('POST', '/v1/payment_links', { ...params, metadata: { ...metadata, revision: linkRevision } }, `link-${linkRevision}`);
+    await verifyLink(link,params);
     if (!link.active) await api('POST', `/v1/payment_links/${link.id}`, { active: true });
     if (!paymentLinkURL(link.url) || !/^plink_\w+$/.test(link.id)) throw new Error('Invalid Payment Link');
     keepLinks.add(link.id);
@@ -83,13 +88,14 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const revision=hash(params);
     let link=links.find(p=>own(p)&&p.metadata?.revision===revision);
     if(!link)link=await api('POST','/v1/payment_links',{...params,metadata:{...metadata,revision}},`menu-${revision}`);
+    await verifyLink(link,params);
     if(!link.active)await api('POST',`/v1/payment_links/${link.id}`,{active:true});
     keepLinks.add(link.id);
     config.menus.push({id:link.id,url:link.url,revision,items:items.map(i=>({item:i.id,price:catalogPrices.get(i.id)}))});
   }
   config.slots=[];
   const pause=async link=>{
-    await api('POST',`/v1/payment_links/${link.id}`,{active:false});
+    if(link.active) await api('POST',`/v1/payment_links/${link.id}`,{active:false});
     for(const session of await list('/v1/checkout/sessions',{payment_link:link.id,status:'open'})) {
       await api('POST',`/v1/checkout/sessions/${session.id}/expire`);
     }
@@ -107,11 +113,13 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     let link=links.find(p=>own(p)&&p.metadata?.slot===identity);
     if(!link && (!slot.capacity||slot.active===false))continue;
     if(link?.metadata?.price && link.metadata.price!==catalogPrices.get(item.id))throw new Error('Slot service price changed. Deactivate the old slot and publish a new slot ID after reviewing existing bookings.');
-    if(slot.confirmed!==undefined && link?.active && slot.active!==false)throw new Error('Pause affected slot links before recounting confirmed seats; wait for signed payments, move/refund, then sync the fresh counts.');
+    const seatsRevision=hash({slot,capacity:slot.capacity,confirmed:slot.confirmed});
+    const counted=slot.confirmed!==undefined && link?.metadata?.seats_revision===seatsRevision;
+    if(slot.confirmed!==undefined && !counted && link?.active && slot.active!==false)throw new Error('Pause affected slot links before recounting confirmed seats; wait for signed payments, move/refund, then sync the fresh counts.');
     const count=link?.restrictions?.completed_sessions?.count??0;
     // Initial publication uses capacity exactly. After a reviewed move/refund the
     // AI supplies current confirmed seats; keep the existing Stripe lifetime count.
-    const limit=slot.confirmed===undefined ? slot.capacity : count+slot.capacity-slot.confirmed;
+    const limit=counted ? Number(link.metadata.seats_limit) : slot.confirmed===undefined ? slot.capacity : count+slot.capacity-slot.confirmed;
     const active=slot.active!==false && limit>count;
     const params={...customText,line_items:[{price:catalogPrices.get(item.id),quantity:1}],payment_method_types:['card'],
       restrictions:{completed_sessions:{limit:Math.max(1,limit)}},after_completion:{type:'redirect',redirect:{url:`${site}/shop/thanks?session_id={CHECKOUT_SESSION_ID}`}}};
@@ -119,9 +127,10 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     else {
       // Pause first whenever publishing a changed budget, so old sessions cannot
       // spend a previous capacity after staff moves or removes a slot.
-      if(!active || link.restrictions?.completed_sessions?.limit!==limit)await pause(link);
-      link=await api('POST',`/v1/payment_links/${link.id}`,{restrictions:params.restrictions,active});
+      if(!active || link.restrictions?.completed_sessions?.limit!==Math.max(1,limit))await pause(link);
+      if (link.active !== active || link.restrictions?.completed_sessions?.limit !== Math.max(1,limit) || slot.confirmed!==undefined && !counted) link=await api('POST',`/v1/payment_links/${link.id}`,{restrictions:params.restrictions,active,...(slot.confirmed!==undefined?{metadata:{seats_revision:seatsRevision,seats_limit:String(limit)}}:{})});
     }
+    await verifyLink(link,params);
     keepLinks.add(link.id);
     config.slots.push({...slot,id:link.id,url:link.url,price:catalogPrices.get(item.id),revision:identity,active:link.active,count:link.restrictions?.completed_sessions?.count??0,limit,paused:slot.active===false});
   }
@@ -132,11 +141,40 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const portals=await list('/v1/billing_portal/configurations');
     let portal=portals.find(p=>own(p));
     const params={features:{subscription_cancel:{enabled:true},payment_method_update:{enabled:true},invoice_history:{enabled:true}},login_page:{enabled:true},business_profile:{headline:'Manage your membership or giving'},default_return_url:`${site}/shop/`,metadata};
-    portal=await api('POST',portal?`/v1/billing_portal/configurations/${portal.id}`:'/v1/billing_portal/configurations',params);
+    if (!portal || !matchesFields(portal, params)) portal=await api('POST',portal?`/v1/billing_portal/configurations/${portal.id}`:'/v1/billing_portal/configurations',params, portal?undefined:`portal-${hash({slug,site,params})}`);
     config.portal=portal.login_page?.url;
   }
-  if(local)return {ok:true,command:'shop connect',local:true,mode,config};
-  const purchases = root ? await (await import('./purchase-links.mjs')).syncPurchaseLinks({ root, api, slug, site, mode, list, till: shop.purchasesTill ?? shop.till }) : null;
+  const retire = [
+    ...links.filter(p=>own(p)&&p.active&&!keepLinks.has(p.id)).map(p=>({method:'POST',path:`/v1/payment_links/${p.id}`,params:{active:false}})),
+    ...prices.filter(p=>own(p)&&p.active&&!keepPrices.has(p.id)).map(p=>({method:'POST',path:`/v1/prices/${p.id}`,params:{active:false}})),
+    ...products.filter(p=>own(p)&&p.active&&!keepProducts.has(p.id)).map(p=>({method:'POST',path:`/v1/products/${p.id}`,params:{active:false}})),
+  ];
+  return {config, retire};
+}
+
+export async function syncPaymentLinks(options) {
+  const {root, api, shop, slug, site, mode, w, receipt, saveReceipt, local = false} = options;
+  if (local && mode !== 'test') throw new Error('Local checkout requires Stripe test mode');
+  const {config, retire} = options.catalog ?? await reconcilePaymentLinks(options);
+  if (local) return {ok:true, command:'shop connect', local:true, mode, config};
+  const list = async (path,params={}) => {
+    const all=[]; let cursor;
+    do {
+      const page=await api('GET',path,{...params,limit:100,...(cursor?{starting_after:cursor}:{})});
+      if (!Array.isArray(page.data)) throw new Error('Incomplete Stripe list');
+      all.push(...page.data);
+      const next=page.has_more?page.data.at(-1)?.id:null;
+      if(page.has_more && (!next || next===cursor))throw new Error('Incomplete Stripe pagination');
+      cursor=next;
+    }while(cursor);
+    return all;
+  };
+  const secrets=await w(['secret','list']);
+  if(secrets.code!==0)return {ok:false,needs:'cloudflare',why:'Connect Cloudflare before installing the shop.'};
+  const names=JSON.parse(secrets.stdout??secrets.out);
+  const has=name=>names.some(s=>s.name===name);
+
+  const purchases = root && !options.catalog ? await (await import('./purchase-links.mjs')).syncPurchaseLinks({ root, api, slug, site, mode, list, till: shop.purchasesTill ?? shop.till }) : null;
   const purchaseSecrets = {};
   if (purchases?.config.offers.length && !has('PURCHASE_SIGNING_KEYS')) {
     const { generateKeyPair, exportJWK } = await import('jose');
@@ -166,9 +204,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
   }
   await purchases?.retire();
   // Retire only after the replacement configuration and signing secret are installed.
-  for (const link of links.filter((p) => own(p) && p.active && !keepLinks.has(p.id))) await api('POST', `/v1/payment_links/${link.id}`, { active: false });
-  for (const price of prices.filter((p) => own(p) && p.active && !keepPrices.has(p.id))) await api('POST', `/v1/prices/${price.id}`, { active: false });
-  for (const product of products.filter((p) => own(p) && p.active && !keepProducts.has(p.id))) await api('POST', `/v1/products/${product.id}`, { active: false });
+  if (!options.catalog) for (const op of retire) await api(op.method, op.path, op.params);
   for (const e of endpoints.filter((e) => e.id !== endpoint.id && e.url === url && e.metadata?.homie === 'shop-v1' && e.status !== 'disabled')) await api('POST', `/v1/webhook_endpoints/${e.id}`, { disabled: true });
   return { ok: true, command: 'shop connect', mode, keyless: true, saved: !unchanged, alreadyConnected: Boolean(unchanged), webhook: { id: endpoint.id, url }, verifiedPurchase: false,
     message: 'Your shop uses Stripe Payment Links. No Stripe API key is stored in the Worker.',

package/lib/shop-listen.mjs

@@ -0,0 +1,43 @@
+/** Private local Stripe forwarding. Only the allowlisted readiness line reaches the model. */
+import {spawn} from 'node:child_process';
+import {readFileSync,writeFileSync,existsSync,chmodSync} from 'node:fs';
+import {join} from 'node:path';
+import {stripeProcess,completionArgs} from './stripe-connect.mjs';
+export function saveLocalStripe(root,values) {
+  const file=join(root,'.dev.vars');
+  let text=existsSync(file)?readFileSync(file,'utf8'):'';
+  for(const [key,value] of Object.entries(values)) {
+    text=text.replace(new RegExp(`^${key}=.*\\n?`,'gm'),'');
+    text+=`\n${key}=${value}\n`;
+  }
+  writeFileSync(file,text,{mode:0o600});
+  chmodSync(file,0o600);
+}
+export async function shopListen(root,{profile,port=8787,log=()=>{},exec=stripeProcess,spawnProcess=spawn}={}) {
+  if(!profile || !Number.isInteger(Number(port)) || Number(port)<1 || Number(port)>65535)throw new Error('Supply a sandbox profile and local port');
+  const cli=args=>exec(['--project-name',profile,...args],{cwd:root});
+  const probe=await cli(['get','/v1/products','-d','limit=1']);
+  if(probe.code!==0) {
+    const start=await cli(['login','--non-interactive']);
+    let login;try{login=JSON.parse(start.stdout);}catch{}
+    const complete=completionArgs(login?.next_step);
+    const u=login?.browser_url;
+    if(!complete || !/^https:\/\/(dashboard|access)\.stripe\.com\//.test(u??''))throw new Error('Update Stripe CLI and retry local browser approval');
+    log(`Approve Stripe sandbox access: ${u}`);
+    if((await cli(complete)).code!==0)throw new Error('Stripe browser approval did not finish');
+  }
+  const env={...process.env};for(const key of Object.keys(env))if(key.startsWith('STRIPE_'))delete env[key];
+  return new Promise((resolve,reject)=>{
+    const child=spawnProcess('stripe',['--project-name',profile,'listen','--all-snapshot','--forward-to',`http://localhost:${port}/api/shop/hook`],{cwd:root,env,stdio:['ignore','pipe','pipe']});
+    let buffer='',ready=false;
+    const capture=data=>{
+      buffer=(buffer+data.toString()).slice(-8192);
+      const secret=/whsec_[A-Za-z0-9+/=_-]+(?=[\s\x1b])/.exec(buffer)?.[0];
+      if(secret && !ready){saveLocalStripe(root,{STRIPE_WEBHOOK_SECRET:secret});ready=true;buffer='';log('Stripe sandbox forwarding ready. Signing secret saved privately; start/restart homie-studio dev.');}
+    };
+    child.stdout.on('data',capture);child.stderr.on('data',capture);
+    child.on('error',()=>reject(new Error('Install Stripe CLI before local forwarding')));
+    const stop=()=>child.kill();process.once('SIGTERM',stop);process.once('SIGINT',stop);
+    child.on('close',code=>{process.removeListener('SIGTERM',stop);process.removeListener('SIGINT',stop);resolve({ok:ready&&code===0,command:'shop listen',ready});});
+  });
+}

package/lib/shop-local.mjs

@@ -27,5 +27,5 @@ export async function shopConnectLocal(root,{url,profile,exec=stripeProcess}={})
  vars=vars.replace(/^STRIPE_(?:SHOP_LINKS|CHECKOUT_MODE)=.*\n?/gm,'');
  vars+=`\nSTRIPE_CHECKOUT_MODE=links\nSTRIPE_SHOP_LINKS=base64:${Buffer.from(JSON.stringify(r.config)).toString('base64')}\n`;
  writeFileSync(file,vars,{mode:0o600});
- return {ok:true,command:'shop connect',local:true,mode:'test',url:origin.origin,message:'Test Payment Links saved to root .dev.vars.',next:[`stripe --project-name ${profile} listen --all-snapshot --forward-to http://localhost:${origin.port||80}/api/shop/hook`,'Put the listener signing secret in root .dev.vars as STRIPE_WEBHOOK_SECRET, then start/restart homie-studio dev --lan. Keep the listener running.','Open the same Wi-Fi address on phones; complete Stripe test checkout and verify the paid order and app event.']};
+ return {ok:true,command:'shop connect',local:true,mode:'test',url:origin.origin,message:'Test Payment Links saved to root .dev.vars.',next:[`homie-studio shop listen --profile '${profile}' --port ${origin.port||80}`,'The listener saves the signing secret privately. Start/restart homie-studio dev --lan after it reports ready.','Open the same Wi-Fi address on phones and verify the paid order and app event.']};
 }

package/lib/shop-mcp.mjs

@@ -0,0 +1,58 @@
+/** Pure, incremental Stripe plan. The owner's AI supplies public API reads; no Stripe transport here. */
+import {createHash} from 'node:crypto';
+import {existsSync, readFileSync, mkdirSync, writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {readShop, SHOP_HOOK_EVENTS} from './shop.mjs';
+import {readStudio, siteUrl} from './studio.mjs';
+import {reconcilePaymentLinks} from './shop-links.mjs';
+import {fullerReason, LINKS_STRIPE_VERSION} from '../worker/shop-links.mjs';
+const hash = x => createHash('sha256').update(JSON.stringify(x)).digest('hex');
+export const readKey = (path, params) => JSON.stringify([path,Object.fromEntries(Object.entries(params).sort(([a],[b])=>a.localeCompare(b)))]);
+export async function shopMcpPlan(root, {observations = [], mode = 'test', url, slots, verify = false} = {}) {
+  const checked=readShop(root);
+  if(!checked.ok || checked.absent) return {ok:false,why:'Create and check shop.json first.'};
+  if(!['test','live'].includes(mode))throw new Error('Choose test or live mode');
+  const reason=fullerReason(checked.shop);
+  if(reason)return {ok:false,why:reason+' Adjust those settings to use Payment Links; no key is required.'};
+  const studio=readStudio(root), address=url??siteUrl(root);
+  if(!address)return {ok:false,needs:'site',why:'Supply the local test URL, or deploy the studio before planning its public checkout links.'};
+  const site=new URL(address).origin;
+  const local=new URL(site).protocol==='http:';
+  if(local && (mode!=='test' || !/^(localhost|127\.0\.0\.1|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+)$/.test(new URL(site).hostname)))throw new Error('Local checkout requires a private HTTP address and test mode');
+  if(!local && new URL(site).protocol!=='https:')throw new Error('Use the studio HTTPS address');
+  const bookingSlots=slots??(existsSync(join(root,'.studio','booking-slots.json'))?JSON.parse(readFileSync(join(root,'.studio','booking-slots.json'),'utf8')):[]);
+  const slug=local?'local-'+createHash('sha256').update(root).digest('hex').slice(0,16):studio.slug;
+  // Reject secrets before persisting observations. Webhook creation is never part of this plan.
+  if(/(?:whsec_|[rs]k_(?:test|live)_)/.test(JSON.stringify(observations)))throw new Error('Supply only public catalog reads, never credentials or webhook creation responses');
+  const api=async(method,path,params={},idempotency)=>{
+    if(method!=='GET')throw {next:{method,path,params,...(idempotency?{idempotency}:{}),retry:'Read fresh before retrying; updates set desired fields and are idempotent.'}};
+    const found=observations.find(o=>readKey(o.path,o.params??{})===readKey(path,params));
+    if(!found)throw {next:{method,path,params}};
+    const body=found.body;
+    if(!body || body.error || body.livemode !== undefined && body.livemode !== (mode==='live') || body.data?.some(o=>o.livemode !== undefined && o.livemode !== (mode==='live')))throw new Error('Stripe read has an error or wrong mode');
+    return body;
+  };
+  const base={command:verify?'shop verify':'shop plan',mode,site,apiVersion:LINKS_STRIPE_VERSION,
+    webhook:{method:'POST',path:'/v1/webhook_endpoints',private:true,params:{url:`${site}/api/shop/hook`,enabled_events:SHOP_HOOK_EVENTS,api_version:LINKS_STRIPE_VERSION,metadata:{homie:'shop-v1'},description:'Studio shop'}}};
+  try {
+    const catalog=await reconcilePaymentLinks({api,shop:checked.shop,slug,site,mode,bookingSlots,verifyObjects:true});
+    if(checked.shop.items.some(item=>item.interval) && !/^https:\/\/billing\.stripe\.com\//.test(catalog.config.portal??''))throw new Error('Invalid Stripe portal URL');
+    const result={...base,ok:true,verified:true,verifiedAt:new Date().toISOString(),...catalog,local, fingerprint:hash({shop:checked.shop,bookingSlots,site,mode,catalog})};
+    return result;
+  } catch(e) {
+    if(!e.next)throw e;
+    return {...base,ok:!verify,verified:false,next:e.next,instructions:e.next.method==='GET'?'Read through Stripe MCP; append {path,params,body} to observations, including every pagination page.':'Perform this exact operation through Stripe MCP. Then discard observations and read fresh before planning again. Do not create the webhook through MCP.'};
+  }
+}
+export async function saveMcpVerification(root, options) {
+  const result=await shopMcpPlan(root,{...options,verify:true});
+  if(result.verified) {
+    if(result.local) {
+      const {saveLocalStripe}=await import('./shop-listen.mjs');
+      saveLocalStripe(root,{STRIPE_CHECKOUT_MODE:'links',STRIPE_SHOP_LINKS:'base64:'+Buffer.from(JSON.stringify(result.config)).toString('base64')});
+    }
+    mkdirSync(join(root,'.studio'),{recursive:true});
+    writeFileSync(join(root,'.studio','stripe-mcp.json'),JSON.stringify({options,result},null,2));
+  }
+  return result;
+}

package/lib/stripe-connect.mjs

@@ -72,6 +72,10 @@ export function completionArgs(step) {
 }
 
 export async function shopConnect(root, options = {}) {
+  const fail=(...args)=>{
+    const result=failure(...args);
+    return options.webhookOnly?{...result,command:'shop webhook',why:result.why.replaceAll('shop connect','shop webhook')}:result;
+  };
   if (options.manual || options.fromClipboard) {
     const result = await shopConnectManual(root, options);
     if (result.ok) rmSync(join(receiptDir(root, options.storage ?? receiptHome()), 'test.json'), { force: true });
@@ -81,19 +85,32 @@ export async function shopConnect(root, options = {}) {
     storage = receiptHome(), wrangler = null } = options;
   const mode = live ? 'live' : 'test';
   const checked = readShop(root);
-  if (!checked.ok || checked.absent) return failure('shop', 'Create and check shop.json first: homie-studio shop init, then shop check.');
-  if (options.managed === true && checked.shop.till !== 'stripe-managed') return failure('shop-settings', 'For Managed Payments, set shop.json till to stripe-managed and deploy that choice before connecting. Stripe’s own eligibility and terms still apply.');
+  if (!checked.ok || checked.absent) return fail('shop', 'Create and check shop.json first: homie-studio shop init, then shop check.');
+  if (options.managed === true && checked.shop.till !== 'stripe-managed') return fail('shop-settings', 'For Managed Payments, set shop.json till to stripe-managed and deploy that choice before connecting. Stripe’s own eligibility and terms still apply.');
+  let catalog, mcpAccount;
+  if (options.webhookOnly) {
+    try {
+      const {saveMcpVerification} = await import('./shop-mcp.mjs');
+      const saved=JSON.parse(readFileSync(join(root,'.studio','stripe-mcp.json'),'utf8'));
+      if(!saved.result?.verifiedAt || Date.now()-Date.parse(saved.result.verifiedAt)>15*60_000) return fail('verify','Run shop verify with fresh Stripe MCP reads before installing the webhook (verification is valid for 15 minutes).');
+      const verified=await saveMcpVerification(root,saved.options);
+      if(!verified.verified || verified.local || verified.mode!==mode || verified.site!==new URL(siteUrl(root)).origin) return fail('verify','Run shop verify with fresh Stripe MCP reads for this site and mode first.');
+      mcpAccount=saved.options.account;
+      if(!/^acct_[A-Za-z0-9]+$/.test(mcpAccount??''))return fail('account','Verify with the Stripe MCP account ID first.');
+      catalog={config:verified.config,retire:verified.retire};
+    } catch { return fail('verify','Run shop verify with fresh Stripe MCP reads for this site first.'); }
+  }
   const id = hash(realpathSync(root)).slice(0, 24);
-  const profile = `homie-${id}`;
+  const profile = options.profile ?? `homie-${id}`;
   const dir = join(storage, id);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   // Reuse the toolkit’s process-aware lock, in the private receipt folder. Dead processes do not strand setup.
   const lock = lockDeploy(dir);
-  if (!lock.ok) return failure('busy', 'Stripe connection is already running for this studio. Wait for that command to finish.');
+  if (!lock.ok) return fail('busy', 'Stripe connection is already running for this studio. Wait for that command to finish.');
   try {
     const cli = (args) => exec(['--project-name', profile, ...args], { cwd: root });
     const installed = await cli(['--version']);
-    if (installed.code !== 0) return failure('stripe-cli', 'Install Stripe’s official CLI, then run shop connect again.', { next: ['npm install -g @stripe/cli@latest'] });
+    if (installed.code !== 0) return fail('stripe-cli', 'Install Stripe’s official CLI, then run shop connect again.', { next: ['npm install -g @stripe/cli@latest'] });
 
     // A read both checks existing credentials and lets Stripe refresh its OAuth session itself.
     let probe = renew ? { code: 1 } : await cli(['get', '/v1/products', '-d', 'limit=1', ...(live ? ['--live'] : [])]);
@@ -102,21 +119,25 @@ 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.' + stripeReason(start, 'login'));
+        return fail('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.' + stripeReason(finished, 'login completion'));
+      if (finished.code !== 0) return fail('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.' + stripeReason(probe, 'GET /v1/products'));
+      if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) return fail('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'));
+    }
+    if (options.webhookOnly) {
+      const accountResult=await cli(['get','/v1/account',...(live?['--live']:[])]);
+      if(accountResult.code!==0 || json(accountResult.stdout)?.id!==mcpAccount) return fail('account','Stripe CLI and MCP must select the same account. Verify with the MCP account ID first.');
     }
     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 });
+    if (!site) return fail('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 });
     let target;
-    try { target = new URL(site); } catch { return failure('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.'); }
-    if (target.protocol !== 'https:' || target.username || target.password || /^(localhost|127\.|\[::1\])/.test(target.hostname)) return failure('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.');
+    try { target = new URL(site); } catch { return fail('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.'); }
+    if (target.protocol !== 'https:' || target.username || target.password || /^(localhost|127\.|\[::1\])/.test(target.hostname)) return fail('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.');
     const api = async (method, path, params, idempotency) => {
       const args = [method.toLowerCase(), path, '--stripe-version', LINKS_STRIPE_VERSION, ...(live ? ['--live'] : []), ...(idempotency ? ['--idempotency', idempotency] : [])];
       for (const [k, v] of formEncode(params)) args.push('-d', `${k}=${v}`);
@@ -128,20 +149,20 @@ export async function shopConnect(root, options = {}) {
       return body;
     };
     const reason = fullerReason(checked.shop);
-    if (reason) return failure('fuller-checkout', reason, { mode, connected: true });
+    if (reason) return fail('fuller-checkout', reason, { mode, connected: true });
     const studio = readStudio(root);
     const w = wrangler ?? runner(root, studio.cloudflare?.accountId ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
     const receiptFile = join(dir, `${mode}.json`);
     const receipt = existsSync(receiptFile) ? json(readFileSync(receiptFile, 'utf8')) : null;
-    const result = await syncPaymentLinks({ root, api, shop: checked.shop, slug: studio.slug, site: target.origin, mode, w, receipt,
+    const result = await syncPaymentLinks({ catalog, root, api, shop: checked.shop, slug: studio.slug, site: target.origin, mode, w, receipt,
       bookingSlots: options.bookingSlots ?? (existsSync(join(root,'.studio','booking-slots.json')) ? JSON.parse(readFileSync(join(root,'.studio','booking-slots.json'),'utf8')) : []),
       saveReceipt: (record) => {
         writeFileSync(`${receiptFile}.tmp`, JSON.stringify(record), { mode: 0o600 });
         renameSync(`${receiptFile}.tmp`, receiptFile);
       } });
-    return { ...result, profile };
+    return { ...result, command:options.webhookOnly?'shop webhook':result.command, profile };
   } 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);
+    return fail('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

@@ -3708,6 +3708,51 @@
      }
     }
    }
+  },
+  "0.51.5": {
+   "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)": "c20d90de21cde0c7",
+     "## 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)": [
+      "0df5a5fe1833c624",
+      "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)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/upgrade-media.mjs

@@ -0,0 +1,13 @@
+/** Retire the exact guidance shipped by Homie without opening credential files. */
+export const RETIRED_MEDIA_GUIDANCE = "### Existing provider credentials\n\nThe tools read `FAL_KEY` or `ELEVENLABS_API_KEY` first, then the plain single-line\nkey in `~/.homie/keys/fal-key` or `~/.homie/keys/elevenlabs-key`. They also accept\n`~/.homie/workspace/fal-key` and `~/.homie/workspace/elevenlabs-key` from earlier\ninstalls. Checks name the source, never the key. Keep these files private (mode\n0600); never copy them into a studio. ElevenLabs also accepts its CLI browser\nsign-in and the existing Stripe Projects connection. Run the tool\u2019s `check`\nbefore declaring a provider disconnected.\n";
+export const OFFICIAL_MEDIA_GUIDANCE = `### Official media connections
+
+Use the official fal and ElevenLabs plugins in the AI client, with their browser sign-in.
+Homie never reads provider credentials. Cloudflare deploys use Wrangler login; official
+Cloudflare MCP tools inspect logs, Workers Issues and D1. Follow the matching toolkit's
+guides/studio-setup/references/OFFICIAL-MEDIA.md. Retired Homie generation scripts have
+no compatibility path. Keep existing assets and receipts; do not migrate credential files.
+`;
+export function upgradeMediaGuidance(text) {
+  return text.replace(RETIRED_MEDIA_GUIDANCE.trimEnd(), OFFICIAL_MEDIA_GUIDANCE.trimEnd());
+}

package/lib/upgrade.mjs

@@ -1,3 +1,4 @@
+import { upgradeMediaGuidance } from './upgrade-media.mjs';
 import {appPresetChanges} from './upgrade-app-presets.mjs';
 import {refreshWorkerConfig} from './worker-config.mjs';
 /**
@@ -199,8 +200,17 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
   if (Object.keys(missingScripts).length) changes.push({ file: 'package.json', kind: 'scripts', what: `add scripts: ${Object.keys(missingScripts).join(', ')}`, scripts: missingScripts });
   if (studio.homie?.studio !== STUDIO_VERSION) changes.push({ file: 'studio.json', kind: 'version', what: `homie.studio ${studio.homie?.studio ?? '(none)'} → ${STUDIO_VERSION}`, to: STUDIO_VERSION });
 
+  const mediaFiles = new Set();
+  for (const file of ['AGENTS.md', 'CLAUDE.md', 'README.md']) {
+    const from = read(root, file);
+    if (from === null) continue;
+    const text = upgradeMediaGuidance(from);
+    if (text !== from) { changes.push({ file, kind: 'update-file', what: 'replace retired Homie credential guidance with official plugin connections', from, text }); mediaFiles.add(file); }
+  }
+
   // AGENTS.md, section by section; the other template files whole.
   for (const rel of TEMPLATE_FILES) {
+    if (mediaFiles.has(rel)) continue;
     const mine = read(root, rel);
     const want = tmpl[rel];
     if (want === undefined) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.51.4",
+  "version": "0.51.5",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/parts/PARTS.md

@@ -240,7 +240,7 @@ Paid releases use a **separate private R2 bucket and `PURCHASE_MEDIA` binding**.
 
 Stripe's [MPP guide](https://docs.stripe.com/payments/machine/mpp) initializes the Stripe client with a secret credential. Its [x402 guide](https://docs.stripe.com/payments/machine/x402) separates the on-chain facilitator settlement from authenticated PaymentIntent recording. **x402 itself does not require a Stripe API key**; this supported path records money into the seller's Stripe books as Stripe documents. The keyless Payment Link path uses [signed webhooks](https://docs.stripe.com/webhooks) instead of provider reads. CLI OAuth is not exported as a Worker REST credential; see [the setup research](../../../docs/stripe-connect-research.md).
 
-For a fuller connection, the AI operates Stripe's [key-creation page](https://docs.stripe.com/keys), selects the necessary permissions and clicks Copy, then runs `shop connect --from-clipboard` (`--live` for live mode). The local command privately reads the clipboard, verifies the key, makes the webhook and writes secrets to Wrangler stdin, then clears the clipboard. **The human only handles provider sign-in, verification or approval prompts**; their count is controlled by Stripe. Never ask the person to find or paste a key when browser control is available. No supported public API to mint a persistent Stripe REST credential from the CLI approval was established. On macOS this uses `pbpaste`/`pbcopy`, Windows its clipboard commands, and Linux Wayland `wl-paste`/`wl-copy`; other desktops require an equivalent private credential transport. The manual local form remains an explicit fallback, not the default instruction. Live CDP credentials likewise belong to the seller and should be transferred privately by the AI from the provider's setup; no Homie account is involved.
+Owner setup uses Stripe’s official OAuth plugin and Homie’s private webhook installation; read [SHOP.md](../shop/SHOP.md). Runtime-credential machine payment integrations are developer work, not an owner fallback. Never ask an owner to create or copy a key.
 
 Turnstile is optional. If the studio configures it, the fallback verifies its hostname and action. The per-address Worker rate limiter remains configurable flood protection. Machine payment proofs are verified by the protocol libraries.
 

package/rules/view.ts

@@ -728,6 +728,10 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     while (stepped < t) {
       stepped += 1;
       step(stepped, stepped === t);
+      // fire() can read/cache the own entity before this pump advances it.
+      // A renderer later in the same callback must see the completed step,
+      // not hold that effect's old pose until the next (possibly early) frame.
+      presentedEntity = null;
       if (stepped % sendEvery === sendEvery - 1) flush(now, stepped);
     }
   }