@homie-rocks/studio 0.24.2 → 0.24.3

package/lib/projects.mjs

@@ -0,0 +1,311 @@
+/**
+ * `homie-studio setup --via stripe-projects [--with elevenlabs] [--accept-tos] [--dry-run]` (@homie-rocks/studio
+ * 0.24.3, a PROTOTYPE): a creator with no Cloudflare account (and no ElevenLabs) gets both through Stripe Projects
+ * (docs.stripe.com/projects), Stripe's CLI plugin that makes or links provider accounts and hands their credentials to
+ * the project. Homie's own paths (`npx wrangler login`, an ElevenLabs sign-in) stay the default; this is an option.
+ *
+ * What it does, in order, and where it stops to hand a step to the person (`needs`):
+ *   1. the Stripe CLI (1.40.0 or later) and its Projects plugin are here;
+ *   2. this folder is a Stripe project, signed in to the PERSON'S OWN Stripe account (`stripe projects init` opens
+ *      Stripe's sign-in in the browser: the person signs in, then this runs again);
+ *   3. the catalog has Cloudflare's Workers service (and ElevenLabs' with --with elevenlabs);
+ *   4. the person said yes to the provider's terms (only then --accept-tos is passed on); the services are added on
+ *      their free plans: this never passes --confirm-paid-service, and stops if Stripe reports anything paid;
+ *      an existing Cloudflare account is linked through Cloudflare's own approval page (`stripe projects link`);
+ *      a Stripe email with no Cloudflare account gets a new one from Cloudflare;
+ *   5. the credentials are where Projects put them (`stripe projects env --json` lists NAMES only): the account id
+ *      goes into studio.json, the token stays in Projects' vault and its git-ignored output file, and studio.json says
+ *      `cloudflare.auth: "stripe-projects"` so every Wrangler run here takes it from there (lib/projects-env.mjs);
+ *   6. read-only checks with that token: Wrangler is signed in, D1 and Workers AI answer (R2 is optional and needs a
+ *      payment method on Cloudflare, so it is only reported);
+ *   7. .gitignore keeps `.env`, `.env.*`, `.projects/vault/` and `.projects/cache/` out of git.
+ * Then `npm run deploy` works as always.
+ *
+ * Never: a value of any credential in output, a file of ours, an argument or a log (Projects' own rule too: names
+ * only); a Stripe login that is not the person's; a paid plan; a payment method (the free plans need none).
+ *
+ * Unverified until a real run (the docs do not say): the exact JSON shapes of `status`, `search` and `env --json`
+ * (read tolerantly here), the ElevenLabs service's slug and env name, and the Cloudflare token's permission groups
+ * (step 6 measures what it can do instead of assuming).
+ */
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runner } from './cloudflare.mjs';
+import { envFileOf, readDotenv } from './projects-env.mjs';
+import { readStudio, writeStudio } from './studio.mjs';
+
+export const MIN_STRIPE_CLI = '1.40.0';
+export const TERMS = Object.freeze({
+  cloudflare: 'https://www.cloudflare.com/terms/',
+  elevenlabs: 'https://elevenlabs.io/terms-of-use',
+});
+/** What .gitignore must hold before any credential lands in the folder. */
+export const IGNORED = Object.freeze(['.env', '.env.*', '.projects/vault/', '.projects/cache/']);
+
+function defaultExec(cmd, args, { cwd, env, timeout = 180_000 } = {}) {
+  const r = spawnSync(cmd, args, { cwd, env: env ?? process.env, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024 });
+  if (r.error) return { code: r.error.code === 'ENOENT' ? 127 : r.error.code === 'ETIMEDOUT' ? 124 : 1, stdout: '', stderr: String(r.error.message) };
+  return { code: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+/** The first JSON value in a command's output (CLIs print a line or two before it), or null. */
+export function jsonOf(text) {
+  const t = String(text ?? '');
+  let i = t.search(/[[{]/);
+  while (i >= 0) {
+    const end = Math.max(t.lastIndexOf('}'), t.lastIndexOf(']'));
+    for (const piece of [t.slice(i), end > i ? t.slice(i, end + 1) : null]) {
+      if (piece === null) continue;
+      try { return JSON.parse(piece); } catch { /* the next try */ }
+    }
+    const next = t.slice(i + 1).search(/[[{]/);
+    i = next < 0 ? -1 : i + 1 + next;
+  }
+  return null;
+}
+
+/** Every string in a JSON value (keys too), for reading shapes the docs do not pin down. */
+function stringsIn(value, out = [], depth = 0) {
+  if (depth > 12 || value === null || value === undefined) return out;
+  if (typeof value === 'string') out.push(value);
+  else if (Array.isArray(value)) for (const v of value) stringsIn(v, out, depth + 1);
+  else if (typeof value === 'object') for (const [k, v] of Object.entries(value)) { out.push(k); stringsIn(v, out, depth + 1); }
+  return out;
+}
+
+/** provider/service slugs named anywhere in a JSON answer ("cloudflare/workers"), and provider + service pairs. */
+export function servicesIn(value) {
+  const found = new Set();
+  for (const s of stringsIn(value)) if (/^[a-z0-9][a-z0-9_.-]*\/[a-z0-9][a-z0-9_:.-]*$/i.test(s)) found.add(s.toLowerCase());
+  const walk = (v, depth = 0) => {
+    if (depth > 12 || !v || typeof v !== 'object') return;
+    if (Array.isArray(v)) { v.forEach((x) => walk(x, depth + 1)); return; }
+    const p = typeof v.provider === 'string' ? v.provider : typeof v.provider?.id === 'string' ? v.provider.id : null;
+    const s = typeof v.service === 'string' ? v.service : typeof v.service?.id === 'string' ? v.service.id : null;
+    if (p && s) found.add((s.includes('/') ? s : `${p}/${s}`).toLowerCase());
+    Object.values(v).forEach((x) => walk(x, depth + 1));
+  };
+  walk(value);
+  return [...found];
+}
+
+/** Environment variable NAMES in `stripe projects env --json` (values are never there, and never read from it). */
+export function envNamesIn(value) {
+  return [...new Set(stringsIn(value).filter((s) => /^[A-Z][A-Z0-9_]{2,}$/.test(s)))];
+}
+
+/** Whether an answer says something costs money: a price or amount above 0, or a plan named paid. */
+export function paidIn(value) {
+  let paid = false;
+  const walk = (v, key = '', depth = 0) => {
+    if (paid || depth > 12 || v === null || v === undefined) return;
+    if (typeof v === 'number') { if (/price|amount|cost|monthly/i.test(key) && v > 0) paid = true; return; }
+    if (typeof v === 'string') { if (/^(tier|plan|plan_id|tier_id)$/i.test(key) && /paid|\bpro\b|scale|business|enterprise/i.test(v) && !/free/i.test(v)) paid = true; return; }
+    if (Array.isArray(v)) { v.forEach((x) => walk(x, key, depth + 1)); return; }
+    if (typeof v === 'object') for (const [k, x] of Object.entries(v)) walk(x, k, depth + 1);
+  };
+  walk(value);
+  return paid;
+}
+
+const CODES = ['PROVIDER_NOT_LINKED', 'BROWSER_AUTH_REQUIRED', 'NOT_INITIALIZED', 'PROJECT_NOT_FOUND', 'TOS_NOT_ACCEPTED', 'PAYMENT_METHOD_REQUIRED', 'PAID_SERVICE_CONFIRMATION_REQUIRED'];
+/** The error code a Projects command answered with (from its JSON or its words). */
+export function codeOf(r) {
+  const text = `${r?.stdout ?? ''}\n${r?.stderr ?? ''}`;
+  const j = jsonOf(text);
+  const failed = j && typeof j === 'object' && (j.error || j.ok === false || j.success === false || j.status === 'error');
+  const fromJson = failed ? (j.error?.code ?? j.code ?? null) : null;
+  if (typeof fromJson === 'string' && fromJson) return fromJson.toUpperCase();
+  for (const c of CODES) if (text.includes(c)) return c;
+  if (/not (?:been )?initiali[sz]ed|no project found|run `?stripe projects init/i.test(text)) return 'NOT_INITIALIZED';
+  if (/log ?in|sign ?in|authenticat/i.test(text) && /browser/i.test(text)) return 'BROWSER_AUTH_REQUIRED';
+  if (/terms of service|accept.*tos|--accept-tos/i.test(text)) return 'TOS_NOT_ACCEPTED';
+  if (/paid|payment method/i.test(text) && /confirm|required/i.test(text)) return 'PAID_SERVICE_CONFIRMATION_REQUIRED';
+  return r?.code === 0 ? null : 'UNKNOWN_ERROR';
+}
+
+const versionAtLeast = (v, min) => {
+  const a = String(v).split('.').map(Number); const b = min.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) { if ((a[i] || 0) > b[i]) return true; if ((a[i] || 0) < b[i]) return false; }
+  return true;
+};
+
+/** .gitignore holds every line in IGNORED (appended, with a comment, when one is missing). */
+function ensureIgnored(root, { dryRun }) {
+  const file = join(root, '.gitignore');
+  const now = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const have = new Set(now.split(/\r?\n/).map((l) => l.trim()));
+  const missing = IGNORED.filter((l) => !have.has(l) && !have.has(`/${l}`));
+  if (missing.length && !dryRun) appendFileSync(file, `${now && !now.endsWith('\n') ? '\n' : ''}# Stripe Projects: credentials stay on this computer (its vault and the .env it syncs), never in git.\n${missing.join('\n')}\n`);
+  return missing;
+}
+
+/**
+ * The prototype's whole run. `exec(cmd, args, { cwd, env })` and `wrangler(args)` are replaceable (tests use
+ * stand-ins that answer like the real CLIs' --json); `stripe` names the Stripe CLI.
+ */
+export async function setupViaProjects(root, {
+  withElevenlabs = false, acceptTos = false, dryRun = false, log = () => {},
+  exec = defaultExec, stripe = process.env.HOMIE_STRIPE_CLI || 'stripe', wrangler = null,
+} = {}) {
+  const steps = [];
+  const step = (id, state, words) => { steps.push({ id, state, words }); log(`${state === 'ok' || state === 'done' ? '✓' : state === 'needs' ? '→' : '·'} ${words}`); };
+  const stop = (id, needs, why, extra = {}) => ({ ok: false, command: 'setup', via: 'stripe-projects', dryRun, steps, needs: { id, ...needs }, why, ...extra });
+  const run = (args) => exec(stripe, args, { cwd: root });
+
+  // 1. The Stripe CLI and the Projects plugin.
+  const v = run(['--version']);
+  const version = /(\d+\.\d+\.\d+)/.exec(`${v.stdout} ${v.stderr}`)?.[1] ?? null;
+  if (v.code === 127 || !version) {
+    return stop('stripe-cli', { who: 'ai', run: 'npm install -g @stripe/cli@latest', say: 'Stripe\'s own CLI (or on a Mac: brew install stripe/stripe-cli/stripe); the person approves the install.' }, 'the Stripe CLI is not on this computer');
+  }
+  if (!versionAtLeast(version, MIN_STRIPE_CLI)) {
+    return stop('stripe-cli', { who: 'ai', run: 'npm install -g @stripe/cli@latest', say: `Stripe Projects needs the Stripe CLI ${MIN_STRIPE_CLI} or later (this one is ${version}); on a Mac with Homebrew: brew upgrade stripe/stripe-cli/stripe.` }, `the Stripe CLI is ${version}; Projects needs ${MIN_STRIPE_CLI} or later`);
+  }
+  step('stripe-cli', 'ok', `the Stripe CLI ${version}`);
+  const plugin = run(['projects', '--version']);
+  if (plugin.code !== 0) return stop('projects-plugin', { who: 'ai', run: 'stripe plugin install projects', say: 'Stripe\'s Projects plugin for the CLI (no sign-in yet).' }, 'the Stripe Projects plugin is not installed');
+  step('projects-plugin', 'ok', 'the Stripe Projects plugin');
+
+  // 2. A project here, signed in to the person's own Stripe.
+  const status = run(['projects', 'status', '--json']);
+  const statusCode = codeOf(status);
+  if (status.code !== 0 || (statusCode && statusCode !== 'UNKNOWN_ERROR')) {
+    if (['NOT_INITIALIZED', 'PROJECT_NOT_FOUND', 'BROWSER_AUTH_REQUIRED', 'UNKNOWN_ERROR'].includes(statusCode ?? 'UNKNOWN_ERROR')) {
+      return stop('projects-init', {
+        who: 'ai', run: 'stripe projects init --yes',
+        say: 'Stripe opens its sign-in in the browser: the person signs in to THEIR OWN Stripe account (a new free one is fine; never a work or client account that happens to be signed in here). Wait until they say it is done, then run this again.',
+      }, statusCode === 'BROWSER_AUTH_REQUIRED' ? 'Stripe needs the person to sign in first' : 'this studio folder is not a Stripe project yet');
+    }
+  }
+  const have = servicesIn(jsonOf(status.stdout));
+  step('project', 'ok', 'this folder is a Stripe project');
+
+  // 3. The catalog: Cloudflare's Workers service (and ElevenLabs').
+  const find = (provider, prefer) => {
+    const r = run(['projects', 'search', provider, '--json']);
+    const j = jsonOf(r.stdout);
+    if (r.code !== 0 || !j) return { slug: null, why: `stripe projects search ${provider} did not answer (${codeOf(r) ?? 'no JSON'})` };
+    if (Number(j.result_count) === 0) return { slug: null, why: `${provider} is not in the Stripe Projects catalog` };
+    const all = servicesIn(j).filter((s) => s.startsWith(`${provider}/`));
+    const slug = prefer.map((p) => all.find((s) => p.test(s))).find(Boolean) ?? null;
+    return slug ? { slug, all } : { slug: null, why: `the catalog has no ${provider} service this kit knows (${all.join(', ') || 'none listed'})` };
+  };
+  const wants = [['cloudflare', [/^cloudflare\/workers$/, /^cloudflare\/worker$/, /^cloudflare\/workers?[:/]/]]];
+  if (withElevenlabs) wants.push(['elevenlabs', [/^elevenlabs\/(?:tts|api|key|audio|music)$/, /^elevenlabs\//]]);
+  const slugs = {};
+  for (const [provider, prefer] of wants) {
+    const f = find(provider, prefer);
+    if (!f.slug) return stop('not-in-catalog', { who: 'person', say: `Use Homie's usual way for ${provider === 'cloudflare' ? 'Cloudflare (npx wrangler login)' : 'ElevenLabs (elevenlabs auth login)'} instead.` }, f.why);
+    slugs[provider] = f.slug;
+    step(`catalog-${provider}`, 'ok', `${f.slug} is in the Stripe Projects catalog`);
+  }
+
+  // 4. The services, on their free plans, after the person said yes to the providers' terms.
+  const missing = Object.entries(slugs).filter(([, slug]) => !have.includes(slug));
+  if (missing.length && !acceptTos && !dryRun) {
+    const names = missing.map(([p]) => (p === 'cloudflare' ? 'Cloudflare' : 'ElevenLabs'));
+    return stop('accept-terms', {
+      who: 'person',
+      say: `Stripe Projects will make (or link) ${names.join(' and ')} for this studio on the free plan${names.length > 1 ? 's' : ''}, with no payment method. The person accepts ${missing.map(([p]) => `${p === 'cloudflare' ? 'Cloudflare' : 'ElevenLabs'}'s terms (${TERMS[p]})`).join(' and ')}. When they say yes, run this again with --accept-tos.${missing.some(([p]) => p === 'elevenlabs') ? ' ElevenLabs\' free plan has no commercial licence: songs made on it cannot be sold or monetised.' : ''}`,
+    }, `the person has not accepted ${names.join(' and ')}'s terms yet`, { plan: missing.map(([, slug]) => `stripe projects add ${slug} --json --no-interactive --accept-tos`) });
+  }
+  for (const [provider, slug] of missing) {
+    if (dryRun) { step(`add-${provider}`, 'skipped', `would run: stripe projects add ${slug} --json --no-interactive --accept-tos`); continue; }
+    const add = run(['projects', 'add', slug, '--json', '--no-interactive', '--accept-tos']);
+    const code = codeOf(add);
+    if (code === 'PROVIDER_NOT_LINKED') {
+      return stop(`link-${provider}`, {
+        who: 'ai', run: `stripe projects link ${provider}`,
+        say: provider === 'cloudflare'
+          ? 'If the person\'s Stripe email already has a Cloudflare account, Cloudflare\'s own approval page opens: they approve once. If not, Cloudflare makes a free account for them. Then run this again.'
+          : 'ElevenLabs\' own approval page may open: the person approves once. Then run this again.',
+      }, `${provider} is not linked to this Stripe account yet`);
+    }
+    if (code === 'BROWSER_AUTH_REQUIRED') return stop('projects-init', { who: 'ai', run: 'stripe projects init --yes', say: 'Stripe needs the person to sign in again in the browser. Then run this again.' }, 'Stripe asked for a sign-in');
+    if (code === 'PAID_SERVICE_CONFIRMATION_REQUIRED' || code === 'PAYMENT_METHOD_REQUIRED') {
+      return stop('paid', { who: 'person', say: `Stripe says ${slug} would cost money here. This kit adds only free plans: nothing was added. Use Homie's usual way (npx wrangler login) instead, or decide about a paid plan yourself in Stripe Projects.` }, `${slug} is not free here`);
+    }
+    if (add.code !== 0) return stop('projects-error', { who: 'ai', run: `stripe projects add ${slug} --json --no-interactive --accept-tos --debug`, say: 'Show the person Stripe\'s error as it is (names of variables only, never values).' }, `stripe projects add ${slug} failed (${code ?? 'no code'})`);
+    if (paidIn(jsonOf(add.stdout))) {
+      return stop('paid', { who: 'person', say: `Stripe reported a price for ${slug}. Check it with stripe projects status, and downgrade it to the free plan (stripe projects downgrade ${slug}) or remove it, before anything else.` }, `Stripe reported a paid plan for ${slug}`);
+    }
+    step(`add-${provider}`, 'done', `${slug} added on its free plan`);
+  }
+  for (const [provider, slug] of Object.entries(slugs)) if (have.includes(slug)) step(`add-${provider}`, 'ok', `${slug} was already in this project`);
+
+  // 5. The credentials: names from Projects, values only from its output file, only into Wrangler's environment.
+  const envList = run(['projects', 'env', '--json']);
+  const names = envNamesIn(jsonOf(envList.stdout));
+  const shown = run(['projects', 'env', 'show', '--json']);
+  const outName = (() => {
+    const j = jsonOf(shown.stdout);
+    const pick = (o) => (o && typeof o === 'object' ? (o.output ?? o.output_file ?? o.outputFile ?? o.environment?.output ?? null) : null);
+    const o = pick(j) ?? (Array.isArray(j) ? j.map(pick).find(Boolean) : null);
+    return typeof o === 'string' && o ? o : '.env';
+  })();
+  const outFile = envFileOf(root, outName);
+  if (!outFile) return stop('env-file', { who: 'ai', say: 'Set the Projects environment\'s output file inside the studio (stripe projects env update --output .env).' }, `the Projects output file (${outName}) is outside the studio`);
+  const missingIgnores = ensureIgnored(root, { dryRun });
+  if (missingIgnores.length) step('gitignore', dryRun ? 'skipped' : 'done', `${dryRun ? 'would add' : 'added'} ${missingIgnores.join(', ')} to .gitignore`);
+  else step('gitignore', 'ok', '.gitignore keeps the credentials out of git');
+  if (dryRun) {
+    return { ok: true, command: 'setup', via: 'stripe-projects', dryRun: true, steps, services: slugs, envNames: names, envFile: outName, next: ['Run it without --dry-run (after the person accepted the terms: --accept-tos).'] };
+  }
+  if (!names.includes('CLOUDFLARE_API_TOKEN') || !names.includes('CLOUDFLARE_ACCOUNT_ID')) {
+    const pull = run(['projects', 'env', '--pull']);
+    if (pull.code !== 0) return stop('credentials', { who: 'ai', run: 'stripe projects env --pull', say: 'Projects did not sync the credentials; show its error (names only).' }, 'Stripe Projects listed no CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID');
+  }
+  const vars = readDotenv(outFile);
+  if (!vars.CLOUDFLARE_API_TOKEN || !vars.CLOUDFLARE_ACCOUNT_ID) {
+    return stop('credentials', { who: 'ai', run: 'stripe projects env --pull', say: `Projects has not written CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to ${outName} yet: pull them, then run this again.` }, `no Cloudflare credentials in ${outName}`);
+  }
+  if (!/^[a-f0-9]{32}$/i.test(vars.CLOUDFLARE_ACCOUNT_ID)) return stop('credentials', { who: 'ai', say: 'The account id Projects wrote does not look like a Cloudflare account id; check stripe projects status.' }, 'CLOUDFLARE_ACCOUNT_ID is not a Cloudflare account id');
+  const studio = readStudio(root);
+  const before = studio.cloudflare?.accountId;
+  if (before && before !== vars.CLOUDFLARE_ACCOUNT_ID && (studio.cloudflare?.created ?? []).length) {
+    return stop('other-account', { who: 'person', say: 'This studio already lives on another Cloudflare account. Keep that one (npx wrangler login), or move the studio deliberately; nothing was changed.' }, 'studio.json names another Cloudflare account that this studio already deployed to');
+  }
+  const eleven = withElevenlabs ? names.find((n) => /ELEVEN/.test(n) && /KEY/.test(n)) ?? (Object.keys(vars).find((n) => /ELEVEN/.test(n) && /KEY/.test(n)) ?? null) : null;
+  writeStudio(root, {
+    ...studio,
+    cloudflare: { ...studio.cloudflare, accountId: vars.CLOUDFLARE_ACCOUNT_ID, auth: 'stripe-projects', envFile: outName },
+    ...(withElevenlabs && eleven ? { providers: { ...(studio.providers ?? {}), elevenlabs: { via: 'stripe-projects', envKey: eleven, envFile: outName } } } : {}),
+  });
+  step('studio.json', 'done', `studio.json: the Cloudflare account Projects gave (its id, not a secret), and "auth": "stripe-projects" (the token stays in ${outName} and Projects' vault)${eleven ? `; ElevenLabs' key is ${eleven} there` : ''}`);
+
+  // 6. What the token can do, read-only.
+  const w = wrangler ?? ((args) => runner(root, {})(args));
+  const checks = {};
+  try {
+    const who = w(['whoami', '--json']);
+    let signed = false;
+    try { signed = Boolean(jsonOf(who.stdout ?? who.out)?.loggedIn); } catch { signed = false; }
+    checks.signedIn = who.code === 0 && signed;
+    checks.d1 = w(['d1', 'list', '--json']).code === 0;
+    checks.workersAi = w(['ai', 'models', '--json']).code === 0;
+    checks.r2 = w(['r2', 'bucket', 'list']).code === 0;
+  } catch (error) {
+    checks.error = String(error?.message ?? error).slice(0, 200);
+  }
+  const short = [checks.signedIn === false ? 'Wrangler does not accept the token' : null, checks.d1 === false ? 'D1 (the studio\'s database)' : null].filter(Boolean);
+  step('checks', checks.error ? 'skipped' : short.length ? 'needs' : 'ok', checks.error ? `not checked (${checks.error})` : `Wrangler with the Projects token: signed in ${checks.signedIn ? 'yes' : 'no'}, D1 ${checks.d1 ? 'yes' : 'no'}, Workers AI ${checks.workersAi ? 'yes' : 'no'}, R2 ${checks.r2 ? 'yes' : 'no (optional: storage asks Cloudflare for a payment method)'}`);
+  if (short.length) {
+    return stop('token-scope', { who: 'ai', run: 'stripe projects search cloudflare --json', say: `The token Projects gave cannot do: ${short.join(', ')}. Add the missing Cloudflare service through Projects (search the catalog: stripe projects search cloudflare --json), or use npx wrangler login instead.` }, `the Cloudflare token cannot do: ${short.join(', ')}`, { checks });
+  }
+  return {
+    ok: true, command: 'setup', via: 'stripe-projects', steps, services: slugs, checks, envFile: outName,
+    wrote: ['studio.json', ...(missingIgnores.length ? ['.gitignore'] : [])],
+    ...(eleven ? { elevenlabs: { envKey: eleven, note: 'ElevenLabs\' free plan has no commercial licence: the music skill says the plan before every render.' } } : {}),
+    next: ['Commit studio.json and .gitignore (never .env or .projects/vault/).', 'npm run deploy   (Wrangler deploys with the Projects token; no wrangler login needed)'],
+  };
+}
+
+export function projectsLines(r) {
+  const lines = [];
+  for (const s of r.steps ?? []) lines.push(`  ${s.state === 'ok' || s.state === 'done' ? '✓' : s.state === 'needs' ? '→' : '·'} ${s.words}`);
+  if (r.ok === false && r.needs) lines.push(`Next (${r.needs.who === 'person' ? 'the person' : 'your AI'}): ${r.needs.run ? `${r.needs.run}  ` : ''}${r.needs.say}`);
+  for (const n of r.next ?? []) lines.push(n);
+  return lines;
+}

package/lib/scaffold.mjs

@@ -364,9 +364,16 @@ studio's pinned copy, never a registry lookup of the bare name.
   \`shop.entitlements()\`, \`shop.on('change', …)\`, \`shop.open(item)\` from a button the player pressed (never the
   play button, never on a timer), \`shop.used(key)\` when it is equipped. A supporter's badge rides on their seat
   (\`peer.badge\`, set by the Worker, never by a hello). The guide is \`node_modules/@homie-rocks/studio/shop/SHOP.md\`.
+- **Stripe's own tools** (set up when the studio starts selling): \`npm install -g @stripe/cli@latest && stripe agent
+  setup\` installs Stripe's agent plugin (its MCP server and skills); the owner signs in once on Stripe's page and
+  gives access to a sandbox first. With it you make the catalog (\`npx --no-install homie-studio shop catalog\` says
+  the read, then the exact \`stripe_api_write\` calls), check tax settings, and answer "how are sales?" read-only.
+  Never make a webhook or an API key through the MCP (a secret would land in the chat), and never retry a write
+  Stripe sent to the owner for confirmation until they approved it.
 - **The key** goes in only from a page on the owner's own computer: \`npx --no-install homie-studio shop connect\`
-  prints a 127.0.0.1 link; the owner pastes a restricted key and the webhook secret there, and they go straight to
-  the Worker secrets. Test keys only unless \`--live\`. Never ask for a key in the chat; never write one anywhere.
+  prints a 127.0.0.1 link; the owner pastes one restricted key there, the page makes the webhook with it, and the
+  key and the webhook's secret go straight to the Worker secrets. Test keys only unless \`--live\`. Never ask for a
+  key in the chat; never write one anywhere.
 - **Refunds:** the owner's one tap in the office (\`/_studio/office/shop\`). You may only ASK:
   \`homie-studio shop refund <order>\` gives the owner a one-tap link. A card dispute never touches the player's
   account. \`shop\` says what is missing; \`shop orders\` lists orders (never a card or an email).
@@ -522,6 +529,10 @@ 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.
+.env.*
+.projects/vault/
+.projects/cache/
 *.log
 # Port checks: receipts and screenshots of each run (games/<id>/.port/check-*/).
 games/*/.port/

package/lib/shop-catalog.mjs

@@ -0,0 +1,163 @@
+/**
+ * `homie-studio shop catalog` (@homie-rocks/studio 0.24.3): the shop's items as Products, each with its Price, in the
+ * studio's OWN Stripe, made by the owner's AI through Stripe's own MCP server (`stripe_api_read`, `stripe_api_write`)
+ * after the owner connected it with Stripe's sign-in page. No key on this computer makes them.
+ *
+ *   homie-studio shop catalog                 what the catalog should hold, and the one read to make first
+ *   homie-studio shop catalog --have <file>   Stripe's answer to that read (a file, or - for standard input): the
+ *                                             exact writes still needed, or "in sync" (then shop.json `catalog`
+ *                                             records the mode, test or live, so the Worker's checkouts name them)
+ *
+ * Each item is one Product with an id of our choosing, the same in a sandbox and in live mode:
+ * `homie_<studio slug>_<item id>` (worker/stripe.mjs productIdOf), its name, blurb, a tax code (video games,
+ * downloaded: what Managed Payments needs, and what Stripe Tax should know), metadata naming the studio and the item,
+ * and a default Price of exactly shop.json's amount (a tip has no fixed price: its Product only). A changed price is a
+ * new Price made the default; an item gone from shop.json is archived (`active: false`), never deleted. Products this
+ * studio did not make are never named.
+ *
+ * shop.json stays the truth for money: the Worker charges shop.json's checked price and names the Product only so that
+ * Stripe's Dashboard, its reports and its MCP see sales by product.
+ */
+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';
+
+const MARK = 'shop-v1';
+
+/** The Products the catalog should hold, from the checked shop.json. */
+export function wantedProducts(shop, slug) {
+  return (shop?.items ?? []).map((it) => {
+    const id = productIdOf(slug, it.id);
+    return {
+      id, item: it.id, name: it.name, description: it.blurb ?? null, tax_code: defaultTaxCode(it),
+      metadata: { homie: MARK, homie_studio: String(slug), homie_item: it.id },
+      price: it.kind === 'tip' ? null : { currency: shop.currency, unit_amount: it.price, tax_behavior: 'exclusive' },
+      shown: it.kind === 'tip' ? `pay what you want, ${money(it.min, shop.currency)} to ${money(it.max, shop.currency)}` : money(it.price, shop.currency),
+    };
+  });
+}
+
+/**
+ * Every Product in whatever Stripe answered: a list object ({ object: 'list', data }), an array, an MCP result
+ * ({ content: [{ type: 'text', text }] }), or several of these. Anything else is ignored.
+ */
+export function productsIn(value, out = [], depth = 0) {
+  if (depth > 8 || value === null || value === undefined) return out;
+  if (typeof value === 'string') {
+    const t = value.trim();
+    if (t.startsWith('{') || t.startsWith('[')) { try { productsIn(JSON.parse(t), out, depth + 1); } catch { /* not JSON */ } }
+    return out;
+  }
+  if (Array.isArray(value)) { for (const v of value) productsIn(v, out, depth + 1); return out; }
+  if (typeof value !== 'object') return out;
+  if (value.object === 'product' && typeof value.id === 'string') { out.push(value); return out; }
+  for (const k of ['data', 'content', 'text', 'result', 'results', 'structuredContent']) if (k in value) productsIn(value[k], out, depth + 1);
+  return out;
+}
+
+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. */
+export function catalogPlan(root, { have = null, mode = null, record = true } = {}) {
+  const r = readShop(root);
+  if (r.absent) return { ok: false, command: 'shop catalog', why: 'no shop.json: homie-studio shop init writes one first' };
+  if (!r.ok) return { ok: false, command: 'shop catalog', why: `shop.json breaks the rules (homie-studio shop check): ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
+  const studio = readStudio(root);
+  const slug = studio.slug;
+  if (!slug) return { ok: false, command: 'shop catalog', why: 'studio.json has no slug: the catalog\'s Product ids are made from it' };
+  const wanted = wantedProducts(r.shop, slug);
+  const read = {
+    tool: 'stripe_api_read', method: 'GET', path: '/v1/products', params: { limit: 100, expand: ['data.default_price'] },
+    then: 'Save exactly what it answers (every page, while has_more) to a file in the scratch folder, then run: npx --no-install homie-studio shop catalog --have <that file>',
+  };
+  const summary = wanted.map((w) => ({ id: w.id, item: w.item, name: w.name, price: w.shown, tax_code: w.tax_code }));
+  if (have === null || have === undefined) {
+    return {
+      ok: true, command: 'shop catalog', step: 'read', products: summary, read,
+      next: [
+        'With Stripe\'s MCP connected to the studio\'s SANDBOX (never live until the owner says so), make the read above with stripe_api_read.',
+        'Then: npx --no-install homie-studio shop catalog --have <the saved answer>: it says exactly which writes are still needed.',
+      ],
+    };
+  }
+  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')))];
+  if (modes.length > 1) return { ok: false, command: 'shop catalog', why: 'that answer mixes test and live Products: read one environment at a time' };
+  const where = mode ?? modes[0] ?? (products[0] ? (products[0].livemode ? 'live' : 'test') : null);
+  const writes = [];
+  let unknownPrices = 0;
+  for (const w of wanted) {
+    const p = products.find((x) => x.id === w.id);
+    const meta = Object.fromEntries(Object.entries(w.metadata));
+    if (!p) {
+      writes.push({
+        tool: 'stripe_api_write', method: 'POST', path: '/v1/products', why: `make ${w.name} (${w.shown})`,
+        params: { id: w.id, name: w.name, ...(w.description ? { description: w.description } : {}), tax_code: w.tax_code, metadata: meta, ...(w.price ? { default_price_data: w.price } : {}) },
+      });
+      continue;
+    }
+    const change = {};
+    if (p.name !== w.name) change.name = w.name;
+    if ((p.description ?? null) !== (w.description ?? null) && w.description) change.description = w.description;
+    if (taxCodeOf(p) !== w.tax_code) change.tax_code = w.tax_code;
+    if (p.active === false) change.active = true;
+    if (Object.entries(meta).some(([k, v]) => p.metadata?.[k] !== v)) change.metadata = meta;
+    if (Object.keys(change).length) writes.push({ tool: 'stripe_api_write', method: 'POST', path: `/v1/products/${w.id}`, why: `bring ${w.name} back in line with shop.json (${Object.keys(change).join(', ')})`, params: change });
+    if (!w.price) continue;
+    const dp = p.default_price;
+    if (typeof dp === 'string') { unknownPrices += 1; continue; }
+    const same = dp && dp.unit_amount === w.price.unit_amount && dp.currency === w.price.currency && dp.active !== false && (!dp.tax_behavior || dp.tax_behavior === 'exclusive' || dp.tax_behavior === 'unspecified');
+    if (!same) {
+      writes.push({
+        tool: 'stripe_api_write', method: 'POST', path: '/v1/prices', why: `${w.name}'s price as shop.json says: ${w.shown}`,
+        params: { product: w.id, ...w.price, lookup_key: `${w.id}_${w.price.currency}`, transfer_lookup_key: true, metadata: meta },
+      });
+      writes.push({
+        tool: 'stripe_api_write', method: 'POST', path: `/v1/products/${w.id}`, why: `make that price ${w.name}'s default`,
+        params: { default_price: '<the id (price_…) of the Price the call before made>' },
+      });
+    }
+  }
+  for (const p of ours) {
+    if (wanted.some((w) => w.id === p.id) || p.active === false) continue;
+    writes.push({ tool: 'stripe_api_write', method: 'POST', path: `/v1/products/${p.id}`, why: `${p.name ?? p.id} is no longer in shop.json: archive it (never delete; past sales keep their product)`, params: { active: false } });
+  }
+  const inSync = writes.length === 0 && unknownPrices === 0;
+  let recorded = false;
+  if (inSync && where && record && wanted.length) {
+    const raw = JSON.parse(readFileSync(r.file, 'utf8'));
+    const now = Array.isArray(raw.catalog) ? raw.catalog : [];
+    if (!now.includes(where)) {
+      raw.catalog = [...new Set([...now, where])].sort();
+      writeFileSync(r.file, `${JSON.stringify(raw, null, 2)}\n`);
+      recorded = true;
+    }
+  }
+  return {
+    ok: true, command: 'shop catalog', step: inSync ? 'done' : 'write', mode: where, inSync, products: summary, writes,
+    ...(unknownPrices ? { read: { ...read, why: `${unknownPrices} Product(s) came back without their default price expanded: read again with expand data.default_price` } } : {}),
+    ...(recorded ? { recorded: `shop.json "catalog" now includes "${where}": commit it, deploy, and the checkouts name these Products` } : {}),
+    next: inSync
+      ? [where === 'live' ? 'The live catalog matches shop.json.' : 'The sandbox catalog matches shop.json.', ...(recorded ? ['Commit shop.json and deploy (npm run deploy).'] : [])]
+      : ['Make each write in order with stripe_api_write (the human-confirmation link Stripe may give is the owner\'s to open).', 'Then read again and run --have again: it says "in sync" when nothing is left.'],
+  };
+}
+
+export function catalogLines(r) {
+  const lines = [];
+  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})`);
+    lines.push(`First read what Stripe holds: ${r.read.tool} ${r.read.method} ${r.read.path} ${JSON.stringify(r.read.params)}`, ...r.next.map((n) => `  ${n}`));
+    return lines;
+  }
+  lines.push(r.inSync ? `In sync: the ${r.mode ?? ''} catalog in Stripe matches shop.json.`.replace('  ', ' ') : `${r.writes.length} write(s) still needed${r.mode ? ` (${r.mode})` : ''}:`);
+  for (const w of r.writes) lines.push(`  ${w.tool} ${w.method} ${w.path} ${JSON.stringify(w.params)}  # ${w.why}`);
+  if (r.read) lines.push(`  ${r.read.why}`);
+  if (r.recorded) lines.push(r.recorded);
+  lines.push(...r.next);
+  return lines;
+}