@homie-rocks/studio 0.37.1 → 0.37.2

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 } };
 }

package/lib/parts-tools.mjs

@@ -1,3 +1,4 @@
+import { purchasePortal } from './parts-purchase.mjs';
 /**
  * GAME PARTS AS CHAT TOOLS (parts/PARTS.md): parts_find, part_add, part_new and part_share, named and worded like
  * the asset tools beside them (assets_find, asset_add). Four tools are the whole surface: a newer version of a part
@@ -11,7 +12,7 @@ import { addPart, checkParts, findParts, sharePart } from './parts-store.mjs';
 import { partsLines } from './parts-cli.mjs';
 
 /** What the planning and game-making tools say about parts, in one place so a test can hold them to it. */
-export const PARTS_FIRST = 'Before writing any system from scratch (camera, movement, bots, pickups, effects, sound, UI, environment), look for what exists, two different things: (1) the @homie-rocks/* packages on npm have the general mechanism (camera, input, audio, effects): use them; (2) `parts find` (the parts_find tool) searches the pieces of real games other studios shared: a creature from one game, a level from another, a bot brain from a third, each brought in with part_add. Record in the game\'s CODEX what came from where: which packages, which parts and the game and studio each came from, and what was written here and why. After building a piece another game could use, offer the person to make it a part (part_new lifts it out of the game) and, only if they ask, to share it (part_share).';
+export const PARTS_FIRST = 'Before writing any system from scratch (camera, movement, bots, pickups, effects, sound, UI, environment), look for what exists, two different things: (1) the @homie-rocks/* packages on npm have the general mechanism (camera, input, audio, effects): use them; (2) `parts find` (the parts_find tool) searches the pieces of games, apps, music and video other studios shared: a creature from one game, a level from another, a bot brain from a third, each brought in with part_add. Record in the project notes or CODEX what came from where: which packages, which parts and the work and studio each came from, and what was written here and why. After building a reusable piece, offer the person to make it a part (part_new lifts it out of the game) and, only if they ask, to share it (part_share).';
 
 /** A fix-it line that names the plumbing, said as the chat tool that does the same. */
 export const inChat = (t) => String(t).replace(/homie-studio parts add (\S+?)(?:@(\S+))?(?: --game (\S+))?(?=[\s).,;]|$)/g, (m, ref, v, g) => `part_add { "part": "${ref}${v ? `@${v}` : ''}"${g ? `, "game": "${g}"` : ''} }`);
@@ -24,36 +25,38 @@ export function partsToolDefs(ctx, h) {
     {
       name: 'parts_find', title: 'Find game parts',
       description: 'Search the pieces of real games that studios shared (a creature, a level generator, a chase camera, a bot brain, a pickup mechanic, an audio pack), and this studio\'s own parts. The first move when planning or building a game: run it for each system the game needs before writing one from scratch, so a new game can be made with parts from several games. Each result has its licence, the game and studio it came from, its costs, what it builds on and what part_add takes. If the catalogue cannot be reached it says so (that is not "nothing exists"). Homie\'s @homie-rocks/* packages are not parts and are not listed here: they come from npm.',
-      inputSchema: { type: 'object', properties: { query: str('Words for what the game needs: "chase camera", "pickups", "cave"'), kind: { type: 'string', enum: [...PART_KINDS], description: 'Only this kind of part' }, tag: str('Only parts with this tag'), license: str('Only this licence (an SPDX identifier, e.g. CC0-1.0)'), builds: str('Only parts that build on this: a package ("@homie-rocks/camera") or a skeleton ("humanoid-v1")'), ...STUDIO_ARG } },
+      inputSchema: { type: 'object', properties: { query: str('Words for what the game needs: "chase camera", "pickups", "cave"'), kind: { type: 'string', description: 'Only this kind of part' }, tag: str('Only parts with this tag'), license: str('Only this licence (an SPDX identifier, e.g. CC0-1.0)'), builds: str('Only parts that build on this: a package ("@homie-rocks/camera") or a skeleton ("humanoid-v1")'), ...STUDIO_ARG } },
       annotations: { title: 'Find game parts', ...RO, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio, { need: false });
         const r = await findParts(root, String(a.query ?? ''), { kind: a.kind ?? null, tag: a.tag ?? null, license: a.license ?? null, builds: a.builds ?? null, fetch: net().fetch, hub: ctx.directory ?? null });
-        return ok([text(r), '', r.results.length ? 'Tell the person what you found and which game each piece is from, with your pick; part_add brings one in. Write in the game\'s CODEX which parts it uses and what you wrote yourself and why.' : 'Nothing fits: write it, and say so in the game\'s CODEX. If it turns out reusable, offer to make it a part (part_new).'].join('\n'), { kind: 'parts', ...r });
+        return ok([text(r), '', r.results.length ? 'Tell the person what you found and which work and studio each piece is from, with your pick; part_add brings one in. Write in the project notes or CODEX which parts it uses and what you wrote yourself and why.' : 'Nothing fits: write it, and say so in the project notes or CODEX. If it turns out reusable, offer to make it a part (part_new).'].join('\n'), { kind: 'parts', ...r });
       },
     },
     {
-      name: 'part_add', title: 'Add a game part',
-      description: 'Bring a part another studio shared into this studio, for a game: one exact version is fetched (the latest unless the part names one, "<studio site>/<part id>@1.2.0"), every file is checked against its SHA-256, and it is copied into parts/ where the studio owns and tunes it. The game credits it (its licence and who made it, on the game\'s credits page), and the packages it builds on are installed by npm. For a part that is already here it brings the newer version: what changed is shown, the studio\'s tuning is kept, and a file the studio edited is never replaced unless overwrite is true (ask the person first). The result says plainly when the licences of the game\'s parts cannot be combined, and gives the one import line.',
-      inputSchema: { type: 'object', properties: { part: str('"<studio site>/<part id>", as parts_find gives it; "@<version>" for one version'), game: str('The game that will use it (its credits get the line)'), overwrite: { type: 'boolean', description: 'For a newer version: also replace files this studio edited. Only after the person agreed' }, ...STUDIO_ARG }, required: ['part'] },
-      annotations: { title: 'Add a game part', ...RW, openWorldHint: true },
+      name: 'part_add', title: 'Add a studio part',
+      description: 'Bring a part another studio shared into this studio, for a game or app, music or video: one exact version is fetched (the latest unless the part names one, "<studio site>/<part id>@1.2.0"), every file is checked against its SHA-256, and it is copied into parts/ where the studio owns and tunes it. The game credits it (its licence and who made it, on the game\'s credits page), and the packages it builds on are installed by npm. For a part that is already here it brings the newer version: what changed is shown, the studio\'s tuning is kept, and a file the studio edited is never replaced unless overwrite is true (ask the person first). The result says plainly when the licences of the game\'s parts cannot be combined, and gives the one import line.',
+      inputSchema: { type: 'object', properties: { part: str('"<studio site>/<part id>", as parts_find gives it; "@<version>" for one version'), game: str('The game or app that will use it (its credits get the line)'), approve: str('The exact quote hash returned by part_add, ONLY with owner or wallet authority covering its exact price, currency, quantity, recurrence and terms'), wallet: { type: 'string', enum: ['link-cli', 'tempo', 'purl'], description: 'The person’s installed wallet client; its authority and limits govern payment' }, quantity: { type: 'integer', minimum: 1, description: 'Quantity under the seller’s licence terms' }, offline: { type: 'boolean', description: 'Restore the verified private purchase backup without the seller; revocation status is only last known' }, manage: { type: 'boolean', description: 'Return the purchase Stripe portal link to manage or cancel a subscription' }, overwrite: { type: 'boolean', description: 'For a newer version: also replace files this studio edited. Only after the person agreed' }, ...STUDIO_ARG }, required: ['part'] },
+      annotations: { title: 'Add a studio part', ...RW, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio);
+        if (a.manage) { const r = await purchasePortal(root, String(a.part ?? ''), { game: a.game ?? null, ...net() }); return ok(r.message, { kind: 'part', ...r }); }
         const said = [];
-        const r = await addPart(root, String(a.part ?? ''), { game: a.game ? String(a.game) : null, overwrite: a.overwrite === true, say: (l) => said.push(l), ...net() });
+        const r = await addPart(root, String(a.part ?? ''), { game: a.game ? String(a.game) : null, overwrite: a.overwrite === true, approve: a.approve ?? null, quantity: a.quantity ?? 1, offline: a.offline === true, wallet: a.wallet, say: (l) => said.push(l), ...net() });
+        if (!r.ok && r.purchase) return ok(r.why, { kind: 'part', ...r, awaitingPurchase: true });
         if (!r.ok) return fail(`Not added: ${inChat(r.why)}`, { kind: 'part', ...r });
         const next = [];
         if (r.import) next.push(`In the game: import … from '${r.import}', then build. Its part.json says what it takes ("contract") and its tuning.json holds the values to tune.`);
         for (const n of r.needs) next.push(`It needs another part, ${n.ref}: part_add { "part": "${n.ref}"${a.game ? `, "game": "${a.game}"` : ''} }.`);
         if (r.licences.some((c) => c.level === 'conflict')) next.push('The licences cannot be combined (above): tell the person plainly before building on it.');
         if (r.packages.some((p) => p.state === 'pinned' || p.state === 'failed')) next.push('A package it builds on is not in place (above): the part will not build until it is.');
-        return ok([...said, text(r), ...next, 'Write in the game\'s CODEX that it uses this part and which game and studio it came from.'].join('\n'), { kind: 'part', ...r });
+        return ok([...said, text(r), ...next, 'Write in the project notes or CODEX that it uses this part and which work and studio it came from.'].join('\n'), { kind: 'part', ...r });
       },
     },
     {
       name: 'part_new', title: 'Make a shared part',
-      description: 'Make a part of this studio: a reusable piece of a game, app, music or video. With from (a game\'s id) and files (paths inside that game: a module or a folder), the files are LIFTED out of the game into parts/<id>/ and the game imports them from there, so it builds and behaves as before; a file that still reaches into the rest of the game is refused by name (pass what it needs in as an argument first). Without from, an empty part to write. A part is a reusable piece, never an entire experience, in whatever form suits it (code, assets, data, a tuned config). A new part is private. Offer this after building something reusable.',
-      inputSchema: { type: 'object', properties: { id: str('The part\'s id (lowercase, digits, hyphens): "chase-camera"'), kind: { type: 'string', enum: [...PART_KINDS], description: 'What kind of part (default mechanic)' }, name: str('Its name'), uses: { type: 'array', items: { type: 'string', enum: ['game', 'app', 'venue', 'cause', 'music', 'video'] } }, from: str('The game to lift it out of'), files: { type: 'array', items: { type: 'string' }, description: 'With from: paths inside games/<from>/ that become the part ("src/creature.ts", "src/cave")' }, ...STUDIO_ARG }, required: ['id'] },
+      description: 'Make a part of this studio: a reusable piece of a game, app, music or video. With from (a game or app id) and files (paths inside that experience: a module or a folder), the files are LIFTED out of the game into parts/<id>/ and the game imports them from there, so it builds and behaves as before; a file that still reaches into the rest of the game is refused by name (pass what it needs in as an argument first). Without from, an empty part to write. A part is a reusable piece, never an entire experience, in whatever form suits it (code, assets, data, a tuned config). A new part is private. Offer this after building something reusable.',
+      inputSchema: { type: 'object', properties: { id: str('The part\'s id (lowercase, digits, hyphens): "chase-camera"'), kind: { type: 'string', description: 'What kind of part (default mechanic)' }, name: str('Its name'), uses: { type: 'array', items: { type: 'string', enum: ['game', 'app', 'venue', 'cause', 'music', 'video'] } }, from: str('The game or app to lift it out of'), files: { type: 'array', items: { type: 'string' }, description: 'With from: paths inside games/<from>/ or apps/<from>/ that become the part ("src/creature.ts", "src/cave")' }, ...STUDIO_ARG }, required: ['id'] },
       annotations: { title: 'Make a shared part', ...RW },
       run: async (a) => {
         const root = ctx.root(a.studio);
@@ -64,7 +67,7 @@ export function partsToolDefs(ctx, h) {
     },
     {
       name: 'part_share', title: 'Share a part',
-      description: 'Share one of this studio\'s parts with other studios, or stop sharing it. Only when the person asked: a part is private until they say otherwise. It needs a licence the person picked (an SPDX identifier: CC0-1.0, CC-BY-4.0, MIT…; with license it is set here), who to credit when the licence asks, and known rights to every file: anything in the way is listed in plain words and nothing is shared. It is live after the studio\'s next deploy (studio_deploy), not before; stopping takes effect then too. With share left out it only checks and reports.',
+      description: 'Share one of this studio\'s parts with other studios, or stop sharing it. Only when the person asked: a part is private until they say otherwise. It needs a licence the person picked (an SPDX identifier: CC0-1.0, CC-BY-4.0, MIT…; with license it is set here), who to credit when the licence asks, and optional sale and licenseTerms fields in part.json for a paid licence, and known rights to every file: anything in the way is listed in plain words and nothing is shared. It is live after the studio\'s next deploy (studio_deploy), not before; stopping takes effect then too. With share left out it only checks and reports.',
       inputSchema: { type: 'object', properties: { id: str('The part\'s id'), share: { type: 'boolean', description: 'true: share it; false: stop sharing it; left out: only check what stands in the way' }, license: str('The licence the person picked, an SPDX identifier (set before sharing)'), attribution: str('Who a game using it should credit'), ...STUDIO_ARG }, required: ['id'] },
       annotations: { title: 'Share a part', ...RW },
       run: async (a) => {

package/lib/parts-upload.mjs

@@ -0,0 +1,43 @@
+/** Private R2 releases. Upload and verify before a deploy exposes the public offer. */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { listOwnParts, packedDir, packedVersions, publicPart, readPart, sha256, verifyFiles } from './parts.mjs';
+import { objectKey, releaseKey } from "../worker/parts-sale.mjs";
+
+export function paidReleases(root) {
+  return listOwnParts(root).flatMap(({ id }) => packedVersions(root, id).map((version) => {
+    const dir = packedDir(root, id, version); const part = readPart(dir);
+    return part.sale ? { dir, part: publicPart({ ...part, share: true }) } : null;
+  }).filter(Boolean));
+}
+
+/** The uploader uses the same Wrangler execution and read-back hashing as mediaMove. */
+export async function uploadPaidParts(root, { bucket, put, hash, log = () => {} }) {
+  const releases = paidReleases(root);
+  if (!releases.length) return { releases: 0, files: 0 };
+  if (!bucket) throw new Error('Paid parts need private R2 storage. Set up storage with homie-studio storage add before deploying. Never enable a public bucket domain.');
+  const temp = mkdtempSync(join(tmpdir(), 'homie-parts-upload-')); const seen = new Set();
+  try {
+    const upload = async (key, path, expected) => {
+      const before = await hash(`${bucket}/${key}`);
+      if (before.code === 0 && before.sha256 === expected.sha256 && before.bytes === expected.bytes) return;
+      if (before.code === 0 && key.startsWith('paid-parts/releases/')) throw new Error(`${key} already exists with different terms. A release is immutable`);
+      const sent = await put(`${bucket}/${key}`, path);
+      if (sent.code !== 0) throw new Error(`Paid part upload failed for ${key}. Nothing may be offered until storage is verified`);
+      const got = await hash(`${bucket}/${key}`);
+      if (got.code !== 0 || got.sha256 !== expected.sha256 || got.bytes !== expected.bytes) throw new Error(`Paid part upload failed integrity verification for ${key}`);
+    };
+    for (const { dir, part } of releases) {
+      if (!verifyFiles(dir, part).ok) throw new Error(`Packed part ${part.id} ${part.version} no longer matches its files`);
+      for (const f of part.files) {
+        if (seen.has(f.sha256)) continue;
+        await upload(objectKey(f.sha256), join(dir, f.path), f); seen.add(f.sha256);
+      }
+      const bytes = Buffer.from(JSON.stringify(part)); const file = join(temp, 'part.json'); writeFileSync(file, bytes);
+      await upload(releaseKey(part.id, part.version), file, { sha256: sha256(bytes), bytes: bytes.length });
+      log(`verified private part ${part.id} ${part.version} in R2`);
+    }
+    return { releases: releases.length, files: seen.size };
+  } finally { rmSync(temp, { recursive: true, force: true }); }
+}

package/lib/parts.mjs

@@ -20,12 +20,17 @@ import { experienceDir, experienceFile } from './studio.mjs';
  * NOTHING HERE IS A PACKAGE MANAGER: packages are npm's (lib/parts-store.mjs hands them to npm), and a part is copied
  * in and then the studio's own. There are no version ranges, no resolver and no lockfile of Homie's.
  */
+import { canonicalJson } from '../worker/referrals.mjs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const parseSpdx = (value) => require('spdx-expression-parse')(value);
+import { saleProblems } from "../worker/parts-sale.mjs";
 import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 
 export const PART_ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
-export const PART_KINDS = Object.freeze(['character', 'rig', 'clips', 'environment', 'effect', 'sound', 'ui', 'mechanic', 'shader', 'level-generator', 'bot-brain', 'audio-pack', 'set-piece', 'quiz', 'menu-board', 'waitlist', 'live-total', 'loop', 'stem', 'track', 'video-intro', 'video-template']);
+export const PART_KINDS = Object.freeze(['character', 'rig', 'clips', 'environment', 'effect', 'sound', 'ui', 'mechanic', 'shader', 'level-generator', 'bot-brain', 'audio-pack', 'set-piece', 'quiz', 'menu-board', 'waitlist', 'live-total', 'loop', 'stem', 'track', 'video-intro', 'video-template', 'app', 'music', 'video']);
 export const NETPLAY_KINDS = Object.freeze(['host-authoritative', 'replicated', 'local']);
 export const PROVENANCE = Object.freeze(['original', 'generated', 'imported']);
 export const PIVOTS = Object.freeze(['feet', 'centre', 'base', 'origin']);
@@ -107,7 +112,10 @@ export function licenseOfPart(value) {
   const id = typeof value === 'string' ? value.trim() : '';
   // Not an identifier at all; a word people write instead of one (cc0, proprietary); or a real
   // identifier in the wrong case (SPDX is case-sensitive, and "mit" must not pass as some unknown licence).
-  if (!id || !SPDX_SHAPE.test(id)) return null;
+  if (!id) return null;
+  if (!SPDX_SHAPE.test(id)) {
+    try { parseSpdx(id); return { id, class: 'unrecognised', credit: true, asks: 'read this SPDX expression and its licence texts; no alternative was selected', known: false }; } catch { return null; }
+  }
   const cased = Object.values(CLASSES).flatMap((c) => c.ids).find((k) => k.toLowerCase() === id.toLowerCase());
   if (cased ? cased !== id : Object.hasOwn(NOT_SPDX, id.toLowerCase())) return null;
   for (const [name, c] of Object.entries(CLASSES)) if (c.ids.includes(id)) return { id, class: name, credit: c.credit, asks: c.asks, known: true };
@@ -231,7 +239,7 @@ export function checkPart(part, { id = null } = {}) {
   if (!PART_ID.test(String(part.id ?? ''))) bad('id', `"${String(part.id ?? '').slice(0, 60)}" is not a part id`, 'lowercase letters, digits and hyphens, starting with a letter or digit (chase-camera)');
   else if (id && part.id !== id) bad('id', `the folder is parts/${id} but part.json says "${part.id}"`, 'name them the same');
   if (!clean(part.name, 80)) bad('name', 'it has no name', 'a few words a person would search for ("Third-person chase camera")');
-  if (!PART_KINDS.includes(part.kind)) bad('kind', part.kind === undefined ? 'it has no kind' : `"${String(part.kind).slice(0, 40)}" is not a kind of part`, `one of: ${PART_KINDS.join(', ')}`);
+  if (!(typeof part.kind === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(part.kind))) bad('kind', part.kind === undefined ? 'it has no kind' : `"${String(part.kind).slice(0, 40)}" is not a kind of part`, 'a lowercase label using letters, digits and hyphens');
   if (!isVersion(part.version)) bad('version', part.version === undefined ? 'it has no version' : `"${String(part.version).slice(0, 40)}" is not a version`, 'three numbers: 1.0.0');
   // A part being written has no summary yet; one that is shared must (shareProblems).
   if (!clean(part.summary)) warn('summary', 'it has no summary', 'one sentence: what it does and what it needs from a game');
@@ -239,6 +247,8 @@ export function checkPart(part, { id = null } = {}) {
   if (part.share !== undefined && typeof part.share !== 'boolean') bad('share', 'it is neither true nor false', 'false keeps the part private (the default); sharing the part sets it true');
   if (part.license !== undefined && part.license !== null && part.license !== '' && !licenseOfPart(part.license)) bad('license', 'it is not a licence a stranger can rely on', licenceHint(part.license));
   if (part.attribution !== undefined && typeof part.attribution !== 'string') bad('attribution', 'it is not text', 'the line a game using the part shows in its credits, or ""');
+  for (const problem of saleProblems(part)) bad('sale', problem);
+  if (part.licenseTerms !== undefined && !safePath(part.licenseTerms)) bad('licenseTerms', 'must be a file inside the part');
   if (part.tags !== undefined) {
     if (!Array.isArray(part.tags) || part.tags.some((t) => typeof t !== 'string' || !/^[a-z0-9][a-z0-9-]{0,29}$/.test(t))) bad('tags', 'a tag is not a lowercase word', 'up to 12 words such as "camera", "3d", "top-down"');
     else if (part.tags.length > 12) warn('tags', 'more than 12 tags; the first 12 are used', null);
@@ -444,6 +454,24 @@ export function packPart(root, id, { bump = null } = {}) {
   const dir = partDir(root, id);
   let part = readPart(dir);
   if (bump) { part.version = bumpVersion(part.version, bump); writePart(dir, part); }
+  // REUSE places custom licence texts under LICENSES and annotates binary files.
+  if (part.sale && part.licenseTerms && safePath(part.licenseTerms) && existsSync(join(dir, part.licenseTerms)) && !existsSync(packedDir(root, id, part.version))) {
+    const refs = [...new Set(String(part.license).match(/LicenseRef-[A-Za-z0-9.-]+/g) ?? [])];
+    if (refs.length > 1 && refs.some((ref) => !existsSync(join(dir, 'LICENSES', `${ref}.txt`)))) return { ok: false, command: 'parts pack', id, why: 'An expression with multiple custom licences needs each full text under LICENSES before packing' };
+    for (const ref of refs) {
+      const target = join(dir, 'LICENSES', `${ref}.txt`);
+      mkdirSync(dirname(target), { recursive: true });
+      if (!existsSync(target)) cpSync(join(dir, part.licenseTerms), target);
+    }
+    if (!existsSync(join(dir, 'REUSE.toml'))) writeFileSync(join(dir, 'REUSE.toml'), `version = 1
+
+[[annotations]]
+path = ["**"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = ${JSON.stringify(part.attribution || 'The selling studio')}
+SPDX-License-Identifier = ${JSON.stringify(part.license)}
+`);
+  }
   part = writeHashes(dir);
   const shape = checkPart(part, { id });
   if (!shape.ok) return { ok: false, command: 'parts pack', id, why: `parts/${id} is not a part yet: ${shape.problems.filter((p) => p.level === 'refuse').map((p) => `${p.field}: ${p.problem}${p.fix ? ` (${p.fix})` : ''}`).slice(0, 4).join('; ')}`, problems: shape.problems };
@@ -451,6 +479,9 @@ export function packPart(root, id, { bump = null } = {}) {
   if (existsSync(out)) {
     const was = readPart(out);
     const same = JSON.stringify((was.files ?? []).map((f) => [f.path, f.sha256])) === JSON.stringify(part.files.map((f) => [f.path, f.sha256]));
+    if ((was.sale || part.sale) && canonicalJson(publicPart({ ...was, share: true })) !== canonicalJson(publicPart({ ...part, share: true }))) return { ok: false, command: 'parts pack', id, why: 'A paid release is immutable, including its description, price and licence. Give the change a new version.' };
+    const legalSame = JSON.stringify({ license: was.license, licenseTerms: was.licenseTerms, sale: was.sale }) === JSON.stringify({ license: part.license, licenseTerms: part.licenseTerms, sale: part.sale });
+    if (!legalSame) return { ok: false, command: 'parts pack', id, why: 'A packed version cannot change its price or licence terms. Give it a new version.' };
     if (!same) return { ok: false, command: 'parts pack', id, version: part.version, why: `parts/${id} ${part.version} is already packed with different files, and a shared version never changes (another studio may have copied it). Give the change a new version: raise "version" in parts/${id}/part.json, then share it again.` };
     // The same bytes: only the description may have moved (a summary, `share`), so the frozen copy takes it.
     writePart(out, part);
@@ -566,7 +597,7 @@ function liftPlan(root, game, paths) {
  */
 export function newPart(root, id, { kind = 'mechanic', name = null, from = null, paths = [], uses = [] } = {}) {
   if (!PART_ID.test(String(id ?? ''))) return { ok: false, command: 'parts new', why: `"${id ?? ''}" is not a part id: lowercase letters, digits and hyphens (chase-camera)` };
-  if (!PART_KINDS.includes(kind)) return { ok: false, command: 'parts new', why: `"${kind}" is not a kind of part: ${PART_KINDS.join(', ')}` };
+  if (!(typeof kind === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(kind))) return { ok: false, command: 'parts new', why: `"${kind}" is not a lowercase kind label` };
   if (!Array.isArray(uses) || uses.some((u) => !['game', 'app', 'venue', 'cause', 'music', 'video'].includes(u))) return { ok: false, command: 'parts new', why: 'invalid intended uses' };
   const dir = partDir(root, id);
   if (existsSync(dir)) return { ok: false, command: 'parts new', why: `parts/${id} is there already` };
@@ -653,6 +684,19 @@ export function licenceIssues(items, { game = null } = {}) {
   const add = (level, parts, problem, fix = null) => out.push({ level, parts, problem, fix });
   const sa = new Map();
   for (const x of items.filter((y) => isObj(y.part))) {
+    if (x.vendored && x.part.sale) {
+      const s = x.part.sale; const p = x.purchase;
+      if (!p) add('conflict', [x.ref], 'No purchase evidence is recorded for this paid part', 'add it through part_add');
+      else {
+        if (p.version !== x.part.version) add('conflict', [x.ref], 'This game has no recorded grant for the installed paid release', 'call part_add for this game and version to check its update rights');
+        if (p.scope === 'game' && game && p.game !== game.id) add('conflict', [x.ref], `This licence covers game ${p.game}, not ${game.id}`, 'buy a licence for this game');
+        if (p.paidUntil && p.paidUntil <= Date.now() && s.onExpiry === 'terminate') add('conflict', [x.ref], 'The subscription licence expired', 'renew through the seller');
+        if (['refunded', 'lost'].includes(p.status) && s.onRefund === 'terminate') add('conflict', [x.ref], 'This purchase was revoked under its refund terms', 'settle the licence before publishing');
+        add('note', [x.ref], `${p.mode} purchase; ${p.scope} scope${p.scope === 'seat' ? `, ${p.quantity} seats` : ''}; last checked ${p.checkedAt ?? 'unknown'}. Offline evidence cannot prove current refund status.`);
+      }
+      if (game?.sells && !s.commercialUse) add('conflict', [x.ref], 'This paid licence excludes commercial use', 'obtain commercial rights before selling');
+      add('note', [x.ref], `Read ${x.part.licenseTerms}: source ${s.source ? 'included' : 'not included'}, transfer ${s.transferable ? 'permitted under the written terms' : 'requires a new licence'}. Publishing a game does not grant standalone part redistribution rights.`);
+    }
     const lic = licenseOfPart(x.part.license);
     if (!lic) { if (x.vendored) add('conflict', [x.ref], 'it names no licence, so nothing says a game may use it', 'ask its studio, or use another part'); continue; }
     if (lic.class === 'unrecognised') add('warn', [x.ref], `${lic.id} is not a licence the toolkit can reason about`, 'read it with the person before the game goes online');
@@ -677,7 +721,7 @@ export function creditLine(ref, entry) {
     url: entry.page ?? null,
     licence: lic?.id ?? null,
     licenceUrl: lic?.known ? `https://spdx.org/licenses/${lic.id}.html` : null,
-    note: entry.from?.name || entry.from?.game ? `A part of ${entry.from.name ?? entry.from.game}, from ${ref.split('/')[0]}` : `A game part from ${ref.split('/')[0]}`,
+    note: entry.from?.name || entry.from?.game ? `A part of ${entry.from.name ?? entry.from.game}, from ${ref.split('/')[0]}` : `A studio part from ${ref.split('/')[0]}`,
     part: ref,
   };
 }

package/lib/purchase-links.mjs

@@ -0,0 +1,42 @@
+/** Uses the shop's authorized Stripe API transport; no API credential goes to the Worker. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sharedPartsOf, readPart, packedDir } from './parts.mjs';
+import { canonicalJson } from '../worker/referrals.mjs';
+import { paymentLinkURL } from '../worker/shop-links.mjs';
+const hash = (v) => createHash('sha256').update(canonicalJson(v)).digest('hex');
+export async function syncPurchaseLinks({ root, api, slug, site, mode, list, till }) {
+  const file = join(root, 'parts', 'offers.json');
+  const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  const offers = sharedPartsOf(root).flatMap(({id, versions, part}) => versions.flatMap((version) => {
+    const p = readPart(packedDir(root,id,version)), config = settings[id], selected = config?.releases?.[version];
+    return p.sale && config?.active !== false && selected?.active !== false && (version === versions.at(-1) || selected?.keepOnSale === true) ? [{kind:'part',resource:id,version,name:part.name,sale:{...p.sale,...config?.price}}] : [];
+  }));
+  const configured = offers.flatMap(o => {
+    const quantities = settings[o.resource]?.quantities ?? [1];
+    if (!Array.isArray(quantities) || !quantities.length || quantities.some(q=>!Number.isSafeInteger(q) || q<1 || !Number.isSafeInteger(q*o.sale.amount))) throw new Error(`Invalid Payment Link quantities for ${o.resource}`);
+    return [...new Set(quantities)].map(quantity=>({...o,quantity}));
+  });
+  const links = (await list('/v1/payment_links')).filter((l) => l.metadata?.homie === 'purchase-links-v1' && l.metadata?.studio === slug && l.metadata?.origin === site);
+  const config = {v:1,mode,offers:[]}, keep = new Set();
+  for (const o of configured) {
+    const revision = hash({o,till});
+    let link = links.find((l)=>l.metadata?.revision === revision);
+    if (!link) {
+      const metadata = {homie:'purchase-links-v1',studio:slug,origin:site,revision};
+      const product = (await list('/v1/products')).find(p=>p.metadata?.homie === 'purchase-links-v1' && p.metadata?.studio === slug && p.metadata?.origin === site && p.metadata?.revision === revision) ?? await api('POST','/v1/products',{name:`${o.name} ${o.version}`, ...(o.sale.taxCode ? {tax_code:o.sale.taxCode}:{}),metadata},`purchase-product-${revision}`);
+      const price = (await list('/v1/prices')).find(p=>p.product === product.id && p.metadata?.revision === revision) ?? await api('POST','/v1/prices',{product:product.id,currency:o.sale.currency,unit_amount:o.sale.amount,...(o.sale.taxBehavior ? {tax_behavior:o.sale.taxBehavior}:{}),...(o.sale.billing !== 'one-time' ? {recurring:{interval:o.sale.billing}}:{}),metadata},`purchase-price-${revision}`);
+      link = await api('POST','/v1/payment_links',{line_items:[{price:price.id,quantity:o.quantity}],metadata,
+        ...(o.sale.billing === 'one-time' ? {payment_intent_data:{metadata}}:{subscription_data:{metadata}}),
+        ...(till === 'stripe-managed' ? {managed_payments:{enabled:true}} : {automatic_tax:{enabled:o.sale.automaticTax === true},...(o.sale.taxIdCollection?{tax_id_collection:{enabled:true}}:{}),...(o.sale.billing === 'one-time' && o.sale.invoiceCreation?{invoice_creation:{enabled:true}}:{}),...(o.sale.adaptivePricing === undefined?{}:{adaptive_pricing:{enabled:o.sale.adaptivePricing}})}),
+        ...(o.sale.billing === 'one-time' && o.sale.customerCreation?{customer_creation:'always'}:{}),allow_promotion_codes:o.sale.promotionCodes === true,
+        after_completion:{type:'redirect',redirect:{url:`${site}/purchases/thanks`}}},`purchase-link-${revision}`);
+    }
+    if (!paymentLinkURL(link.url)) throw new Error('Stripe returned an invalid Payment Link');
+    if (!link.active) await api('POST',`/v1/payment_links/${link.id}`,{active:true});
+    keep.add(link.id);
+    config.offers.push({kind:o.kind,resource:o.resource,version:o.version,quantity:o.quantity,offer:canonicalJson(o.sale),id:link.id,url:link.url,revision});
+  }
+  return { config, retire:async()=>{ for (const l of links) if(l.active && !keep.has(l.id)) await api('POST',`/v1/payment_links/${l.id}`,{active:false}); } };
+}

package/lib/purchase-wallet.mjs

@@ -0,0 +1,114 @@
+/** Payment authority and limits stay in the person's existing wallet client. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execute = promisify(execFile);
+export async function payWithWallet(
+  url,
+  body,
+  { client = process.env.HOMIE_PARTS_WALLET, pending, run = execute } = {},
+) {
+  if (!client) return null;
+  if (!["link-cli", "purl", "tempo"].includes(client))
+    return { data: { detail: "Choose link-cli, purl or tempo as the wallet; hosted Checkout is available." } };
+  let args;
+  if (client === "link-cli") {
+    args = [
+      "mpp",
+      "pay",
+      url,
+      "-X",
+      "POST",
+      "-d",
+      JSON.stringify(body),
+      "--format",
+      "json",
+    ];
+    if (pending?.id)
+      args.push(
+        "--spend-request-id",
+        pending.id,
+        "--approved-challenge",
+        pending.challenge,
+      );
+    else
+      args.push(
+        "--amount",
+        String(body.amount),
+        "--context",
+        `Purchase the digital resource ${body.resource} version ${body.version} from ${new URL(url).host} under the exact price and licence terms approved in this conversation. The selling studio delivers the files and signed purchase proof.`,
+      );
+  } else {
+    const atomic = BigInt(body.amount) * 10000n;
+    const purlLimit = process.env.PURL_MAX_AMOUNT;
+    if (purlLimit && !/^\d+$/.test(purlLimit))
+      return { data: { detail: "Invalid wallet maximum amount; use hosted Checkout or correct the wallet setting." } };
+    const tempoLimit = process.env.TEMPO_MAX_SPEND;
+    if (
+      tempoLimit &&
+      (!Number.isFinite(Number(tempoLimit)) || Number(tempoLimit) < 0)
+    )
+      return { data: { detail: "Invalid wallet maximum spend; use hosted Checkout or correct the wallet setting." } };
+    // Use the wallet's native per-request ceiling in its documented units.
+    const ceiling =
+      client === "tempo"
+        ? [
+            "--max-spend",
+            String(
+              Math.min(
+                body.amount / 100,
+                tempoLimit ? Number(tempoLimit) : Infinity,
+              ),
+            ),
+          ]
+        : [
+            "--max-amount",
+            String(
+              purlLimit && BigInt(purlLimit) < atomic
+                ? BigInt(purlLimit)
+                : atomic,
+            ),
+            "--network",
+            "base,base-sepolia",
+            "--output-format",
+            "json",
+          ];
+    args = [
+      ...(client === "tempo" ? ["request"] : []),
+      ...ceiling,
+      "-X",
+      "POST",
+      "--json",
+      JSON.stringify(body),
+      url,
+    ];
+  }
+  let stdout;
+  try { ({ stdout } = await run(client, args, {
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+    timeout: 60000,
+  })); } catch (error) {
+    if (error.code === 'ENOENT') return { data: { detail: `The ${client} wallet is not installed; use hosted Checkout.` } };
+    // Wallets often return a structured refusal with a nonzero exit status.
+    // A process timeout or broken output is ambiguous: never start a second payment.
+    if (error.stdout?.trim()) stdout = error.stdout;
+    else if (/declined|insufficient funds|spend limit|not authenticated|not logged in|unsupported (network|method)|user rejected|user denied/i.test(error.stderr ?? ''))
+      return { data: { detail: String(error.stderr).trim(), paymentStatus: 'not_paid' } };
+    else return { uncertain: true, data: { detail: 'The wallet stopped without a payment result. Retry this purchase to reconcile it; do not pay again.' } };
+  }
+  let result;
+  try { result = JSON.parse(stdout); }
+  catch { return { uncertain: true, data: { detail: 'The wallet returned an unreadable payment result. Retry this purchase to reconcile it; do not pay again.' } }; }
+  if (result._next?.pay_argv) {
+    const next = result._next.pay_argv.args;
+    return {
+      pending: {
+        id: result.id,
+        challenge: next[next.indexOf("--approved-challenge") + 1],
+      },
+      approval: result.approval_url,
+    };
+  }
+  const value = result.body ?? result;
+  return { data: typeof value === "string" ? JSON.parse(value) : value };
+}