@homie-rocks/studio 0.30.2 → 0.31.1

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

package/lib/parts-tools.mjs

@@ -0,0 +1,92 @@
+/**
+ * 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
+ * is part_add again, stopping is part_share with share false, and checking is part_share with nothing to change.
+ *
+ * The person never types a command: every result here says what happened and what to do next in words, and names a
+ * tool, never a terminal line. Tests pass `ctx.partsNet = { fetch, npm }` so nothing reaches the network or npm.
+ */
+import { PART_KINDS, newPart, partDir, readPart, writePart } from './parts.mjs';
+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).';
+
+/** 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}"` : ''} }`);
+const text = (r) => inChat(partsLines(r).join('\n'));
+
+export function partsToolDefs(ctx, h) {
+  const { ok, fail, str, STUDIO_ARG, RO, RW } = h;
+  const net = () => ctx.partsNet ?? {};
+  return [
+    {
+      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 } },
+      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 });
+      },
+    },
+    {
+      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 },
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        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() });
+        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 });
+      },
+    },
+    {
+      name: 'part_new', title: 'Make a game part',
+      description: 'Make a part of this studio: a piece of one of its games that another game can use. 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 piece of a game, never the whole game, 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'), 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'] },
+      annotations: { title: 'Make a game part', ...RW },
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const r = newPart(root, String(a.id ?? ''), { kind: a.kind ?? 'mechanic', name: a.name ?? null, from: a.from ? String(a.from) : null, paths: Array.isArray(a.files) ? a.files.map(String) : [] });
+        if (!r.ok) return fail(`No part was made: ${r.why}`, { kind: 'part', ...r });
+        return ok([text(r), r.lifted ? `Build ${r.from} now and check it still plays the same.` : '', 'Fill in parts/' + r.id + '/part.json: a one-sentence summary, what it takes from a game ("contract"), and its costs if measured. It stays private until the person asks to share it (part_share).'].filter(Boolean).join('\n'), { kind: 'part', ...r });
+      },
+    },
+    {
+      name: 'part_share', title: 'Share a game 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.',
+      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 game part', ...RW },
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const id = String(a.id ?? '');
+        if (a.license !== undefined || a.attribution !== undefined) {
+          let part;
+          try { part = readPart(partDir(root, id)); } catch { return fail(`There is no part "${id}" in this studio.`); }
+          if (a.license !== undefined) part.license = String(a.license).trim();
+          if (a.attribution !== undefined) part.attribution = String(a.attribution).slice(0, 200);
+          writePart(partDir(root, id), part);
+        }
+        if (a.share === undefined) {
+          const r = checkParts(root, id, { write: true });
+          if (!r.rows?.length) return fail(r.why ?? `There is no part "${id}" in this studio.`);
+          const row = r.rows[0];
+          return ok([text(r), row.shareable ? 'Nothing stands in the way. It is still private: share it only when the person asks (part_share with share: true).' : 'It cannot be shared until those are settled. It is private.'].join('\n'), { kind: 'part', ...r });
+        }
+        const r = sharePart(root, id, a.share === true);
+        if (!r.ok) return fail(`Not shared: ${inChat(r.why)}`, { kind: 'part', ...r });
+        return ok([text(r), a.share === true ? 'Tell the person it is live after the studio\'s next deploy (studio_deploy), and under which licence.' : ''].filter(Boolean).join('\n'), { kind: 'part', ...r });
+      },
+    },
+  ];
+}