@homie-rocks/studio 0.30.1 → 0.31.0

package/lib/parts-build.mjs

@@ -0,0 +1,169 @@
+/**
+ * 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:
+ *
+ *   partsPlugin(root, game)     esbuild resolves `@parts/<host>/<id>` (a part brought in) and `@parts/<id>` (one of
+ *                               the studio's own) to the part's entry, so adding a part and one import line is a
+ *                               running piece. A game that imports a brought-in part is recorded against it and
+ *                               credited (the existing credits.json), whether or not the add named the game.
+ *   buildParts(root, dist)      site/dist/parts/: every packed version of every SHARED part, byte for byte as
+ *                               hashed, and index.json, what the Worker answers /.well-known/homie-parts.json from.
+ *                               What is shared is sharedPartsOf() and nothing else. A private part is never copied:
+ *                               what is not in dist cannot be served.
+ *   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 { dirname, join } from 'node:path';
+import {
+  assetRecords, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir, packedVersions, publicPart, readOrigins, readPart, safePath, shareProblems,
+  sharedPartsOf, syncPartCredits, vendorDir, verifyFiles, writeOrigins,
+} from './parts.mjs';
+import { gameFacts, partItems } from './parts-store.mjs';
+
+/* ------------------------------------------------------------------ importing a part */
+
+/**
+ * Where `@parts/…` points: { path } or { error }. `@parts/<host>/<id>[/<file>]` is a part the lock names;
+ * `@parts/<id>[/<file>]` is one of the studio's own. With no file it is the part's `entry`.
+ */
+export function resolvePartImport(root, spec, lock = readOrigins(root)) {
+  const segs = String(spec).replace(/^@parts\//, '').split('/').filter(Boolean);
+  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 (!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) {
+    const file = rest.join('/');
+    if (!safePath(file) || !existsSync(join(dir, file))) return { error: `'${spec}': the ${ref} part has no file ${file}` };
+    return { path: join(dir, file), ref, vendored };
+  }
+  let part;
+  try { part = readPart(dir); } catch (error) { return { error: `'${spec}': ${error.message}` }; }
+  if (!part.entry) return { error: `'${spec}': the ${ref} part has no code to import (it is ${part.kind}: files only). Name a file: '@parts/${ref}/<path>'.` };
+  if (!existsSync(join(dir, part.entry))) return { error: `'${spec}': the ${ref} part's entry ${part.entry} is missing` };
+  return { path: join(dir, part.entry), ref, vendored };
+}
+
+/** 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',
+    setup(build) {
+      const used = new Set();
+      let lock = null;
+      build.onStart(() => { used.clear(); lock = null; });
+      build.onResolve({ filter: /^@parts\// }, (args) => {
+        try { lock ??= readOrigins(root); } catch (error) { return { errors: [{ text: error.message }] }; }
+        const r = resolvePartImport(root, args.path, lock);
+        if (r.error) return { errors: [{ text: r.error }] };
+        if (r.vendored) used.add(r.ref);
+        return { path: r.path };
+      });
+      // A brought-in part a game imports is that game's to credit, even when it was added without naming the game.
+      build.onEnd(() => {
+        if (!game || !used.size || !existsSync(join(root, 'games', game))) return;
+        try {
+          const now = readOrigins(root);
+          let changed = false;
+          for (const ref of used) { const e = now.parts[ref]; if (e && !(e.games ?? []).includes(game)) { e.games = [...(e.games ?? []), game].sort(); changed = true; } }
+          if (changed) writeOrigins(root, now);
+          syncPartCredits(root, game, now);
+        } catch { /* a credit line is never worth a failed bundle; the publish report says what is missing */ }
+      });
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ the site's parts */
+
+/**
+ * site/dist/parts/: the shared parts and their index. Returns { shared: [{ id, versions }], kept: <private count> }.
+ * A part marked shared that cannot be (someone set `share` by hand past the checks) STOPS the build with the
+ * reasons: publishing a file of unknown rights quietly is the one thing this must never do.
+ */
+export function buildParts(root, dist, { studio = {}, log = () => {} } = {}) {
+  const out = join(dist, 'parts');
+  rmSync(out, { recursive: true, force: true });
+  const own = listOwnParts(root);
+  const records = assetRecords(root);
+  for (const o of own) {
+    if (o.part?.share !== true) continue;
+    const problems = shareProblems(o.part, { dir: o.dir, records }).filter((p) => !(p.field === 'files' && /^the files differ/.test(p.problem)));
+    if (problems.length) throw new Error(`parts/${o.id} is marked shared but cannot be: ${problems.map((p) => `${p.field}: ${p.problem}`).slice(0, 4).join('; ')}. Fix it, or stop sharing it (part_share with share: false); the site was not built with it.`);
+    // Edited since it was packed: the packed version is what is public; the edit needs a version of its own.
+    if (!verifyFiles(o.dir, o.part).ok || !packedVersions(root, o.id).includes(o.part.version)) {
+      const packed = verifyFiles(o.dir, o.part).ok ? packPart(root, o.id) : { ok: false };
+      if (!packed.ok) log(`warning: parts/${o.id} changed since version ${packedVersions(root, o.id).at(-1) ?? '(none)'} was shared; the site shares that version. To share the change, raise "version" in its part.json and share it again.`);
+    }
+  }
+  // The one answer to "what does this studio share".
+  const sharing = sharedPartsOf(root);
+  const names = new Map();
+  const index = [];
+  for (const { id, versions, part } of sharing) {
+    for (const v of versions) {
+      const src = packedDir(root, id, v);
+      const packed = readPart(src);
+      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)); }
+      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;
+    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 });
+    log(`shared part ${id} (${versions.join(', ')})`);
+  }
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, 'index.json'), `${JSON.stringify({ v: 1, studio: { name: studio.name ?? null }, parts: index.sort((a, b) => a.id.localeCompare(b.id)) })}\n`);
+  return { shared: sharing.map(({ id, versions }) => ({ id, versions })), kept: own.length - sharing.length };
+}
+
+/* ------------------------------------------------------------------ before going online */
+
+/**
+ * What a deploy plan shows about parts, and changes nothing:
+ *
+ *   games     each game that uses brought-in parts: every part's licence, what it asks, its attribution and the game
+ *             it came from, and plainly where licences cannot be combined (licenceIssues)
+ *   sharing   the studio's own parts this deploy makes live (sharedPartsOf)
+ *   ok        false when a game's licences cannot be combined: the caller decides whether that stops it
+ *
+ * `partsPlanLines(report)` is the same in plain lines: said before a deploy (its plan) and before a studio is listed
+ * (`publish`, lib/directory.mjs), in the same words.
+ */
+export function partsPublishReport(root) {
+  let lock;
+  try { lock = readOrigins(root); } catch (error) { return { ok: false, games: [], sharing: [], why: error.message }; }
+  const byGame = new Map();
+  for (const [ref, e] of Object.entries(lock.parts)) for (const g of e.games ?? []) { if (!byGame.has(g)) byGame.set(g, []); byGame.get(g).push([ref, e]); }
+  const games = [];
+  for (const [game, list] of [...byGame].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!existsSync(join(root, 'games', game, 'game.json'))) continue;
+    const issues = licenceIssues(partItems(root, { game }), { game: gameFacts(root, game) });
+    games.push({
+      game,
+      parts: list.sort(([a], [b]) => a.localeCompare(b)).map(([ref, e]) => { const lic = licenseOfPart(e.license); return { ref, name: e.name, version: e.version, license: lic?.id ?? null, asks: lic?.asks ?? 'nothing is known: it names no licence', attribution: e.attribution || null, from: e.from ?? null }; }),
+      issues, ok: !issues.some((i) => i.level === 'conflict'),
+    });
+  }
+  const sharing = sharedPartsOf(root).map(({ id, versions, part }) => ({ id, version: versions.at(-1), license: part.license ?? null, from: part.from ?? null }));
+  return { ok: games.every((g) => g.ok), games, sharing };
+}
+
+export function partsPlanLines(report, { at = 'deploy' } = {}) {
+  const L = [];
+  if (report.why) L.push(`Parts: ${report.why}`);
+  for (const g of report.games) {
+    L.push(`Parts in ${g.game} from other studios (their licences travel with the game):`);
+    for (const p of g.parts) L.push(`  ${p.name} ${p.version} (${p.ref})${p.from?.name || p.from?.game ? `, from ${p.from.name ?? p.from.game}` : ''}: ${p.license ?? 'NO LICENCE'}; asks ${p.asks}${p.attribution ? `; credit: ${p.attribution}` : ''}`);
+    for (const i of g.issues) L.push(`  ${i.level === 'conflict' ? 'CANNOT BE COMBINED' : i.level === 'warn' ? 'look' : 'note'} ${i.parts.join(' + ')}: ${i.problem}${i.fix ? ` (${i.fix})` : ''}`);
+    if (!g.issues.length) L.push('  Their licences can be combined, and each is credited in the game\'s credits.');
+  }
+  // The same lines before a deploy and before a listing; only where a shared part becomes visible differs.
+  if (report.sharing.length) L.push(`Parts this studio shares (${at === 'publish' ? 'the parts catalog shows them once the studio is listed' : 'live with this deploy'}): ${report.sharing.map((s) => `${s.id} ${s.version} (${s.license})`).join(', ')}`);
+  return L;
+}

package/lib/parts-cli.mjs

@@ -0,0 +1,104 @@
+/**
+ * `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.
+ *
+ *   parts find <words> [--kind <kind>] [--tag <tag>] [--license <SPDX>] [--builds <package or rig>]
+ *   parts new <id> [--kind <kind>] [--name "<Name>"] [--from <game> <paths in the game…>]
+ *   parts add <host>/<id>[@<version>] [--game <id>] [--overwrite] [--no-install]     (again: the newer version)
+ *       --no-install: bring the part in and install nothing. package.json and package-lock.json are not touched and
+ *       npm is only asked what the studio has (`npm ls`). Each package the part builds on that is missing is named
+ *       "NOT INSTALLED" with the one npm command that installs it. The part will not build until that is run.
+ *   parts share <id>      parts unshare <id>      (live after the studio's next deploy)
+ *   parts check [<id>]                             (what stands in the way of sharing; rewrites the hashes)
+ */
+import { newPart } from './parts.mjs';
+import { addPart, checkParts, findParts, sharePart } from './parts-store.mjs';
+
+export const PARTS_VERBS = ['find', 'new', 'add', 'share', 'unshare', 'check'];
+
+/**
+ * What `parts add` takes, in the words the command prints when it is not given a part. `--no-install` is said as
+ * what it does: nothing is installed and package.json is not written (npm writes it, when npm installs). A test
+ * runs the flag through the real command and holds these words to what happened.
+ */
+export const PARTS_ADD_USAGE = 'homie-studio parts add <studio site>/<part id>[@<version>] [--game <id>] [--overwrite] [--no-install]\n  --no-install: install nothing and leave package.json as it is; a package the part builds on that this studio does not have is named NOT INSTALLED with the npm command that installs it (the part will not build until then).';
+
+export async function partsCommand(root, sub, positional, flags, { log = () => {}, fetch, npm } = {}) {
+  const arg = positional[2];
+  const str = (k) => (typeof flags.get(k) === 'string' ? flags.get(k) : null);
+  switch (sub ?? 'find') {
+    case 'find': return findParts(root, positional.slice(2).join(' '), { kind: str('kind'), tag: str('tag'), license: str('license'), builds: str('builds'), fetch, hub: str('hub') });
+    case 'new': return newPart(root, arg, { kind: str('kind') ?? 'mechanic', name: str('name'), from: str('from'), paths: positional.slice(3) });
+    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}` };
+    default: return { ok: false, command: 'parts', why: `"${sub}" is not a parts command: ${PARTS_VERBS.join(', ')}` };
+  }
+}
+
+/* ------------------------------------------------------------------ plain lines */
+
+const costWords = (c) => { const b = []; if (Number.isFinite(c?.bytes)) b.push(`${Math.max(1, Math.round(c.bytes / 1024))} KB`); if (Number.isFinite(c?.triangles)) b.push(`${c.triangles} triangles`); if (Number.isFinite(c?.drawCalls)) b.push(`${c.drawCalls} draws`); if (Number.isFinite(c?.textureMB)) b.push(`${c.textureMB} MB textures`); return b.join(', '); };
+const buildsWords = (r) => [...Object.keys(r?.packages && typeof r.packages === 'object' ? r.packages : {}), ...(Array.isArray(r?.parts) ? r.parts.map((x) => `the part ${x}`) : [])].join(', ');
+const issueLines = (issues) => issues.map((i) => `  ${i.level === 'conflict' ? 'CANNOT BE COMBINED' : i.level === 'warn' ? 'look' : 'note'} ${i.parts.join(' + ')}: ${i.problem}${i.fix ? `\n      ${i.fix}` : ''}`);
+const packageLines = (rows) => rows.filter((p) => p.state !== 'ok').map((p) => (p.state === 'installed' ? `  npm installed ${p.name}@${p.range}, for ${p.by}` : p.state === 'missing' ? `  NOT INSTALLED ${p.name}@${p.range}: ${p.why} npm installs it with: ${p.command}` : `  ${p.state === 'pinned' ? 'PACKAGE DOES NOT FIT' : 'NPM FAILED'}: ${p.why}`));
+
+function addLines(r) {
+  const L = [];
+  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.`);
+  if (r.from?.name || r.from?.game) L.push(`  It came out of ${r.from.name ?? r.from.game}${r.from.studio ? ` by ${r.from.studio}` : ''}.`);
+  L.push(`  Licence: ${r.license ?? 'NONE NAMED'} (asks ${r.asks ?? 'unknown'})${r.attribution ? `; credit: ${r.attribution}` : ''}`);
+  if (r.credits?.length) L.push(`  Credited in ${r.credits.join(', ')}.`);
+  else if (!r.game) L.push('  It is credited in a game\'s credits when that game imports it (the build does it).');
+  if (r.import) L.push(`  Use it: import … from '${r.import}'`);
+  L.push(...packageLines(r.packages ?? []));
+  for (const n of r.needs ?? []) L.push(`  It needs another part, ${n.ref}: ${n.add}`);
+  L.push(...issueLines(r.licences ?? []));
+  return L;
+}
+
+export function partsLines(r) {
+  const L = [];
+  switch (r.command) {
+    case 'parts find': {
+      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'})`}`);
+        if (p.summary) L.push(`  ${p.summary}`);
+        if (p.from?.name || p.from?.game) L.push(`  from ${p.from.name ?? p.from.game}${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);
+        if (bits.length) L.push(`  ${bits.join(' · ')}`);
+        L.push(`  ${p.say}`);
+      }
+      break;
+    }
+    case 'parts new':
+      L.push(`parts/${r.id} is a new ${r.kind} part (private).${r.lifted ? ` Lifted out of games/${r.from}: ${r.lifted.moved.length} module(s) moved${r.lifted.copied.length ? `, ${r.lifted.copied.length} other file(s) copied` : ''}.` : ''}`, ...r.next.map((n) => `  ${n}`));
+      break;
+    case 'parts check':
+      for (const row of r.rows) {
+        L.push(`${row.id}${row.version ? ` ${row.version}` : ''}: ${row.ok ? 'reads fine' : 'NOT A PART YET'}${row.share ? ', shared' : row.shareable ? ', could be shared' : ', private'}`);
+        for (const p of row.problems) L.push(`  ${p.level === 'refuse' ? 'FIX ' : 'look'} ${p.field}: ${p.problem}${p.fix ? `\n      ${p.fix}` : ''}`);
+        if (!row.shareable) { L.push('  Before it can be shared:'); for (const p of row.sharing) L.push(`    ${p.field}: ${p.problem}${p.fix ? `\n        ${p.fix}` : ''}`); }
+      }
+      for (const b of r.brought) L.push(`${b.ref}${b.version ? ` ${b.version}` : ''}: ${b.ok ? (b.edited.length ? `edited here (${b.edited.join(', ')}); a newer version will not replace them without being told to` : 'as fetched') : b.problem ?? `missing ${b.missing.join(', ')}`}${b.fix ? `\n      ${b.fix}` : ''}`);
+      if (!r.rows.length && !r.brought.length) L.push('No parts here yet.');
+      break;
+    case 'parts share':
+      L.push(`parts/${r.id} ${r.version} is shared under ${r.license} (asks ${r.asks}).`, r.effect);
+      break;
+    case 'parts unshare':
+      L.push(`parts/${r.id} is private.`, r.effect);
+      break;
+    case 'parts add':
+      L.push(...addLines(r));
+      break;
+    default:
+      L.push(JSON.stringify(r));
+  }
+  return L;
+}

package/lib/parts-store.mjs

@@ -0,0 +1,342 @@
+/**
+ * FINDING, ADDING AND SHARING PARTS (parts/PARTS.md): what the four chat tools do (lib/parts-tools.mjs).
+ *
+ * A part is copied into the studio and is then the studio's own to tune. This file is deliberately NOT a package
+ * manager, and rebuilds nothing that already works:
+ *
+ *   packages   are npm's. What a part builds on (`requires.packages`) is handed to npm: `npm ls` says whether the
+ *              studio has it, `npm install` installs what is missing, and npm's own words are relayed as they are.
+ *              package.json and package-lock.json are the only record. No resolver, no ranges, no lockfile here.
+ *   parts      one exact version is fetched (the latest shared one unless a version is named), its integrity
+ *              checked (every file's SHA-256 and size, node:crypto) BEFORE a byte reaches the studio, copied to
+ *              parts/_vendor/<host>/<id>/, and where it came from recorded in parts/origins.json.
+ *   credits    one line in the game's credits.json, through the same `parts[]` the asset credits use.
+ *
+ * Two things are injectable so tests touch neither the network nor the registry: `fetch` (every request goes
+ * through the one get() below) and `npm` (every npm call goes through one runner).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  LIMITS, TUNING_FILE, TUNING_UPSTREAM, assetRecords, checkPart, compareVersions, isVersion, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir,
+  packedVersions, parseRef, partDir, readOrigins, readPart, requiredParts, sha256, shareProblems, syncPartCredits, vendorDir, verifyFiles, writeHashes,
+  writeOrigins, writePart,
+} from './parts.mjs';
+import { listGames, readStudio } from './studio.mjs';
+
+export const HUB = 'https://homie.rocks';
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const line = (v, n = 200) => (typeof v === 'string' ? v.replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, n) : '');
+
+/* ------------------------------------------------------------------ the one fetch */
+
+/** A studio's site from its host: https, except a site on this computer (the local preview), which has no certificate. */
+export function baseOf(host) {
+  return `${/^(localhost|127\.0\.0\.1)(:\d+)?$/.test(host) ? 'http' : 'https'}://${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' } = {}) {
+  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)})`); }
+  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;
+}
+async function getJson(url, opts) {
+  const bytes = await get(url, { max: 4 * 1024 * 1024, ...opts });
+  try { return JSON.parse(bytes.toString('utf8')); } catch { throw new Error(`${url} is not JSON`); }
+}
+
+/**
+ * One exact version of a shared part, fetched and CHECKED: { part, files: Map(path → bytes), entry, base, version }.
+ * 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 } = {}) {
+  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);
+  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.`);
+  }
+  const versions = (Array.isArray(entry.versions) ? entry.versions : [entry.version]).filter(isVersion).sort(compareVersions);
+  const version = ref.version ?? (isVersion(entry.version) ? entry.version : versions.at(-1));
+  if (!version || !versions.includes(version)) throw new Error(`${ref.ref} has no version ${ref.version ?? '(none listed)'}; it has ${versions.join(', ') || 'none'}`);
+  const at = `${base}/parts/${ref.id}/${version}/`;
+  const part = await getJson(`${at}part.json`, { fetch, max: LIMITS.json, what: 'the part\'s part.json' });
+  const shape = checkPart(part);
+  if (!shape.ok) throw new Error(`${ref.ref} ${version} is not a part this toolkit can read: ${shape.problems.filter((p) => p.level === 'refuse').map((p) => `${p.field}: ${p.problem}`).slice(0, 3).join('; ')}`);
+  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 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 });
+    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 };
+}
+
+/* ------------------------------------------------------------------ packages: npm's */
+
+/** npm, in the studio folder: { status, stdout, stderr }. The one place npm is run (tests pass their own). */
+export function runNpm(args, { cwd }) {
+  const r = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, { cwd, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 16 * 1024 * 1024, shell: process.platform === 'win32' });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? (r.error ? String(r.error.message) : '') };
+}
+const pinnedIn = (root, name) => {
+  try { const p = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); return p.dependencies?.[name] ?? p.devDependencies?.[name] ?? null; } catch { return null; }
+};
+/** The packages a set of parts builds on: [{ name, range, by }] (one row per part that asks; npm judges each). */
+export function wantedPackages(items) {
+  const out = [];
+  for (const x of items) for (const [name, range] of Object.entries(isObj(x.part?.requires?.packages) ? x.part.requires.packages : {})) out.push({ name, range, by: x.ref });
+  return out;
+}
+
+/**
+ * What npm says about each wanted package, and (with `install`) npm installing what is missing.
+ *
+ *   ok        `npm ls <name>@<range>` found it: nothing to do
+ *   pinned    the studio's package.json already names the package and npm says that version does not fit: explained,
+ *             and NOTHING is changed (a studio's pin is its own; moving it is the person's call)
+ *   installed npm installed it (pinned exactly, as studios pin); `said` is npm's own output
+ *   failed    npm could not; `said` is npm's own error, as it printed it
+ *   missing   not installed and not asked to (`install: false`, or --no-install): `command` installs it
+ *
+ * `say` gets one plain line BEFORE anything is installed: what, and which part it is for.
+ */
+export function ensurePackages(root, wants, { npm = runNpm, install = false, say = () => {} } = {}) {
+  const rows = [];
+  for (const w of wants) {
+    const spec = `${w.name}@${w.range}`;
+    const ls = npm(['ls', spec, '--depth=0'], { cwd: root });
+    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}`;
+    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 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}` });
+  }
+  return rows;
+}
+
+/* ------------------------------------------------------------------ what a game is, to a licence */
+
+/** What a part's licence can care about in the game using it: whether the studio sells, and who the game credits. */
+export function gameFacts(root, id) {
+  let g = {}; let credits = {};
+  try { g = JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')); } catch { g = {}; }
+  try { credits = JSON.parse(readFileSync(join(root, 'games', id, 'credits.json'), 'utf8')); } catch { credits = {}; }
+  return { id, name: g.name ?? id, sells: existsSync(join(root, 'shop.json')), credits: Array.isArray(credits.parts) ? credits.parts : [] };
+}
+
+/** The studio's parts as licenceIssues() takes them: its own, and the ones it brought in (with what was changed locally). */
+export function partItems(root, { game = null, refs = null } = {}) {
+  const lock = readOrigins(root);
+  const items = [];
+  for (const [ref, e] of Object.entries(lock.parts)) {
+    if (refs ? !refs.includes(ref) : game && !(e.games ?? []).includes(game)) continue;
+    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 : [] });
+  }
+  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;
+}
+
+/* ------------------------------------------------------------------ add (and the newer version) */
+
+const diffFiles = (was, now) => {
+  const a = new Map((was ?? []).map((f) => [f.path, f.sha256])); const b = new Map((now ?? []).map((f) => [f.path, f.sha256]));
+  return { added: [...b.keys()].filter((p) => !a.has(p)), removed: [...a.keys()].filter((p) => !b.has(p)), changed: [...b.keys()].filter((p) => a.has(p) && a.get(p) !== b.get(p)) };
+};
+
+/**
+ * Adding a part (`<host>/<id>[@version]`, for a game), and the same call for a part already here: the newer
+ * version, with what changed shown.
+ *
+ * Order matters and is the safety: fetch and verify everything; refuse to replace a file the studio edited unless
+ * 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 = () => {} } = {}) {
+  const command = 'parts add';
+  const fail = (why, extra = {}) => ({ ok: false, command, why, ...extra });
+  if (game && !existsSync(join(root, 'games', game, 'game.json'))) 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); }
+  const { ref, part, files, version, base, entry } = got;
+  const lock = readOrigins(root);
+  const was = lock.parts[ref.ref] ?? null;
+  const dir = vendorDir(root, ref.ref);
+  const here = was && existsSync(dir);
+  // What the studio changed in its copy (tuning.json is meant to be changed and is never in this list).
+  const edited = here ? verifyFiles(dir, { files: was.files }, { skipTuning: true }) : { changed: [], missing: [] };
+  const changes = here ? diffFiles(was.files, part.files) : null;
+  const same = here && was.version === version && !changes.added.length && !changes.removed.length && !changes.changed.length;
+  if (here && !same && edited.changed.length && !overwrite) {
+    return fail(`${ref.ref} ${was.version} has files this studio edited: ${edited.changed.join(', ')}. Version ${version} would replace them, so nothing was changed. Keep your edits by moving them into tuning.json (which an update never touches) or into the game; or ask to replace them (overwrite).`, { ref: ref.ref, from: was.version, to: version, edited: edited.changed, changes });
+  }
+  if (!same) {
+    for (const p of changes?.removed ?? []) if (p !== TUNING_FILE) rmSync(join(dir, p), { force: true });
+    for (const [path, bytes] of files) {
+      const dest = join(dir, path);
+      mkdirSync(dirname(dest), { recursive: true });
+      if (path === TUNING_FILE && existsSync(dest)) { if (!readFileSync(dest).equals(bytes)) writeFileSync(join(dir, TUNING_UPSTREAM), bytes); else rmSync(join(dir, TUNING_UPSTREAM), { force: true }); continue; }
+      writeFileSync(dest, bytes);
+    }
+    writePart(dir, part);
+  }
+  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] = {
+    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() } : {}),
+  };
+  writeOrigins(root, lock);
+  const credits = games.map((g) => syncPartCredits(root, g, lock)).filter(Boolean);
+  // Packages: npm judges, npm installs, npm's words are relayed.
+  const packages = ensurePackages(root, wantedPackages([{ ref: ref.ref, part }]), { npm, install, say });
+  // Other parts it names: named, with what adds each. Nothing is solved or fetched for them.
+  const needs = requiredParts(part).parts.filter((d) => !lock.parts[d.ref]).map((d) => ({ ...d, add: `homie-studio parts add ${d.ref}${game ? ` --game ${game}` : ''}` }));
+  const lic = licenseOfPart(part.license);
+  const licences = game ? licenceIssues(partItems(root, { game }), { game: gameFacts(root, game) }) : licenceIssues(partItems(root, { refs: [ref.ref] }));
+  const blocked = packages.filter((p) => p.state === 'pinned' || p.state === 'failed');
+  return {
+    ok: true, command, ref: ref.ref, id: ref.id, host: ref.host, version, name: part.name, kind: part.kind, dir: `parts/_vendor/${ref.host.replace(':', '_')}/${ref.id}`,
+    ...(here ? { was: was.version, same, changes, replaced: same ? [] : edited.changed } : {}),
+    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,
+    ready: !blocked.length && !packages.some((p) => p.state === 'missing') && !needs.length && !licences.some((c) => c.level === 'conflict'),
+  };
+}
+
+/* ------------------------------------------------------------------ list, check, share */
+
+/** `parts check [<id>] [--write]`: each of the studio's parts against the format, its hashes and the rights of every file; and each brought-in part against what was fetched. */
+export function checkParts(root, id = null, { write = false } = {}) {
+  const records = assetRecords(root);
+  const own = listOwnParts(root).filter((o) => !id || o.id === id);
+  if (id && !own.length && !existsSync(partDir(root, id))) return { ok: false, command: 'parts check', why: `there is no part "${id}" in parts/ (${listOwnParts(root).map((o) => o.id).join(', ') || 'none yet'})` };
+  const rows = [];
+  for (const o of own) {
+    if (!o.part) { rows.push({ id: o.id, ok: false, problems: [{ level: 'refuse', field: 'part.json', problem: o.error, fix: null }], shareable: false, sharing: [] }); continue; }
+    const part = write ? writeHashes(o.dir) : o.part;
+    const shape = checkPart(part, { id: o.id });
+    const v = verifyFiles(o.dir, part);
+    const problems = [...shape.problems];
+    if (!v.ok) problems.push({ level: 'refuse', field: 'files', problem: `the files differ from the hashes (${[...v.changed.map((p) => `${p} changed`), ...v.missing.map((p) => `${p} is missing`), ...v.extra.map((p) => `${p} is not listed`)].slice(0, 6).join('; ')})`, fix: 'checking the part rewrites them (part_share with nothing to change)' });
+    const sharing = shareProblems(part, { dir: o.dir, records });
+    rows.push({ id: o.id, version: part.version, share: part.share === true, ok: !problems.some((p) => p.level === 'refuse'), problems, shareable: !sharing.length, sharing, files: (part.files ?? []).length });
+  }
+  const lock = readOrigins(root);
+  const brought = id ? [] : Object.entries(lock.parts).map(([ref, e]) => {
+    const dir = vendorDir(root, ref);
+    if (!existsSync(dir)) return { ref, ok: false, problem: 'its files are gone from parts/_vendor', fix: `add it again: homie-studio parts add ${ref}@${e.version}` };
+    const v = verifyFiles(dir, { files: e.files }, { skipTuning: true });
+    return { ref, version: e.version, ok: !v.missing.length, edited: v.changed, missing: v.missing, ...(v.changed.length ? { note: 'edited here: a newer version will not replace them without being told to' } : {}) };
+  });
+  return { ok: rows.every((r) => r.ok) && brought.every((b) => b.ok), command: 'parts check', rows, brought, wrote: write };
+}
+
+/**
+ * Sharing a part, or stopping. Sharing checks everything, packs this version and sets `share`; nothing is uploaded:
+ * it is LIVE AFTER THE STUDIO'S NEXT DEPLOY, and every answer says so.
+ */
+export function sharePart(root, id, on = true) {
+  const dir = partDir(root, id);
+  const command = on ? 'parts share' : 'parts unshare';
+  if (!existsSync(join(dir, 'part.json'))) return { ok: false, command, why: `there is no part "${id}" in parts/ (${listOwnParts(root).map((o) => o.id).join(', ') || 'none yet'}). A part brought in from another studio is theirs to share.` };
+  if (!on) {
+    const part = readPart(dir);
+    const was = part.share === true;
+    part.share = false;
+    writePart(dir, part);
+    for (const v of packedVersions(root, id)) { const d = packedDir(root, id, v); const p = readPart(d); p.share = false; writePart(d, p); }
+    return { ok: true, command, id, share: false, was, effect: was ? 'It stays public until the studio\'s next deploy; from that deploy on it is gone from the site and the hub. Copies other studios already made stay theirs under the licence it was shared with.' : 'It was already private.' };
+  }
+  const part = writeHashes(dir);
+  const problems = shareProblems(part, { dir, records: assetRecords(root) });
+  if (problems.length) return { ok: false, command, id, why: `parts/${id} cannot be shared yet:\n${problems.map((p) => `  ${p.field}: ${p.problem}${p.fix ? `\n      ${p.fix}` : ''}`).join('\n')}`, problems };
+  part.share = true;
+  writePart(dir, part);
+  const packed = packPart(root, id);
+  if (!packed.ok) { part.share = false; writePart(dir, part); return { ...packed, command }; }
+  const lic = licenseOfPart(part.license);
+  return { ok: true, command, id, share: true, version: part.version, license: lic.id, asks: lic.asks, files: part.files.length, bytes: part.cost?.bytes ?? 0, ...(part.from?.game ? { from: part.from } : {}), effect: 'It is live after the studio\'s next deploy, not before: nothing was uploaded now. Sharing a part does not list the studio in the directory.' };
+}
+
+/* ------------------------------------------------------------------ find */
+
+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) : [],
+  from: isObj(p.from) ? { 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,
+});
+function matches(p, { words, kind, tag, license, builds }) {
+  if (kind && p.kind !== kind) return false;
+  if (tag && !(p.tags ?? []).includes(tag)) return false;
+  if (license && String(p.license ?? '').toLowerCase() !== String(license).toLowerCase()) return false;
+  // What a part builds on: a package it names, or the skeleton it is made for.
+  if (builds && !(Object.keys(p.requires?.packages && typeof p.requires.packages === 'object' ? p.requires.packages : {}).includes(builds) || p.rig === builds)) return false;
+  const hay = [p.id, p.name, p.kind, p.summary, ...(p.tags ?? []), p.from?.name, p.from?.game, p.from?.studio].filter(Boolean).join(' ').toLowerCase();
+  return words.every((w) => hay.includes(w));
+}
+
+/**
+ * Finding parts (words, and kind, tag, licence, what a part builds on): the hub's catalogue of parts studios shared, and this
+ * studio's own and brought-in parts. Packages are not parts and are not listed.
+ *
+ * A HUB THAT CANNOT BE REACHED IS SAID, NEVER HIDDEN: `hub.ok` is false with why, and the studio's own results still
+ * come back, so an empty list is never mistaken for "nothing exists".
+ */
+export async function findParts(root, query = '', { kind = null, tag = null, license = null, builds = null, fetch, hub = null } = {}) {
+  const words = String(query ?? '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).slice(0, 8);
+  const filter = { words, kind, tag, license, builds };
+  const here = [];
+  if (root) {
+    for (const o of listOwnParts(root)) if (o.part) here.push(row(o.part, { where: 'own', share: o.part.share === true, import: o.part.entry ? `@parts/${o.id}` : null, say: `It is this studio's own part: import it from '@parts/${o.id}'.` }));
+    for (const [ref, e] of Object.entries(readOrigins(root).parts)) {
+      let part = null;
+      try { part = readPart(vendorDir(root, ref)); } catch { part = null; }
+      if (part) here.push(row({ ...part, from: e.from ?? part.from }, { where: 'here', ref, add: ref, import: part.entry ? `@parts/${ref}` : null, games: e.games ?? [], say: `Already in this studio (${e.version}): import it from '@parts/${ref}'.` }));
+    }
+  }
+  let base = hub;
+  if (!base && root) { try { const d = readStudio(root).homie?.directory; base = d === false || d === null ? null : d; } catch { base = null; } }
+  base = /^https?:\/\/[a-z0-9.:-]+$/i.test(String(base ?? '')) ? base : HUB;
+  const url = `${base}/parts/index.json`;
+  let hubState; let found = [];
+  try {
+    const index = await getJson(url, { fetch, what: 'the catalogue of shared parts' });
+    if (!Array.isArray(index?.parts)) throw new Error(`${url} is not a parts catalogue`);
+    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;
+    }).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))];
+  return { ok: true, command: 'parts find', query: words.join(' '), filter: { kind, tag, license, builds }, hub: hubState, results, searched: { hub: found.length, here: here.length } };
+}