@homie-rocks/studio 0.37.0 → 0.37.2

package/lib/mcp.mjs

@@ -33,22 +33,17 @@ export const MCP_APP_MIME = 'text/html;profile=mcp-app';
 
 export const INSTRUCTIONS = `Homie Studio, on this computer: make game studios and their multiplayer web games, music and videos, run them here, and put them online on the studio's own Cloudflare. (It is not the Homie house app: that app's own server, with its room and TV tools, is a different one.) These tools do the work in this chat; the person never types a command and never needs a terminal. A studio is a folder in the studios folder; the file tools (file_list, file_read, file_edit, file_write, file_search) work inside it.
 
-A new studio follows one checklist, in order and never ahead. Show it in your first reply and again, ticked, as each step ends:
-0. Setup status (setup_status; for a studio that is not made yet, pass its name as studio, so the checklist is the new studio's and never another's): what this computer and their accounts have; optional rows never block.
-1. The studio (studio_scaffold): it has NO game; its home page says "First game coming soon".
-2. See a working game (game_demo): a live game on Homie Arcade with its Play link, nothing copied in. Copy a starter in (game_make) only if they ask.
-3. One small change from one sentence of theirs: to the copied game, or to the studio's home (site/theme.json colours, a tagline in studio.json, a first post in posts/). Then build and preview_run, and they reload.
-4. Plan their game (game_plan): a short interview, two or three questions a message with options and your pick; then fill games/<id>/CODEX.md and show it (game_codex). Look for pieces first: the @homie-rocks/* packages for general mechanisms, and parts_find for pieces other studios shared (part_add brings one in).
-5. Build it: build_open, then game_make under the planned id (the codex stays), file edits (few and large: one file_edit carries every change to a file in its edits list, never a call per change), build, preview_run, check. The card follows every build.
-For a shop: stripe_login (shop connect) syncs Products, Prices, Payment Links and the webhook through Stripe CLI browser approval. Follow studio_job. Default is keyless: no API key in the Worker, no human-handled key. Rerun after shop.json changes. Never expose CLI credentials or webhook secrets. Follow the single next step, verify purchase/webhook/grant and a refund in Stripe or through the connected AI. An existing Worker key selects fuller carts, caps, expiry, automatic recovery and office refunds; explain that only when requested. Never choose manual automatically. Lost webhook: resend from Stripe, never grant from the return URL. Live only when requested.
-6. Playtest it (playtest), then put it online: studio_deploy with plan: true first (say what it creates and costs, free), cloudflare_login when not signed in (they approve once in their browser), studio_deploy, then studio_publish.
-If they ask for everything at once, show the list, make your own choices for steps 2 to 4 in one line each, and go on.
+Carry the person's request through to a working result without a lesson or an interview. Use their name or business name, otherwise "My Studio". Setup, dependencies, a plan, building and checking are AI work, not approval gates. Choose engineering and design defaults from the request; record them in CODEX.md so the person can change them later by asking. Phone and computer controls, a small first version, local sound and CC0 art are the defaults. No paid media unless requested with a budget. A business or charity may need an app or a site, not a game: do not make them play a demo or choose a genre.
+Run setup_status (for a studio that is not made yet, pass its name as studio), studio_scaffold (NO game until one is requested), then build the requested thing and check it. A demo and a small-change lesson are optional only when requested. Look for existing engine mechanisms and parts_find before building systems. Use few, large edits: one file_edit carries every change to a file in its edits list. game_plan records your decisions; it does not require an interview. Install missing prerequisites yourself with setup_prepare; follow studio_job without asking the person to retry. Optional providers never block.
+Show progress briefly and give the preview link as soon as it works. For going live, studio_deploy with plan: true says what it creates and costs; cloudflare_login asks for browser approval once; then studio_deploy. Publish to the directory only when requested (offer once after going live). Honour an existing request to deploy or list; do not ask again except for a host's mandatory approval.
+For a shop, stripe_login (shop connect) syncs Products, Prices, Payment Links and the webhook through one Stripe browser approval. No human-handled key. Follow studio_job and the result's single next step; rerun after shop.json changes. Test purchase, webhook, grant and refund with stand-ins before going live. Live payments only when requested.
+For a custom domain already on Cloudflare, studio_domain prepares the exact hostname route using the existing sign-in; studio_deploy applies it and Cloudflare creates DNS and TLS. Never ask for zone or account ids. Keep workers.dev until a domain is requested.
 
 If studio_scaffold finds an earlier folder of the studio's name that is not a studio, ask the person whether to fold its premise in (studio_fold), and remove it only with a second yes.
 
 A studio made elsewhere (on a phone, with Deploy to Cloudflare, so it lives on GitHub): studio_open with its repo clones it into the studios folder with this computer's own GitHub sign-in; github_login signs the computer in with GitHub's one-time code. Never ask for a token.
 
-Links are the person's to open: give them in your reply (the cards have their own buttons). Never open a browser or run a command such as open to open one yourself.
+Give preview and finished-site links in your reply (the cards have their own buttons). Open provider authorization flows when needed; the person signs in and approves, while you handle configuration.
 
 To make one mechanic of a game feel better (a jump, a hit, a dash), game_lab opens the Game Lab: New beside Today, one take, its phases and sliders (studio_guide { "topic": "lab" }).
 

package/lib/parts-build.mjs

@@ -1,4 +1,7 @@
 import { experienceDir, experienceFile } from './studio.mjs';
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../worker/referrals.mjs';
+import { publicFiles, saleProblems } from "../worker/parts-sale.mjs";
 /**
  * GAME PARTS IN THE BUILD (parts/PARTS.md). Three small things lib/build.mjs and the deploy plan call, so the build
  * itself stays one line longer in each place:
@@ -14,7 +17,7 @@ import { experienceDir, experienceFile } from './studio.mjs';
  *   partsPublishReport(root)    before a game that uses parts goes online: each part's licence and attribution, and
  *                               plainly where licences cannot be combined.
  */
-import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, readFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import {
   assetRecords, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir, packedVersions, publicPart, readOrigins, readPart, safePath, shareProblems,
@@ -33,6 +36,7 @@ export function resolvePartImport(root, spec, lock = readOrigins(root)) {
   let dir = null; let rest = []; let ref = null; let vendored = false;
   if (segs.length >= 2 && lock.parts[`${segs[0]}/${segs[1]}`]) { ref = `${segs[0]}/${segs[1]}`; dir = vendorDir(root, ref); rest = segs.slice(2); vendored = true; }
   else if (segs.length >= 1 && existsSync(join(root, 'parts', segs[0], 'part.json'))) { ref = segs[0]; dir = join(root, 'parts', segs[0]); rest = segs.slice(1); }
+  if (vendored && lock.parts[ref]?.purchase?.scope === 'game' && lock.parts[ref].purchase.game == null) return { error: 'The paid part needs a named game licence' };
   if (!dir) return { error: `'${spec}' names a part this studio does not have. Parts here: ${[...Object.keys(lock.parts), ...listOwnParts(root).map((o) => o.id)].join(', ') || 'none'}. Bring one in with part_add ("<studio site>/<part id>").` };
   if (!existsSync(dir)) return { error: `'${spec}': parts/origins.json names ${ref} but its files are gone. Add it again (${ref}@${lock.parts[ref].version}).` };
   if (rest.length) {
@@ -50,7 +54,7 @@ export function resolvePartImport(root, spec, lock = readOrigins(root)) {
 /** The esbuild plugin (lib/build.mjs passes it to every game's bundle). `game`: the game being bundled, to credit. */
 export function partsPlugin(root, game = null) {
   return {
-    name: 'homie-parts',
+    name: 'homie-purchases',
     setup(build) {
       const used = new Set();
       let lock = null;
@@ -58,6 +62,8 @@ export function partsPlugin(root, game = null) {
       build.onResolve({ filter: /^@parts\// }, (args) => {
         try { lock ??= readOrigins(root); } catch (error) { return { errors: [{ text: error.message }] }; }
         const r = resolvePartImport(root, args.path, lock);
+        const purchase = lock.parts[r.ref]?.purchases?.[game] ?? lock.parts[r.ref]?.purchase;
+        if (r.vendored && purchase?.scope === 'game' && game !== purchase.game) return { errors: [{ text: `The paid part ${r.ref} is licensed for ${purchase.game}, not ${game}. Use part_add to obtain this game's licence.` }] };
         if (r.error) return { errors: [{ text: r.error }] };
         if (r.vendored) used.add(r.ref);
         return { path: r.path };
@@ -103,19 +109,32 @@ export function buildParts(root, dist, { studio = {}, log = () => {} } = {}) {
   const sharing = sharedPartsOf(root);
   const names = new Map();
   const index = [];
+  const offerFile = join(root, 'parts', 'offers.json');
+  const offers = existsSync(offerFile) ? JSON.parse(readFileSync(offerFile, 'utf8')) : {};
   for (const { id, versions, part } of sharing) {
+    const releases = [];
     for (const v of versions) {
       const src = packedDir(root, id, v);
       const packed = readPart(src);
+      const config = offers[id];
+      // Release terms are authoritative. The optional price override survives releases.
+      const offer = packed.sale ? { ...packed.sale, ...(config?.price ?? {}) } : null;
+      if (offer && saleProblems({ ...packed, sale: offer }).length) throw new Error(`Invalid offer for ${id}`);
+      const selected = config?.releases?.[v];
+      const onSale = Boolean(offer && config?.active !== false && selected?.active !== false && (v === versions.at(-1) || selected?.keepOnSale === true));
+      if (offer && packed.sale.amount !== offer.amount) log(`warning: ${id} ${v} manifest price is historical; the current offer is ${offer.amount}. Use parts offer to change the selling price.`);
+      if (selected?.upgrade !== undefined && !['included', 'paid'].includes(selected.upgrade)) throw new Error('Release upgrade must be included or paid');
+      releases.push({ onSale, offerVersion: offer ? createHash('sha256').update(canonicalJson({ resource: { kind: 'part', id, release: v, manifest: createHash('sha256').update(canonicalJson(packed)).digest('hex') }, terms: offer })).digest('hex') : null, offer, upgrade: selected?.upgrade ?? 'paid', version: v, license: packed.license, licenseTerms: packed.licenseTerms ?? null, sale: packed.sale ?? null });
       if (!verifyFiles(src, packed).ok) throw new Error(`parts/_packed/${id}/${v} no longer matches its hashes: a shared version never changes. Restore it from git.`);
       const dest = join(out, id, v);
-      for (const f of packed.files) { mkdirSync(dirname(join(dest, f.path)), { recursive: true }); cpSync(join(src, f.path), join(dest, f.path)); }
+      for (const f of packed.files.filter((f) => !packed.sale || publicFiles(packed).has(f.path))) { mkdirSync(dirname(join(dest, f.path)), { recursive: true }); cpSync(join(src, f.path), join(dest, f.path)); }
+      mkdirSync(dest, { recursive: true });
       writeFileSync(join(dest, 'part.json'), `${JSON.stringify(publicPart({ ...packed, share: true }))}\n`);
     }
     // The game it came out of, by the name the studio gives it.
     const g = part.from?.game ?? part.from?.app;
     if (g && !names.has(g)) names.set(g, gameFacts(root, g).name);
-    index.push({ ...part, ...(g ? { from: { ...part.from, name: names.get(g) } } : {}), url: `/parts/${id}/${versions.at(-1)}/`, page: `/parts/${id}/`, versions });
+    index.push({ ...part, ...(part.sale ? { sale: releases.at(-1).offer } : {}), ...(g ? { from: { ...part.from, name: names.get(g) } } : {}), url: `/parts/${id}/${versions.at(-1)}/`, page: `/parts/${id}/`, versions, releases });
     log(`shared part ${id} (${versions.join(', ')})`);
   }
   mkdirSync(out, { recursive: true });

package/lib/parts-cli.mjs

@@ -1,3 +1,8 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPart, partDir } from './parts.mjs';
+import { saleProblems } from "../worker/parts-sale.mjs";
+import { purchasePortal, prepareRecovery } from './parts-purchase.mjs';
 /**
  * `homie-studio parts …`: the plumbing behind the four chat tools (lib/parts-tools.mjs; parts/PARTS.md). A creator
  * works in chat and never types these; an agent with a shell and no MCP connection may.
@@ -14,7 +19,7 @@
 import { newPart } from './parts.mjs';
 import { addPart, checkParts, findParts, sharePart } from './parts-store.mjs';
 
-export const PARTS_VERBS = ['find', 'new', 'add', 'share', 'unshare', 'check'];
+export const PARTS_VERBS = ['find', 'new', 'add', 'share', 'unshare', 'check', 'manage', 'recover', 'reissue', 'keys', 'offer', 'refund', 'retire', 'test-access'];
 
 /**
  * What `parts add` takes, in the words the command prints when it is not given a part. `--no-install` is said as
@@ -32,7 +37,51 @@ export async function partsCommand(root, sub, positional, flags, { log = () => {
     case 'check': return checkParts(root, arg ?? null, { write: true });
     case 'share': return arg ? sharePart(root, arg, true) : { ok: false, command: 'parts share', why: 'name the part to share' };
     case 'unshare': return arg ? sharePart(root, arg, false) : { ok: false, command: 'parts unshare', why: 'name the part to stop sharing' };
-    case 'add': return arg ? addPart(root, arg, { fetch, ...(npm ? { npm } : {}), install: !flags.has('no-install'), say: log, game: str('game'), overwrite: flags.has('overwrite') }) : { ok: false, command: 'parts add', why: `name the part: "<studio site>/<part id>"\n${PARTS_ADD_USAGE}` };
+    case 'offer': {
+      const p = readPart(partDir(root, arg)); const version = str('release');
+      if (str('upgrade') && (!version || !['included', 'paid'].includes(str('upgrade')))) throw new Error('--upgrade included|paid requires --release');
+      if (flags.has('keep-on-sale') && !version) throw new Error('--keep-on-sale requires --release');
+      const file = join(root, 'parts', 'offers.json'); const offers = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+      const old = offers[arg] ?? {};
+      const price = { ...old.price, ...(str('amount') ? { amount: Number(str('amount')) } : {}) };
+      const problems = saleProblems({ ...p, sale: { ...p.sale, ...price } });
+      if (problems.length) throw new Error(problems.join('; '));
+      offers[arg] = { price, active: !version && flags.has('withdraw') ? false : flags.has('on-sale') ? true : old.active !== false, releases: { ...old.releases } };
+      if (version) offers[arg].releases[version] = { ...old.releases?.[version], ...(flags.has('withdraw') ? { active: false } : flags.has('on-sale') ? { active: true } : {}), ...(flags.has('keep-on-sale') ? { keepOnSale: true } : {}), ...(str('upgrade') ? { upgrade: str('upgrade') } : {}) };
+      writeFileSync(file, JSON.stringify(offers, null, 2) + '\n');
+      return { ok: true, command: 'parts offer', message: 'Offer updated. Deploy to publish it. Existing purchase terms stay unchanged.' };
+    }
+    case 'test-access': {
+      const { withKey } = await import('./office.mjs');
+      return withKey(root, null, (call) => call('/_studio/api/shop/test-access', { order: arg }));
+    }
+    case 'recover': return prepareRecovery(root, arg, str('order'), str('game'));
+    case 'reissue': {
+      const { withKey } = await import('./office.mjs');
+      return withKey(root, null, (call) => call('/_studio/api/shop/reissue', { order: arg, claimHash: str('claim-hash'), receiptVerified: flags.has('receipt-verified'), ...(str('buyer') ? { buyer: str('buyer') } : {}) }));
+    }
+    case 'keys': {
+      const { generateKeyPair, exportJWK } = await import('jose');
+      const { runner } = await import('./cloudflare.mjs');
+      const { siteUrl } = await import('./studio.mjs');
+      const url = siteUrl(root);
+      let old = [];
+      try { const r = await (fetch ?? globalThis.fetch)(`${url}/purchases/keys.json`); if (r.ok) old = (await r.json()).keys; else if (r.status !== 404 || !flags.has('initialize')) throw new Error('Cannot read keys; only an explicit --initialize accepts a missing endpoint'); } catch { throw new Error('Cannot read the current public key ring; restore connectivity before rotating'); }
+      if (!Array.isArray(old) || old.length >= 32) throw new Error('Retain the existing ring. Its 32-key protocol limit requires an explicit key retirement before rotating again');
+      const pair = await generateKeyPair('Ed25519', { extractable: true });
+      const ring = [await exportJWK(pair.privateKey), ...old.map(({ kty, crv, x }) => ({ kty, crv, x }))];
+      const r = runner(root)(['secret', 'put', 'PURCHASE_SIGNING_KEYS'], { input: JSON.stringify(ring) + '\n' });
+      return { ok: r.code === 0, command: 'parts keys', message: 'The parts signing key is a Worker secret. Retained public keys verify earlier purchases.' };
+    }
+    case 'refund': return purchasePortal(root, arg, { game: str('game'), fetch, action: 'refund' });
+    case 'retire': {
+      const { withKey } = await import('./office.mjs');
+      const result = await withKey(root, null, (call) => call('/_studio/api/shop/retire', { kind: 'part', resource: arg }));
+      if (result.ok) sharePart(root, arg, false);
+      return { ...result, command: 'parts retire' };
+    }
+    case 'manage': return purchasePortal(root, arg, { game: str('game'), fetch });
+    case 'add': return arg ? addPart(root, arg, { fetch, ...(npm ? { npm } : {}), install: !flags.has('no-install'), approve: str('approve'), wallet: str('wallet'), quantity: str('quantity') ? Number(str('quantity')) : 1, offline: flags.has('offline'), say: log, game: str('game'), overwrite: flags.has('overwrite') }) : { ok: false, command: 'parts add', why: `name the part: "<studio site>/<part id>"\n${PARTS_ADD_USAGE}` };
     default: return { ok: false, command: 'parts', why: `"${sub}" is not a parts command: ${PARTS_VERBS.join(', ')}` };
   }
 }
@@ -46,6 +95,8 @@ const packageLines = (rows) => rows.filter((p) => p.state !== 'ok').map((p) => (
 
 function addLines(r) {
   const L = [];
+  if (r.purchase?.offline) L.push('Restored from the verified private backup. Refund status is only last known; the seller was not contacted.');
+  if (r.purchase?.mode === 'test') L.push('TEST purchase: this is not proof of a live payment.');
   if (r.was && r.same) L.push(`${r.ref} ${r.version} is already here and unchanged.`);
   else if (r.was) L.push(`${r.ref}: ${r.was} → ${r.version}. ${[r.changes.changed.length ? `changed: ${r.changes.changed.join(', ')}` : '', r.changes.added.length ? `new: ${r.changes.added.join(', ')}` : '', r.changes.removed.length ? `gone: ${r.changes.removed.join(', ')}` : ''].filter(Boolean).join('; ') || 'the same files'}. Your tuning.json was kept${r.replaced?.length ? `; REPLACED your edited ${r.replaced.join(', ')} as asked` : ''}.`);
   else L.push(`${r.name} ${r.version} (${r.kind}) from ${r.host} is in ${r.dir}: ${r.files} files, every one checked against its SHA-256. It is this studio's to tune now.`);
@@ -67,7 +118,7 @@ export function partsLines(r) {
       if (!r.hub.ok) L.push(r.hub.why, '');
       if (!r.results.length) L.push(r.hub.ok ? `No shared part matches${r.query ? ` "${r.query}"` : ''} (${r.searched.hub} in the catalogue, ${r.searched.here} in this studio). Write it; if it turns out reusable, it can become a part.` : 'Nothing in this studio matches.');
       for (const p of r.results) {
-        L.push(`${p.name} (${p.kind}) ${p.version ?? ''} · ${p.license ?? 'no licence named'} · ${p.where === 'hub' ? p.ref : p.where === 'here' ? `${p.ref} (already here)` : `${p.id} (this studio's own${p.share ? ', shared' : ', private'})`}`);
+        L.push(`${p.name} (${p.kind}) ${p.version ?? ''} · ${p.license ?? 'no licence named'} · ${p.price ?? 'Free'} · ${p.where === 'hub' ? p.ref : p.where === 'here' ? `${p.ref} (already here)` : `${p.id} (this studio's own${p.share ? ', shared' : ', private'})`}`);
         if (p.summary) L.push(`  ${p.summary}`);
         if (p.from?.name || (p.from?.game ?? p.from?.app)) L.push(`  from ${p.from.name ?? (p.from.game ?? p.from.app)}${p.from.studio ? ` by ${p.from.studio}` : ''}`);
         const bits = [costWords(p.cost) && `costs ${costWords(p.cost)}`, buildsWords(p.requires) && `builds on ${buildsWords(p.requires)}`, p.rig && `rig ${p.rig}`, p.netplay && `in a room: ${p.netplay}`].filter(Boolean);

package/lib/parts-purchase.mjs

@@ -0,0 +1,174 @@
+import { payWithWallet } from './purchase-wallet.mjs';
+/** Buyer purchase records and pristine backups never belong in public source or game bundles. */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { digest, manifestHash, verifyGrant } from "../worker/purchase-crypto.mjs";
+import { priceWords } from "../worker/purchase-pricing.mjs";
+import { quoteHash } from "../worker/parts-sale.mjs";
+import { checkPart, parseRef, sha256 } from './parts.mjs';
+
+const directory = (root) => join(root, '.homie', 'paid-parts');
+const recordName = (ref, game) => sha256(`${ref}\n${game ?? ''}`);
+function privateWrite(root, path, value) {
+  mkdirSync(directory(root), { recursive: true, mode: 0o700 });
+  const ignore = join(root, '.gitignore');
+  const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+  if (!text.split('\n').includes('/.homie/paid-parts/')) writeFileSync(ignore, `${text}${text && !text.endsWith('\n') ? '\n' : ''}/.homie/paid-parts/\n`);
+  writeFileSync(`${path}.tmp`, JSON.stringify(value), { mode: 0o600 }); chmodSync(`${path}.tmp`, 0o600); renameSync(`${path}.tmp`, path);
+}
+function read(path) { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } }
+const recordPath = (root, ref, game) => join(directory(root), `${recordName(ref, game)}.json`);
+export async function purchaseFetch(url, { fetch: f = globalThis.fetch, method = 'GET', body, authorization, max = 1024 * 1024 } = {}) {
+  const r = await f(url, { method, redirect: 'error', signal: AbortSignal.timeout(30000), headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}), ...(authorization ? { authorization: `Bearer ${authorization}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+  const reader = r.body?.getReader(); let count = 0; const chunks = [];
+  if (reader) for (;;) { const { done, value } = await reader.read(); if (done) break; count += value.length; if (count > max) { await reader.cancel(); throw new Error('Purchase response exceeds its size limit'); } chunks.push(value); }
+  let data;
+  try { data = JSON.parse(Buffer.concat(chunks).toString()); } catch { throw new Error(`Purchase service answered ${r.status} without JSON`); }
+  return { status: r.status, data };
+}
+function purchaseNeeded(purchase) {
+  const error = new Error(purchase.message); error.purchase = purchase; throw error;
+}
+
+/** Request payment from the existing wallet only for the approved immutable quote. */
+export async function paidAccess(root, ref, part, { game = null, quantity = 1, approve = null, fetch, offer = part.sale, wallet, walletPay = payWithWallet } = {}) {
+  game = offer.scope === 'game' ? game : null;
+  const origin = `https://${ref.host}`; const hash = await manifestHash(part); const quote = await quoteHash(part, quantity, game, offer); const path = recordPath(root, ref.ref, game);
+  let record = read(path);
+  let exchange;
+  if (record?.recovery) {
+    const recovered = await purchaseFetch(`${origin}/api/purchases/recover`, { fetch, method: 'POST', authorization: record.claim, body: {} });
+    if (!recovered.data.ok || recovered.data.order !== record.order) throw new Error('Seller has not reissued this purchase yet');
+    const r = recovered.data;
+    record = { ...record, recovery: false, buyer: r.buyer, quantity: r.quantity, game: r.game, version: r.manifest.version, manifestHash: await manifestHash(r.manifest), quote: await quoteHash(r.manifest, r.quantity, r.game), price: priceWords(r.manifest.sale, r.quantity) };
+    privateWrite(root, recordPath(root, ref.ref, r.game), record);
+  }
+  if (!record) {
+    if (approve !== quote) purchaseNeeded({ required: true, quote, part: ref.ref, version: part.version, price: priceWords(offer, quantity), sale: offer, licence: part.license, terms: `${origin}/parts/${ref.id}/${part.version}/${part.licenseTerms}`, quantity, game, message: `Ask first: ${part.name} from ${ref.host}, ${priceWords(offer, quantity)}. Show the licence, refund and recurring terms. Only authority for this exact price permits requesting payment through the person’s wallet; Checkout is the fallback.` });
+    if (!Number.isSafeInteger(quantity) || quantity < 1) throw new Error('Quantity must be a positive whole number');
+    if (offer.scope === 'game' && !game) throw new Error('This licence needs the game being licensed');
+    const identityPath = join(directory(root), 'identity.json'); let identity = read(identityPath);
+    if (!identity) { identity = { buyer: randomBytes(32).toString('hex') }; privateWrite(root, identityPath, identity); }
+    record = { createdAt: Date.now(), buyer: identity.buyer, buyerName: String(read(join(root, 'studio.json'))?.name ?? 'Buying studio').slice(0, 80), claim: randomBytes(32).toString('hex'), quote, manifestHash: hash, version: part.version, price: priceWords(offer, quantity), quantity, game, origin, ref: ref.ref };
+    privateWrite(root, path, record);
+  }
+  if (!record.order) {
+    // A retry of a previously approved intent is bound to its original quote and quantity.
+    if ((record.quote !== quote || record.quantity !== quantity) && approve === quote) { privateWrite(root, path, null); return paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }); }
+    if (record.quote !== quote || record.quantity !== quantity) purchaseNeeded({ required: true, quote, price: priceWords(offer, quantity), message: 'Price, terms or quantity changed. Approve the new quote with a new purchase record.' });
+    if (offer.billing === 'one-time' && offer.currency === 'usd' && !offer.automaticTax && offer.taxBehavior !== 'exclusive' && (wallet || process.env.HOMIE_PARTS_WALLET)) {
+      const paid = await walletPay(`${origin}/api/purchases/resource`, { kind: 'part', resource: part.id, version: part.version, buyer: record.buyer, claim: record.claim, quote, quantity, game, amount: offer.amount * quantity }, { client: wallet, pending: record.walletPending });
+      if (paid?.pending) {
+        record.walletPending = paid.pending; privateWrite(root, path, record);
+        purchaseNeeded({ required: true, wallet: paid.approval, quote, price: priceWords(offer, quantity), message: 'Approve this spend in your wallet app, then call part_add again. The wallet controls authority and limits.' });
+      }
+      record.walletPending = null;
+      privateWrite(root, path, record);
+      if (paid?.data?.order) {
+        exchange = paid.data;
+        record.order = paid.data.order; privateWrite(root, path, record);
+      } else {
+        const reason = paid?.data?.detail ?? paid?.data?.message ?? 'The wallet could not complete this payment';
+        if (paid?.uncertain || /Settlement|recording|processing|do not pay again/i.test(reason)) throw new Error(reason);
+        record.walletUnavailable = reason;
+        // Retain this private claim so a corrected wallet can retry it.
+        privateWrite(root, path, record);
+        if (!paid?.data?.checkout) purchaseNeeded({ required: true, quote, price: priceWords(offer, quantity), walletUnavailable: reason, machine: `${origin}/api/purchases/resource`, message: `${reason}. Retry part_add with the corrected wallet, or omit wallet to choose the hosted Checkout fallback. No payment was confirmed.` });
+      }
+    }
+    if (!record.order) {
+    if (record.walletUnavailable) { record.claim = randomBytes(32).toString('hex'); privateWrite(root, path, record); }
+    const { status, data } = await purchaseFetch(`${origin}/api/purchases/intent`, { fetch, method: 'POST', body: { kind: 'part', resource: part.id, version: part.version, buyer: record.buyer, buyerName: record.buyerName, claimHash: await digest(record.claim), quote, quantity: record.quantity, game } });
+    if (status !== 200 || !data.ok) throw new Error(data.message ?? 'Purchase could not be prepared');
+    if (new URL(data.url).origin !== origin) throw new Error('Purchase URL is not on the seller origin');
+    record.order = data.order; record.url = data.url; privateWrite(root, path, record);
+    purchaseNeeded({ required: true, checkout: record.url, price: priceWords(offer, quantity), message: `${record.walletUnavailable ? record.walletUnavailable + ". " : ""}Machine payments are also available: name link-cli or purl as the wallet before starting Checkout. Hosted Checkout fallback: the person opens ${record.url}, reads the licence and pays on Stripe. Then call part_add again. Nothing has been charged by the assistant.` });
+    }
+  }
+  const { status, data } = exchange ? { status: 200, data: exchange } : await purchaseFetch(`${origin}/api/purchases/grant`, { fetch, method: 'POST', authorization: record.claim, body: { version: part.version } });
+  if (status !== 200 || !data.ok) {
+    if (status === 401 && record.createdAt && Date.now() - record.createdAt > (offer.intentMinutes ?? 30) * 60000) data.status = 'expired';
+    if (approve === quote && ((status === 401 && quote !== record.quote) || (status === 403 && quote !== record.quote) || ['expired', 'failed', 'refunded', 'lost'].includes(data.status))) {
+      privateWrite(root, join(directory(root), `${recordName(ref.ref, game)}-${record.order}.purchase.json`), record);
+      privateWrite(root, path, null);
+      return paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay });
+    }
+    if (data.status) record.status = data.status;
+    if (data.paidUntil !== undefined) record.paidUntil = data.paidUntil;
+    record.checkedAt = new Date().toISOString(); privateWrite(root, path, record);
+    purchaseNeeded({ required: true, checkout: record.url, status: record.status, quote, price: priceWords(offer, quantity), sale: offer, licence: part.license, terms: `${origin}/parts/${ref.id}/${part.version}/${part.licenseTerms}`, message: data.message ?? 'Finish the purchase on Stripe, then call part_add again' });
+  }
+  const { calculateJwkThumbprint, decodeProtectedHeader } = await import('jose');
+  let jwk = record.jwk;
+  if (!jwk || decodeProtectedHeader(data.token).kid !== await calculateJwkThumbprint(jwk)) {
+    const keys = await purchaseFetch(`${origin}/purchases/keys.json`, { fetch });
+    if (keys.status !== 200 || !Array.isArray(keys.data.keys) || !keys.data.keys.length) throw new Error('The seller supplied no unambiguous signing key');
+    jwk = keys.data.keys.find((k) => k.kid === decodeProtectedHeader(data.token).kid);
+    if (!jwk) throw new Error('Seller key is not in its HTTPS key ring');
+  }
+  const claims = await verifyGrant(data.token, jwk, { issuer: origin, subject: record.buyer, kind: 'part', resource: part.id, version: part.version });
+  if (claims.manifest !== hash || await manifestHash(data.manifest) !== hash || (part.version === record.version && hash !== record.manifestHash) || claims.jti !== record.order || (claims.quantity !== record.quantity && claims.billing === 'one-time') || claims.game !== record.game || (record.mode && record.mode !== claims.mode)) throw new Error('The signed licence differs from the approved purchase');
+  const evidence = await verifyGrant(data.proof, jwk, { proof: true, issuer: origin, subject: record.buyer, kind: 'part', resource: part.id, version: part.version });
+  if (evidence.manifest !== claims.manifest || evidence.jti !== claims.jti) throw new Error('Purchase evidence does not match the download');
+  record = { ...record, trustedKeys: [...new Map([...(record.trustedKeys ?? []), ...(record.jwk ? [record.jwk] : []), jwk].map((k) => [k.x, k])).values()], quantity: claims.quantity, paidUntil: claims.paidUntil, jwk, token: data.token, proof: data.proof, mode: claims.mode, status: 'paid', checkedAt: new Date().toISOString() }; privateWrite(root, path, record);
+  return { token: data.token, proof: data.proof, claims, jwk, record, files: exchange?.files };
+}
+
+export function savePurchaseBackup(root, got, access, game) {
+  game = access.claims.game;
+  const path = recordPath(root, got.ref.ref, game); const record = read(path);
+  // One JSON archive retains exact bytes, including files the buyer later edits. Its token is private.
+  const archive = { ref: got.ref, part: got.part, entry: got.entry, base: got.base, version: got.version, versions: got.versions, token: access.proof, jwk: access.jwk, buyer: record.buyer, files: [...got.files].map(([path, bytes]) => [path, bytes.toString('base64')]) };
+  const name = `${recordName(got.ref.ref, game)}-${got.version}.backup.json`;
+  privateWrite(root, join(directory(root), name), archive);
+  record.backup = name; privateWrite(root, path, record);
+}
+export async function offlinePurchase(root, refText, game) {
+  const ref = parseRef(refText); if (!ref) throw new Error('Name a part');
+  const record = read(recordPath(root, ref.ref, game)) ?? read(recordPath(root, ref.ref, null));
+  game = record?.game;
+  const name = ref.version ? `${recordName(ref.ref, game)}-${ref.version}.backup.json` : record?.backup;
+  const backup = name ? read(join(directory(root), name)) : null;
+  if (!backup) throw new Error('No private purchase backup for this part and game');
+  if (backup.ref?.ref !== ref.ref || backup.ref?.host !== ref.host || backup.ref?.id !== ref.id || backup.version !== backup.part?.version || backup.base !== record.origin) throw new Error('Purchase backup identifies another release');
+  if (![...(record.trustedKeys ?? []), record.jwk].some((key) => key?.x === backup.jwk?.x)) throw new Error('Archive key is not a pinned seller key');
+  const claims = await verifyGrant(backup.token, backup.jwk, { proof: true, issuer: backup.base, subject: backup.buyer, kind: 'part', resource: ref.id, version: backup.version });
+  if (!checkPart(backup.part).ok || claims.manifest !== await manifestHash(backup.part)) throw new Error('Purchase backup manifest failed verification');
+  if (record.status === 'refunded' || record.status === 'lost') { if (claims.onRefund === 'terminate') throw new Error('This purchase was revoked under its refund terms'); }
+  if (claims.paidUntil && claims.paidUntil <= Date.now() && claims.onExpiry === 'terminate') throw new Error('This subscription licence has expired');
+  const files = new Map(backup.files.map(([path, bytes]) => [path, Buffer.from(bytes, 'base64')]));
+  if (files.size !== backup.part.files.length || files.size !== backup.files.length) throw new Error('Purchase backup contains unlisted files');
+  for (const f of backup.part.files) if (!files.has(f.path) || files.get(f.path).length !== f.bytes || sha256(files.get(f.path)) !== f.sha256) throw new Error('Purchase backup files failed verification');
+  return { ...backup, files, purchase: { version: claims.version, mode: claims.mode, scope: claims.terms.scope, game: claims.game, quantity: claims.quantity, paidUntil: claims.paidUntil, onExpiry: claims.onExpiry, onRefund: claims.onRefund, checkedAt: record.checkedAt, offline: true, status: record.status } };
+}
+export async function purchasePortal(root, refText, { game = null, fetch, action = 'portal' } = {}) {
+  const ref = parseRef(refText); const record = ref && (read(recordPath(root, ref.ref, game)) ?? read(recordPath(root, ref.ref, null)));
+  if (!record?.order && action === 'portal' && ref) {
+    const { status, data } = await purchaseFetch(`https://${ref.host}/api/purchases/portal-login`, { fetch });
+    if (status !== 200) throw new Error(data.message);
+    return { ...data, command: 'parts manage' };
+  }
+  if (!record?.order) throw new Error('No purchase here to manage');
+  const { status, data } = await purchaseFetch(`${record.origin}/api/purchases/${action}`, { fetch, method: 'POST', authorization: record.claim, body: {} });
+  if (status !== 200) throw new Error(data.message ?? 'Stripe portal unavailable');
+  if (action === 'refund') return { ...data, command: 'parts refund' };
+  return { ok: true, command: 'parts manage', url: data.url, message: `Open ${data.url} to manage or cancel this subscription in Stripe.` };
+}
+
+/** Last checked state for publish reports; private credentials never leave this module. */
+export function purchaseFacts(root, ref, game) {
+  const r = read(recordPath(root, ref, game)) ?? read(recordPath(root, ref, null));
+  return r ? { status: r.status, paidUntil: r.paidUntil, checkedAt: r.checkedAt } : {};
+}
+
+/** Prepare a recovery request without giving the seller the new claim secret. */
+export function prepareRecovery(root, refText, order, game = null) {
+  const ref = parseRef(refText);
+  if (!ref || !/^ord_[A-Za-z0-9]{20}$/.test(order ?? '')) throw new Error('Supply the part and order from the receipt or seller');
+  const existing = read(recordPath(root, ref.ref, game)) ?? read(recordPath(root, ref.ref, null));
+  if (existing?.claim && !existing.recovery) return { ok: false, command: 'parts recover', message: 'A healthy purchase claim already exists; keep it and run parts add' };
+  const claim = randomBytes(32).toString('hex');
+  privateWrite(root, recordPath(root, ref.ref, game), { claim, order, origin: `https://${ref.host}`, ref: ref.ref, game, recovery: true });
+  return digest(claim).then((claimHash) => ({ ok: true, command: 'parts recover', order, claimHash, message: 'Give the seller this order and claimHash with your Stripe receipt. After reissue, run parts add again. Keep this private purchase folder.' }));
+}

package/lib/parts-store.mjs

@@ -1,3 +1,6 @@
+import { paidAccess, savePurchaseBackup, offlinePurchase, purchaseFacts } from './parts-purchase.mjs';
+import { priceWords } from "../worker/purchase-pricing.mjs";
+
 /**
  * FINDING, ADDING AND SHARING PARTS (parts/PARTS.md): what the four chat tools do (lib/parts-tools.mjs).
  *
@@ -37,13 +40,13 @@ export function baseOf(host) {
 }
 
 /** Every request this file makes. Bytes back, capped; a plain sentence when it fails. */
-async function get(url, { fetch: f = globalThis.fetch, max = LIMITS.fileBytes, what = 'the file' } = {}) {
+async function get(url, { fetch: f = globalThis.fetch, max = LIMITS.fileBytes, what = 'the file', authorization } = {}) {
   let res;
-  try { res = await f(url, { redirect: 'follow', headers: { accept: '*/*' } }); } catch (error) { throw new Error(`${new URL(url).host} could not be reached (${String(error?.cause?.code ?? error?.message ?? error).slice(0, 80)})`); }
+  try { res = await f(url, { redirect: authorization ? 'error' : 'follow', headers: { accept: '*/*', ...(authorization ? { authorization: `Bearer ${authorization}` } : {}) }, signal: AbortSignal.timeout(30000) }); } catch (error) { throw new Error(`${new URL(url).host} could not be reached (${String(error?.cause?.code ?? error?.message ?? error).slice(0, 80)})`); }
   if (!res.ok) throw new Error(`${url} answered ${res.status}: ${what} is not there`);
-  const bytes = Buffer.from(await res.arrayBuffer());
-  if (bytes.length > max) throw new Error(`${url} is ${bytes.length} bytes, more than ${what} may be (${max})`);
-  return bytes;
+  const reader = res.body?.getReader(); const chunks = []; let size = 0;
+  if (reader) for (;;) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > max) { await reader.cancel(); throw new Error(`${url} exceeds the size ${what} may be (${max} bytes)`); } chunks.push(value); }
+  return Buffer.concat(chunks);
 }
 async function getJson(url, opts) {
   const bytes = await get(url, { max: 4 * 1024 * 1024, ...opts });
@@ -55,12 +58,22 @@ async function getJson(url, opts) {
  * Nothing is returned unless every file's SHA-256 and size are what the part.json says, so nothing unverified can
  * be written by a caller.
  */
-export async function fetchPart(refText, { fetch } = {}) {
+export async function fetchPart(refText, { fetch, onPaid } = {}) {
   const ref = parseRef(refText);
   if (!ref) throw new Error(`"${String(refText).slice(0, 80)}" does not name a part: "<studio site>/<part id>", such as "owls.example/pickup-field" (and "@1.2.0" for one version)`);
   const base = baseOf(ref.host);
-  const index = await getJson(`${base}/.well-known/homie-parts.json`, { fetch, what: 'the studio\'s list of shared parts' }).catch((error) => { throw new Error(`${ref.host} shares no parts that can be read: ${error.message}`); });
-  const entry = (Array.isArray(index?.parts) ? index.parts : []).find((p) => p?.id === ref.id);
+  let catalog = `${base}/parts/catalog.json`;
+  try {
+    const discovery = await getJson(`${base}/.well-known/api-catalog`, { fetch, what: 'the studio API catalogue' });
+    const candidate = discovery.linkset?.flatMap((item) => item.item ?? []).find((item) => item.type === 'application/json' && new URL(item.href).origin === base);
+    if (candidate) catalog = candidate.href;
+  } catch { /* Older studios expose the resource catalogue directly. */ }
+  const index = await getJson(catalog, { fetch, what: 'the studio list of shared parts' }).catch(() => getJson(`${base}/.well-known/homie-parts.json`, { fetch, what: 'the older studio catalogue' })).catch((error) => { throw new Error(`${ref.host} shares no parts that can be read: ${error.message}`); });
+  let entry = (Array.isArray(index?.parts) ? index.parts : []).find((p) => p?.id === ref.id);
+  if (!entry && ref.version) {
+    const retired = await getJson(`${base}/parts/${ref.id}/${ref.version}/part.json`, { fetch, max: LIMITS.json, what: 'the previously sold release' });
+    if (retired.sale) entry = { ...retired, versions: [ref.version] };
+  }
   if (!entry) {
     const names = (Array.isArray(index?.parts) ? index.parts : []).map((p) => p?.id).filter(Boolean);
     throw new Error(`${ref.host} does not share a part "${ref.id}"${names.length ? ` (it shares: ${names.slice(0, 12).join(', ')})` : ' (it shares none)'}. A part its studio keeps private is not there to add.`);
@@ -75,16 +88,19 @@ export async function fetchPart(refText, { fetch } = {}) {
   if (part.id !== ref.id || part.version !== version) throw new Error(`${at}part.json says it is ${part.id} ${part.version}, not ${ref.id} ${version}`);
   if (part.share !== true) throw new Error(`${ref.ref} is not shared`);
   if (!Array.isArray(part.files) || !part.files.length) throw new Error(`${ref.ref} ${version} lists no files`);
+  const access = part.sale ? (onPaid ? await onPaid(ref, part, entry.releases?.find((r) => r.version === version)?.offer ?? part.sale) : null) : null;
+  if (part.sale && !access) throw new Error(`This is a paid part: ${priceWords(part.sale)}. Use part_add to review its price first.`);
   const files = new Map();
   let total = 0;
   for (const f of part.files) {
-    const bytes = await get(`${at}${f.path.split('/').map(encodeURIComponent).join('/')}`, { fetch, max: Math.min(LIMITS.fileBytes, f.bytes), what: f.path });
+    const delivered = access?.files?.find((item) => item.path === f.path);
+    const bytes = delivered ? Buffer.from(delivered.data, 'base64') : await get(`${at}${f.path.split('/').map(encodeURIComponent).join('/')}`, { fetch, max: Math.min(LIMITS.fileBytes, f.bytes), what: f.path, authorization: access?.token });
     if (bytes.length !== f.bytes || sha256(bytes) !== f.sha256) throw new Error(`${ref.ref} ${version}: ${f.path} is not the file its part.json describes (its SHA-256 or size differs). Nothing was written; tell its studio.`);
     total += bytes.length;
     if (total > LIMITS.totalBytes) throw new Error(`${ref.ref} is over ${Math.round(LIMITS.totalBytes / 1048576)} MB`);
     files.set(f.path, bytes);
   }
-  return { ref, part, files, entry, base, version, versions };
+  return { ref, part, files, entry, base, version, versions, access };
 }
 
 /* ------------------------------------------------------------------ packages: npm's */
@@ -124,10 +140,10 @@ export function ensurePackages(root, wants, { npm = runNpm, install = false, say
     if (ls.status === 0) { rows.push({ ...w, state: 'ok' }); continue; }
     const pinned = pinnedIn(root, w.name);
     if (pinned) { rows.push({ ...w, state: 'pinned', has: pinned, why: `${w.by} is built on ${w.name} ${w.range}; this studio's package.json has ${w.name} at ${pinned}, which npm says does not fit. Nothing was changed: move the studio to a version in that range if the part is worth it, or use a part written against ${pinned}.` }); continue; }
-    const command = `npm install --save-exact ${spec}`;
+    const command = `npm install --ignore-scripts --save-exact ${spec}`;
     if (!install) { rows.push({ ...w, state: 'missing', command, why: `${w.by} is built on ${w.name} ${w.range}, which this studio does not have.` }); continue; }
     say(`Installing ${spec} from npm: ${w.by} is built on it.`);
-    const r = npm(['install', '--save-exact', spec], { cwd: root });
+    const r = npm(['install', '--ignore-scripts', '--save-exact', spec], { cwd: root });
     const said = `${r.stdout}${r.stderr}`.trim();
     rows.push(r.status === 0 ? { ...w, state: 'installed', said } : { ...w, state: 'failed', said, command, why: `npm could not install ${spec} for ${w.by}. npm said:\n${said}` });
   }
@@ -153,7 +169,7 @@ export function partItems(root, { game = null, refs = null } = {}) {
     const dir = vendorDir(root, ref);
     let part = null;
     try { part = readPart(dir); } catch { part = null; }
-    items.push({ ref, part, vendored: true, changed: part ? verifyFiles(dir, { files: e.files }, { skipTuning: true }).changed : [] });
+    items.push({ ref, part, vendored: true, purchase: e.purchase ? { ...(e.purchases?.[game] ?? e.purchase), ...purchaseFacts(root, ref, game) } : null, changed: part ? verifyFiles(dir, { files: e.files }, { skipTuning: true }).changed : [] });
   }
   for (const o of listOwnParts(root)) if (refs ? refs.includes(o.id) : !game) items.push({ ref: o.id, part: o.part, vendored: false });
   return items;
@@ -174,12 +190,19 @@ const diffFiles = (was, now) => {
  * told to (`overwrite`); only then write. tuning.json is the studio's from the first add and is never replaced: a
  * new version's defaults land beside it as tuning.upstream.json.
  */
-export async function addPart(root, refText, { game = null, fetch, npm = runNpm, install = true, overwrite = false, say = () => {} } = {}) {
+export async function addPart(root, refText, { game = null, fetch, npm = runNpm, install = true, overwrite = false, say = () => {}, approve = null, quantity = 1, offline = false, wallet, walletPay } = {}) {
   const command = 'parts add';
   const fail = (why, extra = {}) => ({ ok: false, command, why, ...extra });
   if (game && !existsSync(experienceFile(root, game))) return fail(`there is no game "${game}" in this studio (${listGames(root).map((g) => g.id).join(', ') || 'it has none yet'})`);
   let got;
-  try { got = await fetchPart(refText, { fetch }); } catch (error) { return fail(error.message); }
+  try {
+    got = offline ? await offlinePurchase(root, refText, game) : await fetchPart(refText, { fetch, onPaid: (ref, part, offer) => paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }) });
+    if (got.access) {
+      savePurchaseBackup(root, got, got.access, game);
+      const c = got.access.claims;
+      got.purchase = { version: c.version, mode: c.mode, scope: c.terms.scope, game: c.game, quantity: c.quantity, paidUntil: c.paidUntil, onExpiry: c.onExpiry, onRefund: c.onRefund, status: 'paid', checkedAt: new Date().toISOString() };
+    }
+  } catch (error) { return fail(error.message, error.purchase ? { purchase: error.purchase } : {}); }
   const { ref, part, files, version, base, entry } = got;
   const lock = readOrigins(root);
   const was = lock.parts[ref.ref] ?? null;
@@ -205,6 +228,7 @@ export async function addPart(root, refText, { game = null, fetch, npm = runNpm,
   const games = [...new Set([...(was?.games ?? []), ...(game ? [game] : [])])].sort();
   const from = isObj(entry.from) ? { game: line(entry.from.game, 40) || null, name: line(entry.from.name, 80) || null, studio: line(entry.from.studio, 80) || null, page: /^https:\/\//.test(String(entry.from.page ?? '')) ? String(entry.from.page).slice(0, 300) : null } : isObj(part.from) ? { game: part.from.game ?? null, studio: line(part.from.studio, 80) || null } : null;
   lock.parts[ref.ref] = {
+    ...(got.purchase ? { purchase: got.purchase, purchases: { ...(was?.purchases ?? {}), ...(got.purchase.scope === 'game' ? { [game]: got.purchase } : {}) } } : {}),
     version, url: `${base}/parts/${ref.id}/${version}/`, license: part.license ?? null, attribution: part.attribution ?? '', name: part.name, kind: part.kind,
     ...(from ? { from } : {}), page: `${base}/parts/${ref.id}/`, studio: line(got.entry?.studio?.name, 80) || null,
     files: part.files.map(({ path, sha256: h, bytes }) => ({ path, sha256: h, bytes })), games, addedAt: was?.addedAt ?? new Date().toISOString(), ...(was && !same ? { updatedAt: new Date().toISOString() } : {}),
@@ -224,7 +248,7 @@ export async function addPart(root, refText, { game = null, fetch, npm = runNpm,
     license: lic?.id ?? null, asks: lic?.asks ?? null, attribution: part.attribution ?? '', ...(from ? { from } : {}),
     files: part.files.length, bytes: part.files.reduce((n, f) => n + f.bytes, 0), verified: true,
     entry: part.entry ?? null, import: part.entry ? `@parts/${ref.ref}` : null, game, credits,
-    packages, needs, licences,
+    packages, needs, licences, ...(got.purchase ? { purchase: got.purchase } : {}),
     ready: !blocked.length && !packages.some((p) => p.state === 'missing') && !needs.length && !licences.some((c) => c.level === 'conflict'),
   };
 }
@@ -289,8 +313,8 @@ export function sharePart(root, id, on = true) {
 const row = (p, extra) => ({
   id: p.id, name: p.name, kind: p.kind, version: p.version, summary: line(p.summary), license: p.license || null, tags: Array.isArray(p.tags) ? p.tags.slice(0, 12) : [],
   ...(Array.isArray(p.uses) ? { uses: p.uses } : {}),
-  from: isObj(p.from) ? { ...(p.from.app ? { app: p.from.app, open: p.from.open ?? null } : {}), ...(p.from.music ? { music: p.from.music } : {}), ...(p.from.video ? { video: p.from.video } : {}), game: p.from.game ?? null, name: p.from.name ?? null, studio: p.from.studio ?? null, play: p.from.play ?? null } : null,
-  cost: isObj(p.cost) ? p.cost : {}, requires: isObj(p.requires) ? p.requires : {}, rig: p.skeleton?.rig ?? null, netplay: p.contract?.netplay ?? null, ...extra,
+  from: isObj(p.from) ? { ...(p.from.kind ? { kind: p.from.kind, id: p.from.id ?? null } : {}), ...(p.from.app ? { app: p.from.app, open: p.from.open ?? null } : {}), ...(p.from.music ? { music: p.from.music } : {}), ...(p.from.video ? { video: p.from.video } : {}), game: p.from.game ?? null, name: p.from.name ?? null, studio: p.from.studio ?? null, play: p.from.play ?? null } : null,
+  sale: p.sale ?? null, price: priceWords(p.sale), purchaseRequired: Boolean(p.sale), licenseTerms: p.licenseTerms ?? null, quality: p.quality ?? null, checkedAt: p.checkedAt ?? null, available: p.available ?? null, cost: isObj(p.cost) ? p.cost : {}, requires: isObj(p.requires) ? p.requires : {}, rig: p.skeleton?.rig ?? null, netplay: p.contract?.netplay ?? null, ...extra,
 });
 function matches(p, { words, kind, tag, license, builds }) {
   if (kind && p.kind !== kind) return false;
@@ -332,12 +356,19 @@ export async function findParts(root, query = '', { kind = null, tag = null, lic
     const have = new Set(here.filter((h) => h.where === 'here').map((h) => h.ref));
     found = index.parts.filter((p) => isObj(p) && typeof p.id === 'string' && (typeof p.host === 'string' || typeof p.add === 'string')).map((p) => {
       const ref = parseRef(typeof p.add === 'string' ? p.add : `${p.host}/${p.id}`)?.ref;
-      return ref ? row(p, { where: 'hub', ref, add: ref, studio: line(p.studio?.name, 80) || null, page: /^https:\/\//.test(String(p.page ?? '')) ? p.page : null, here: have.has(ref), say: `Add it: part_add { "part": "${ref}" }.` }) : null;
+      return ref ? row(p, { where: 'hub', ref, add: ref, studio: line(p.studio?.name, 80) || null, page: /^https:\/\//.test(String(p.page ?? '')) ? p.page : null, here: have.has(ref), say: `${p.sale ? `Paid: ${priceWords(p.sale)}. Ask for approval of the exact quote before requesting payment. ` : 'Free. '}Add it: part_add { "part": "${ref}" }.` }) : null;
     }).filter(Boolean);
     hubState = { ok: true, url, parts: found.length };
   } catch (error) {
     hubState = { ok: false, url, why: `The catalogue of shared parts could not be read just now (${error.message}). This is NOT "no parts exist": only this studio's own parts were searched. Try again, or add a part straight from a studio you know (part_add with "<studio site>/<part id>").` };
   }
   const results = [...here.filter((p) => matches(p, filter)), ...found.filter((p) => !p.here && matches(p, filter))];
+  for (const p of results) {
+    p.relevance = words.reduce((n, w) => n + (String(p.name ?? '').toLowerCase().includes(w) ? 3 : 0) + (String(p.id).includes(w) ? 2 : 0) + (String(p.summary ?? '').toLowerCase().includes(w) ? 1 : 0), 0);
+    p.availability = p.available === false ? 'unavailable' : p.where === 'hub' && (!Number.isFinite(Date.parse(p.checkedAt)) || Date.parse(p.checkedAt) > Date.now() + 300000 || Date.now() - Date.parse(p.checkedAt) > 86400000) ? 'stale: verify with seller' : 'recently checked';
+    p.qualityMeaning = 'Seller-attested purchases are not independent payment verification; quality is informational and does not change ranking.';
+  }
+  results.sort((a, b) => b.relevance - a.relevance || (a.where === 'hub') - (b.where === 'hub') || Boolean(a.sale) - Boolean(b.sale) || String(a.ref ?? a.id).localeCompare(String(b.ref ?? b.id)));
+  for (const p of results) p.ranking = 'Text relevance first (name 3, id 2, summary 1 per matching word); ties: local first, then free before paid, then reference. Quality is informational.';
   return { ok: true, command: 'parts find', query: words.join(' '), filter: { kind, tag, license, builds }, hub: hubState, results, searched: { hub: found.length, here: here.length } };
 }