@homie-rocks/studio 0.12.1 → 0.14.0

package/lib/files.mjs

@@ -0,0 +1,154 @@
+/**
+ * THE STUDIO'S FILES, FOR THE LOCAL MCP SERVER (lib/mcp.mjs). The Claude desktop app's chat has no file tools of its
+ * own, so the server gives it these, and only inside ONE studio folder: list, read, write, edit and search. A path
+ * is relative to the studio; nothing outside it is ever read or written (a symbolic link that leads out is refused
+ * too). Secrets never pass: .env and .dev.vars files and the progress feeds' write keys are neither read nor
+ * written, and git's own folder and node_modules are never written.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+
+export const FILE_LIMITS = Object.freeze({ write: 2 * 1024 * 1024, read: 400 * 1024, image: 1536 * 1024, lines: 2000, list: 600, matches: 200 });
+const IMAGES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
+const SKIP_DIRS = new Set(['node_modules', '.git', '.wrangler', '.studio', 'dist']);
+
+const inside = (base, p) => p === base || p.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
+
+function secret(rel) {
+  const parts = rel.split(/[\\/]/);
+  const name = parts[parts.length - 1];
+  return /^\.env(\..*)?$/.test(name) || name === '.dev.vars' || /\.key$/.test(name) && parts.includes('progress');
+}
+
+/** A path in the studio, checked: { abs, rel }. `write`: also refuse git's folder and node_modules. */
+export function studioPath(root, path, { write = false } = {}) {
+  const raw = String(path ?? '').trim() || '.';
+  if (raw.includes('\0')) throw new Error('that path has a NUL in it');
+  const base = realpathSync(root);
+  const abs = resolve(base, raw);
+  if (!inside(base, abs)) throw new Error(`${raw} is outside the studio (${base}); only the studio's own files are reachable`);
+  // The nearest existing folder on the way must also be inside (a symbolic link must not lead out).
+  let at = abs;
+  while (!existsSync(at)) at = dirname(at);
+  const real = realpathSync(at);
+  if (!inside(base, real)) throw new Error(`${raw} leads outside the studio through a link`);
+  const rel = relative(base, abs) || '.';
+  if (secret(rel)) throw new Error(`${rel} holds a secret: it is never read or written here`);
+  if (write) {
+    const top = rel.split(/[\\/]/)[0];
+    if (top === '.git' || rel.split(/[\\/]/).includes('node_modules')) throw new Error(`${rel} is git's or npm's own: never written by hand`);
+    if (rel === '.') throw new Error('name a file');
+  }
+  return { abs, rel, base };
+}
+
+export function listFiles(root, path = '.', { depth = 2 } = {}) {
+  const { abs, rel } = studioPath(root, path);
+  if (!existsSync(abs)) throw new Error(`${rel} does not exist`);
+  if (!statSync(abs).isDirectory()) throw new Error(`${rel} is a file (file_read reads it)`);
+  const out = [];
+  const walk = (dir, d) => {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => (b.isDirectory() - a.isDirectory()) || a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (out.length >= FILE_LIMITS.list) return;
+      if (e.name === '.DS_Store') continue;
+      const p = join(dir, e.name);
+      const r = relative(realpathSync(root), p);
+      if (secret(r)) continue;
+      if (e.isDirectory()) {
+        out.push({ path: `${r}/`, type: 'dir' });
+        if (d < depth && !SKIP_DIRS.has(e.name)) walk(p, d + 1);
+      } else {
+        let size = null;
+        try { size = lstatSync(p).size; } catch { /* gone */ }
+        out.push({ path: r, type: e.isSymbolicLink() ? 'link' : 'file', size });
+      }
+    }
+  };
+  walk(abs, 1);
+  return { path: rel, entries: out, truncated: out.length >= FILE_LIMITS.list };
+}
+
+/** Text (with line numbers from `offset`), or a picture as MCP image content. */
+export function readStudioFile(root, path, { offset = 1, limit = FILE_LIMITS.lines } = {}) {
+  const { abs, rel } = studioPath(root, path);
+  if (!existsSync(abs)) throw new Error(`${rel} does not exist`);
+  const st = statSync(abs);
+  if (st.isDirectory()) throw new Error(`${rel} is a folder (file_list lists it)`);
+  const mime = IMAGES[extname(abs).toLowerCase()];
+  if (mime) {
+    if (st.size > FILE_LIMITS.image) throw new Error(`${rel} is ${Math.round(st.size / 1024)} KB, over the ${FILE_LIMITS.image / 1024} KB a picture may be here`);
+    return { rel, image: { mimeType: mime, data: readFileSync(abs).toString('base64') }, bytes: st.size };
+  }
+  if (st.size > FILE_LIMITS.read * 8) throw new Error(`${rel} is ${Math.round(st.size / 1024)} KB: too big to read here`);
+  const buf = readFileSync(abs);
+  if (buf.subarray(0, 8000).includes(0)) throw new Error(`${rel} is not a text file`);
+  const lines = buf.toString('utf8').split('\n');
+  const from = Math.max(1, Number(offset) || 1);
+  const n = Math.min(Math.max(1, Number(limit) || FILE_LIMITS.lines), FILE_LIMITS.lines);
+  let text = '';
+  let shown = 0;
+  for (let i = from - 1; i < lines.length && shown < n; i++, shown++) {
+    const line = `${String(i + 1).padStart(5)}\t${lines[i]}\n`;
+    if (text.length + line.length > FILE_LIMITS.read) break;
+    text += line;
+  }
+  return { rel, text, from, to: from + shown - 1, lines: lines.length, more: from + shown - 1 < lines.length };
+}
+
+export function writeStudioFile(root, path, content) {
+  const { abs, rel } = studioPath(root, path, { write: true });
+  const text = String(content ?? '');
+  if (Buffer.byteLength(text) > FILE_LIMITS.write) throw new Error(`at most ${FILE_LIMITS.write / 1024 / 1024} MB a file`);
+  if (existsSync(abs) && statSync(abs).isDirectory()) throw new Error(`${rel} is a folder`);
+  const existed = existsSync(abs);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, text);
+  return { rel, bytes: Buffer.byteLength(text), created: !existed };
+}
+
+export function editStudioFile(root, path, oldText, newText, { all = false } = {}) {
+  const { abs, rel } = studioPath(root, path, { write: true });
+  if (!existsSync(abs)) throw new Error(`${rel} does not exist (file_write makes a new file)`);
+  const was = readFileSync(abs, 'utf8');
+  const from = String(oldText ?? '');
+  if (!from) throw new Error('old is the exact text to replace (it cannot be empty)');
+  const count = was.split(from).length - 1;
+  if (!count) throw new Error(`the text to replace is not in ${rel} (it must match exactly, spaces and line breaks too)`);
+  if (count > 1 && !all) throw new Error(`the text to replace is in ${rel} ${count} times: give more of it so it is unique, or all: true`);
+  const next = all ? was.split(from).join(String(newText ?? '')) : was.replace(from, () => String(newText ?? ''));
+  if (Buffer.byteLength(next) > FILE_LIMITS.write) throw new Error(`at most ${FILE_LIMITS.write / 1024 / 1024} MB a file`);
+  writeFileSync(abs, next);
+  return { rel, replaced: all ? count : 1 };
+}
+
+/** Lines matching a regular expression, in the studio's text files (never node_modules, git, builds or .studio). */
+export function searchStudio(root, pattern, { path = '.', ignoreCase = false } = {}) {
+  let re;
+  try { re = new RegExp(String(pattern ?? ''), ignoreCase ? 'i' : ''); } catch (error) { throw new Error(`not a regular expression: ${error.message}`); }
+  const { abs } = studioPath(root, path);
+  const base = realpathSync(root);
+  const matches = [];
+  const walk = (dir) => {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (matches.length >= FILE_LIMITS.matches) return;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(p); continue; }
+      if (!e.isFile() || IMAGES[extname(e.name).toLowerCase()]) continue;
+      const r = relative(base, p);
+      if (secret(r)) continue;
+      let buf;
+      try { if (statSync(p).size > 1024 * 1024) continue; buf = readFileSync(p); } catch { continue; }
+      if (buf.subarray(0, 8000).includes(0)) continue;
+      const lines = buf.toString('utf8').split('\n');
+      for (let i = 0; i < lines.length && matches.length < FILE_LIMITS.matches; i++) if (re.test(lines[i])) matches.push({ path: r, line: i + 1, text: lines[i].slice(0, 300) });
+    }
+  };
+  if (statSync(abs).isDirectory()) walk(abs);
+  else walk(dirname(abs));
+  return { pattern: String(pattern), matches, truncated: matches.length >= FILE_LIMITS.matches };
+}

package/lib/handoff.mjs

@@ -0,0 +1,128 @@
+/**
+ * `homie-studio handoff <hb_…>` — what a Claude Code session started from the Claude app does with the ONE line it
+ * was given ("Continue building <Studio>: build hb_…", HANDOFF.md in every studio):
+ *
+ *   1. fetch the brief the person gave in the chat from the directory (GET /api/studio/progress/<hb>/brief: the
+ *      build id is the read capability, and it is only ever shown in the person's own chat and that link);
+ *   2. for a build that belongs to a studio still being set up, check in from this repository (`setup attach`);
+ *   3. take the build once (`progress attach`), so the chat's card follows the work;
+ *   4. print the brief and the steps for its kind, in this toolkit's own commands.
+ *
+ * No key travels in a prompt, and no wall of text either. When this session's network does not reach the directory,
+ * it says so and names the other road: the Homie connector's build_progress, which answers with the same brief.
+ */
+import { request } from './net.mjs';
+import { startProgress } from './progress.mjs';
+import { spawnSync } from 'node:child_process';
+import { studioRepo } from './repo.mjs';
+
+/** The repository this checkout IS (its origin remote), even Homie's engine one: the session must be in the studio's. */
+function originRepo(root) {
+  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8', timeout: 5000 });
+  if (r.status !== 0) return null;
+  // Not repoFromUrl: that one never names the engine repository, and this must, to refuse it.
+  const m = /[/:]([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/.exec(r.stdout.trim().replace(/\.git$/, '').replace(/\/+$/, ''));
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+import { setupAttach } from './setup.mjs';
+import { listGames, readStudio } from './studio.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+const BUILD = /^hb_[a-f0-9]{32}$/;
+const SETUP = /^hs_[a-f0-9]{32}$/;
+
+const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const line = (v, max) => String(v ?? '').replace(/[\x00-\x1f\x7f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+const lines = (v, max) => String(v ?? '').split(/\r?\n/).map((l) => line(l, max)).filter(Boolean).join('\n').slice(0, max);
+
+/** The steps for a kind of build, in this toolkit's commands (the brief says what; these say how). */
+export function stepsFor(h, { games = [] } = {}) {
+  const id = ID.test(String(h.id ?? '')) ? h.id : null;
+  const has = id && games.includes(id);
+  const q = (s) => JSON.stringify(String(s));
+  const work = {
+    setup: [
+      'This studio was just set up from the Claude app. Go through the new-studio checklist with the person, one step at a time and never ahead (the plugin\'s studio-setup skill): it has no game yet, and its home page says "First game coming soon".',
+      'See a working game: `npx --no-install homie-studio demo` names a live one on Homie Arcade; copy a starter in only if they ask.',
+      'One small change from one sentence of theirs (the studio\'s colours in site/theme.json, a tagline in studio.json, or a first post in posts/), then plan their game into its Game Codex (`npx --no-install homie-studio codex new <id> --name "<Name>"`) before any game is made.',
+    ],
+    make: [
+      has ? `games/${id} is here already: change it as the brief says.` : id ? `npx --no-install homie-studio game new ${id} --from ${ID.test(String(h.from ?? '')) ? h.from : 'gem-rush'}${h.name ? ` --name ${q(line(h.name, 60))}` : ''}` : 'Pick an id and a name from the brief, then npx --no-install homie-studio game new <id> --from gem-rush --name "<Name>".',
+      'Make it the game the brief describes (its Game Codex, games/<id>/CODEX.md, when there is one).',
+    ],
+    port: [
+      `npx --no-install homie-studio port plan ${h.folder ? q(line(h.folder, 200)) : '<the game\'s folder>'}, then port import${id ? ` --id ${id}` : ''} (the plugin's port skill has the whole job).`,
+    ],
+    remix: [
+      h.source && id ? `npx --no-install homie-studio game remix ${line(h.source, 300)} --id ${id}` : 'npx --no-install homie-studio game remix <source.json> --id <new id>',
+      'Then make it the brief\'s own.',
+    ],
+    change: ['Make the change the brief asks for, in small steps.'],
+  }[h.kind] ?? ['Do what the brief asks.'];
+  return [
+    ...work,
+    'npm run build; npm run dev in the background; npx --no-install homie-studio check <id> --url http://127.0.0.1:8787 (on Linux without Chrome, first: npx --no-install homie-studio chrome install).',
+    'npx --no-install homie-studio progress change "<what it does, one line>"; commit on a new branch, push, gh pr create; then npx --no-install homie-studio progress pr --url <the pull request>.',
+    'Never merge the pull request: the person publishes it from the chat\'s card, in GitHub.',
+  ];
+}
+
+export async function handoff(root, build, { homie, fetchFn = globalThis.fetch, attach = startProgress, checkIn = setupAttach, repoOf = originRepo } = {}) {
+  const studio = readStudio(root);
+  // "Continue building <Studio>: setup hs_…": a studio being set up, before any build: check in, then the checklist.
+  if (SETUP.test(String(build ?? ''))) {
+    const r = await checkIn(root, build, { homie });
+    if (!r.ok) return { ok: false, command: 'handoff', setup: build, why: r.why, ...(r.needs ? { needs: r.needs } : {}) };
+    const h = { kind: 'setup', what: 'game', title: 'first steps', studio: r.name ?? studio.name, brief: '', setup: build };
+    return { ok: true, command: 'handoff', build: null, ...h, setup: { ok: true, message: r.message, renamed: r.renamed ?? [] }, attached: null, attachWhy: 'no build was opened in the chat yet (the setup card\'s Start building opens one)', steps: stepsFor(h) };
+  }
+  if (!BUILD.test(String(build ?? ''))) return { ok: false, command: 'handoff', why: 'the id from the one line the Claude app gave: hb_ (a build) or hs_ (a setup) and 32 hex digits' };
+  const directory = String(homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  // lib/net.mjs: through the environment's proxy, and an honest reason when it fails (the directory's own words, or
+  // the connection's error; only a refusal by the proxy names the network setting).
+  const got = await request(`${directory}/api/studio/progress/${build}/brief`, { headers: { accept: 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION}` } }, { fetchFn });
+  const instead = `If the Homie connector's tools are in this session, call build_progress with { "build": "${build}" }: it answers with the brief. Otherwise ask the person what to build; the card in their chat shows it.`;
+  if (!got.ok) return { ok: false, command: 'handoff', build, why: got.why, ...(got.needs ? { needs: got.needs } : {}), ...(got.status === 404 ? {} : { instead }) };
+  const body = got.body ?? {};
+  // The build is for one repository: a session in any other stops here (claude.ai may open the person's last one).
+  const want = studioRepo(body.repo)?.toLowerCase() ?? null;
+  const here = want ? (repoOf(root) ?? null)?.toLowerCase() ?? null : null;
+  if (want && here && here !== want) return { ok: false, command: 'handoff', build, why: `this build is for ${body.repo}, but this session is in ${here}: open it in ${body.repo} (the card's Build it does), and change nothing here` };
+  const h = {
+    kind: ['make', 'port', 'remix', 'change', 'setup'].includes(body.kind) ? body.kind : 'change',
+    what: ['game', 'song', 'video'].includes(body.what) ? body.what : 'game',
+    title: line(body.title, 120), studio: line(body.studio, 60) || studio.name, brief: lines(body.brief, 1200),
+    id: ID.test(String(body.id ?? '')) ? body.id : null, name: line(body.name, 60) || null, from: ID.test(String(body.from ?? '')) ? body.from : null,
+    source: /^https:\/\/\S{8,300}$/.test(String(body.source ?? '')) ? body.source : null, folder: line(body.folder, 200) || null,
+    setup: /^hs_[a-f0-9]{32}$/.test(String(body.setup ?? '')) ? body.setup : null,
+  };
+  let setup = null;
+  if (h.setup) {
+    const r = await checkIn(root, h.setup, { homie: directory });
+    setup = { ok: r.ok, message: r.ok ? r.message : r.why, renamed: r.renamed ?? [] };
+  }
+  const taken = await attach(root, { attach: build, what: h.what, id: h.id, directory });
+  let games = [];
+  try { games = listGames(root).map((g) => g.id); } catch { games = []; }
+  return {
+    ok: true, command: 'handoff', build, ...h, setup,
+    attached: taken.ok ? { feed: taken.build, shared: taken.shared?.build ?? build } : null,
+    attachWhy: taken.ok ? null : taken.why,
+    steps: stepsFor(h, { games }),
+  };
+}
+
+/** The hand-off as the session reads it. */
+export function formatHandoff(r) {
+  return [
+    `Continue building ${r.studio}: ${r.title || r.kind}`,
+    '',
+    r.brief ? `The person's brief, from the chat:\n${r.brief.split('\n').map((l) => `  ${l}`).join('\n')}` : 'No brief beyond the title: ask the person one question if anything is unclear.',
+    '',
+    r.setup ? `Setup: ${r.setup.message}${r.setup.renamed?.length ? ` (changed: ${r.setup.renamed.join(', ')}; commit them on the branch)` : ''}` : null,
+    r.attached ? `This session took build ${r.build}: the chat's card follows the work.` : r.build ? `The chat's card will not follow this session: ${r.attachWhy}` : null,
+    '',
+    'Steps:',
+    ...r.steps.map((s, i) => `  ${i + 1}. ${s}`),
+  ].filter((l) => l !== null).join('\n');
+}

package/lib/jobs.mjs

@@ -0,0 +1,181 @@
+/**
+ * THE WORK THE LOCAL MCP SERVER STARTS (lib/mcp.mjs): every studio command runs as its own process, with the
+ * studio's OWN pinned toolkit (node_modules/@homie-rocks/studio, the version its package.json names), and the
+ * system's Node. A tool call waits for it a little while (under a minute: the Claude desktop app gives a local tool
+ * call 60 s), then hands back a job id; `studio_job` reads it later, and a check, playtest or deploy also reports
+ * into the studio's progress feed, which the build card follows.
+ *
+ * WHICH NODE. Inside the Claude desktop app the server may run on the app's own built-in Node, which may not start
+ * another copy of itself (process.execPath is the app). A studio needs the system's Node and npm anyway (npm
+ * install, Wrangler, esbuild), so commands always run with the first Node 22 or newer on the PATH. A GUI app's PATH
+ * is short, so the usual places Node lives are added (Homebrew, nvm, Volta, asdf, fnm, the Node installer).
+ *
+ * Logs go to .studio/mcp/<job>.log in the studio (git-ignored). Nothing here ever runs a shell.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { PACKAGE_ROOT } from './studio.mjs';
+
+const WIN = process.platform === 'win32';
+
+const byVersionDesc = (a, b) => {
+  const pa = a.replace(/^v/, '').split('.').map(Number); const pb = b.replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((pb[i] || 0) !== (pa[i] || 0)) return (pb[i] || 0) - (pa[i] || 0);
+  return 0;
+};
+
+/** Where Node and npm usually live, after this process's own PATH. */
+export function toolPath(env = process.env, platform = process.platform, home = homedir()) {
+  const nvm = (() => {
+    const dir = join(home, '.nvm', 'versions', 'node');
+    try { return readdirSync(dir).filter((v) => /^v\d+\./.test(v)).sort(byVersionDesc).map((v) => join(dir, v, 'bin')); } catch { return []; }
+  })();
+  const extra = platform === 'win32'
+    ? [join(env.APPDATA ?? join(home, 'AppData', 'Roaming'), 'npm'), join(env.ProgramFiles ?? 'C:\\Program Files', 'nodejs'), join(env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), 'Volta', 'bin')]
+    : ['/opt/homebrew/bin', '/usr/local/bin', join(home, '.volta', 'bin'), join(home, '.asdf', 'shims'), join(home, '.local', 'bin'), join(home, '.fnm', 'aliases', 'default', 'bin'), join(home, '.bun', 'bin'), ...nvm, '/usr/bin', '/bin'];
+  const seen = new Set();
+  const out = [];
+  for (const p of [...String(env.PATH ?? env.Path ?? '').split(delimiter), ...extra]) if (p && !seen.has(p)) { seen.add(p); out.push(p); }
+  return out.join(delimiter);
+}
+
+let nodeCache = null;
+/** The first Node 22 or newer on the PATH (never the Claude app's own binary): { bin, version, npm } or null. */
+export function findNode({ fresh = false } = {}) {
+  if (nodeCache && !fresh) return nodeCache;
+  const exe = WIN ? 'node.exe' : 'node';
+  const candidates = [];
+  // A plain Node process (Claude Code, a terminal, a test) can run itself; the Claude app's built-in one cannot.
+  if (!process.versions.electron) candidates.push(process.execPath);
+  for (const dir of toolPath().split(delimiter)) candidates.push(join(dir, exe));
+  const tried = new Set();
+  for (const bin of candidates) {
+    if (tried.has(bin) || !existsSync(bin)) continue;
+    tried.add(bin);
+    const env = { ...process.env };
+    delete env.ELECTRON_RUN_AS_NODE;
+    const r = spawnSync(bin, ['-v'], { encoding: 'utf8', timeout: 5000, env });
+    const version = String(r.stdout ?? '').trim().replace(/^v/, '');
+    if (r.status === 0 && Number(version.split('.')[0]) >= 22) {
+      const npmNext = join(dirname(bin), WIN ? 'npm.cmd' : 'npm');
+      nodeCache = { bin, version, npm: existsSync(npmNext) ? npmNext : which(WIN ? 'npm.cmd' : 'npm') };
+      return nodeCache;
+    }
+  }
+  return null;
+}
+
+export function which(name) {
+  for (const dir of toolPath().split(delimiter)) { const p = join(dir, name); if (existsSync(p)) return p; }
+  return null;
+}
+
+/** The environment a studio command runs in: the long PATH (this Node's folder first), no update nags. */
+export function toolEnv(extra = {}) {
+  const node = findNode();
+  const path = toolPath();
+  const env = { ...process.env, PATH: node ? `${dirname(node.bin)}${delimiter}${path}` : path, npm_config_update_notifier: 'false', npm_config_fund: 'false', npm_config_audit: 'false', WRANGLER_SEND_METRICS: 'false', ...extra };
+  delete env.ELECTRON_RUN_AS_NODE;
+  return env;
+}
+
+/** The studio's own pinned CLI, else this package's (a studio before its npm install). */
+export function cliOf(root) {
+  const pinned = join(root, 'node_modules', '@homie-rocks', 'studio', 'bin', 'homie-studio.mjs');
+  return existsSync(pinned) ? pinned : join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs');
+}
+export const installed = (root) => existsSync(join(root, 'node_modules', '@homie-rocks', 'studio', 'package.json')) && existsSync(join(root, 'node_modules', 'wrangler'));
+
+const jobs = new Map();
+const MAX_OUT = 4 * 1024 * 1024;
+
+/**
+ * Start one process for a studio. `json`: the command prints a JSON result on stdout (homie-studio --json), kept
+ * as job.result. `onEnd(job)` runs once when it exits.
+ */
+export function startJob({ root, label, cmd, args, env = toolEnv(), json = false, onEnd = null, keep = false }) {
+  const id = `j_${randomBytes(6).toString('hex')}`;
+  const dir = join(root, '.studio', 'mcp');
+  mkdirSync(dir, { recursive: true });
+  const log = join(dir, `${id}.log`);
+  appendFileSync(log, `$ ${[cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}\n`);
+  const child = spawn(cmd, args, { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, shell: WIN && /\.cmd$/i.test(cmd) });
+  const job = { id, label, root, args, pid: child.pid ?? null, startedAt: new Date().toISOString(), endedAt: null, code: null, out: '', err: '', log, result: null, json, keep, child };
+  let finish;
+  job.done = new Promise((r) => { finish = r; });
+  child.stdout.on('data', (d) => { if (job.out.length < MAX_OUT) job.out += d; try { appendFileSync(log, d); } catch { /* full disk: keep going */ } });
+  child.stderr.on('data', (d) => { job.err = (job.err + d).slice(-64 * 1024); try { appendFileSync(log, d); } catch { /* keep going */ } });
+  const end = (code) => {
+    if (job.endedAt) return;
+    job.code = code;
+    job.endedAt = new Date().toISOString();
+    if (json) job.result = lastJson(job.out);
+    job.child = null;
+    try { onEnd?.(job); } catch { /* the job's own result stands */ }
+    finish(job);
+  };
+  child.on('error', (error) => { job.err += `\n${error.message}`; end(127); });
+  child.on('close', (code) => end(code ?? 1));
+  jobs.set(id, job);
+  return job;
+}
+
+/** The last JSON document a command printed (homie-studio --json prints one, pretty). */
+export function lastJson(text) {
+  const s = String(text ?? '').trim();
+  if (!s) return null;
+  try { return JSON.parse(s); } catch { /* look for the last top-level object */ }
+  for (let i = s.lastIndexOf('\n{'); i >= 0; i = s.lastIndexOf('\n{', i - 1)) {
+    try { return JSON.parse(s.slice(i + 1)); } catch { /* earlier */ }
+    if (i === 0) break;
+  }
+  return null;
+}
+
+export const getJob = (id) => jobs.get(String(id ?? '')) ?? null;
+export const runningJobs = (root) => [...jobs.values()].filter((j) => !j.endedAt && (!root || j.root === root));
+
+/** Wait for a job at most `ms`; true when it ended. */
+export async function waitJob(job, ms) {
+  if (job.endedAt) return true;
+  let t;
+  const ended = await Promise.race([job.done.then(() => true), new Promise((r) => { t = setTimeout(() => r(false), ms); })]);
+  clearTimeout(t);
+  return ended;
+}
+
+/** What a person (and the model) is told about a job. */
+export function jobView(job, { lines = 12 } = {}) {
+  const text = `${job.err}\n${job.json ? '' : job.out}`.split('\n').map((l) => l.trimEnd()).filter(Boolean);
+  return {
+    job: job.id, label: job.label, state: !job.endedAt ? 'running' : job.code === 0 ? 'done' : 'failed', code: job.code,
+    startedAt: job.startedAt, endedAt: job.endedAt,
+    seconds: Math.round(((job.endedAt ? Date.parse(job.endedAt) : Date.now()) - Date.parse(job.startedAt)) / 1000),
+    tail: text.slice(-lines), log: job.log, result: job.result,
+  };
+}
+
+/** Run the studio's pinned CLI as a job: `homie-studio <args> --json`. */
+export function cliJob(root, label, args, opts = {}) {
+  const node = findNode();
+  if (!node) throw new Error('no Node.js 22 or newer on this computer: install it from https://nodejs.org/en/download (the LTS), then ask again');
+  return startJob({ root, label, cmd: node.bin, args: [cliOf(root), ...args, '--json'], json: true, ...opts });
+}
+
+/** `npm install` in a studio (its pinned toolkit and Wrangler). */
+export function installJob(root, opts = {}) {
+  const node = findNode();
+  if (!node?.npm) throw new Error('npm was not found next to Node.js on this computer: install Node.js 22 or newer from https://nodejs.org/en/download, then ask again');
+  return startJob({ root, label: 'npm install (the studio\'s pinned toolkit and Wrangler)', cmd: node.npm, args: ['install', '--no-audit', '--no-fund'], ...opts });
+}
+
+/** When the server ends (the app quit), nothing it started keeps running, except what asked to (none today). */
+export function stopAllJobs() {
+  for (const job of jobs.values()) {
+    if (job.endedAt || !job.child || job.keep) continue;
+    try { job.child.kill('SIGTERM'); } catch { /* gone */ }
+  }
+}