@homie-rocks/studio 0.19.1 → 0.19.2

package/README.md

@@ -108,14 +108,20 @@ are watched only by those they let in (NETPLAY.md section 16, site/SITE.md).
 
 ## Upgrading a studio
 
-A studio pins one version, so nothing changes until it asks. To take a newer one:
+A studio pins one version, so nothing changes until it asks. To take a newer one (`latest`, or a version):
 
 ```sh
-npx -y @homie-rocks/studio@0.18.2 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.18.2 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@latest upgrade          # what's new, and the plan; changes nothing
+npx -y @homie-rocks/studio@0.19.2 upgrade --apply  # after the person agrees (the version the plan named)
 npm install && npm run build
 ```
 
+The plan starts with **what's new** since the version the studio pins: one line per version and every upgrade note
+(anything the person has to do), read from the new version's own `CHANGELOG.md`, which ships in the package (the
+repository's [CHANGELOG.md](https://github.com/homie-rocks/homie/blob/main/CHANGELOG.md) is the same file). `--json`
+carries it as `whatsNew`. In Claude Desktop, `studio_run ["upgrade"]` runs the extension's own newer toolkit for
+this, and the studio card says what's new when a studio is behind.
+
 `upgrade` compares the studio with what this version's `new` would write for it: an AGENTS.md section, a README,
 a `.gitignore` line, a D1 migration or a package.json script it lacks is added, and one it never changed since an
 older template wrote it (`lib/template-history.json` knows every earlier version's text by a fingerprint) takes
@@ -498,6 +504,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket; `media move`: big media into it, checked by SHA-256 (every deploy runs it). |
 | `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
+| `lib/changelog.mjs`, `CHANGELOG.md` | The release history this package carries (a copy of the repository's): `upgrade`'s what's new, the studio card's, and the release notes. |
 | `lib/progress.mjs`, `lib/setup.mjs` | The progress feed (`progress …`), a build the chat opened (`progress attach`), a change as a pull request (`progress change`, `progress pr`), and `setup attach`. |
 | `lib/net.mjs`, `lib/repo.mjs` | The toolkit's own web requests: through the environment's proxy, and an honest reason when one fails. The studio's repository (`owner/name`), from its remote, never the engine's. |
 | `template/` (repository root), `scripts/template.mjs` | The public "Deploy to Cloudflare" template, generated from `new --template`. |

package/bin/homie-studio.mjs

@@ -61,7 +61,9 @@
  *   homie-studio upgrade [--apply] [--diff]
  *                                         (what this version's template adds to an existing studio: AGENTS.md
  *                                          sections, READMEs, .gitignore lines, the pin; changes nothing until
- *                                          --apply, and never a file or section the studio changed)
+ *                                          --apply, and never a file or section the studio changed. It starts
+ *                                          with what's new since the studio's version, from this package's
+ *                                          CHANGELOG.md)
  *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>] [--url <site>]
  *   homie-studio stats key [--hours 1]    (a read key for the Homie MCP tool studio_stats)
  *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
@@ -170,6 +172,7 @@ import { DEFAULT_GOAL, perfCompare, perfRun, perfSizes } from '../lib/perf.mjs';
 import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
+import { whatsNewLines } from '../lib/changelog.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
@@ -439,7 +442,9 @@ function print(result) {
       lines.push(result.applied
         ? `${result.studio} is on the @homie-rocks/studio ${result.to} template now (${list.length} change${list.length === 1 ? '' : 's'}).`
         : list.length ? `${result.studio}: what the @homie-rocks/studio ${result.to} template adds (from ${result.from ?? 'an older version'}). Nothing is changed until --apply.` : `${result.studio} has everything the @homie-rocks/studio ${result.to} template writes.`);
-      if (list.length) lines.push('');
+      // What the versions since the studio's own brought, from this package's CHANGELOG.md (also after --apply).
+      if (result.whatsNew) lines.push('', ...whatsNewLines(result.whatsNew, { source: `@homie-rocks/studio ${result.to}'s CHANGELOG.md` }));
+      if (list.length) lines.push('', result.applied ? 'Done:' : 'The changes:');
       for (const c of list) {
         lines.push(`  ${mark[c.kind] ?? '·'} ${c.file.padEnd(18)} ${c.what}${c.kind === 'add-section' && (c.after || c.before) ? ` (${c.after ? `after "${c.after}"` : `before "${c.before}"`})` : ''}`);
         if (result.applied) continue;

package/lib/changelog.mjs

@@ -0,0 +1,204 @@
+/**
+ * CHANGELOG.md: what changed in each @homie-rocks/studio version, and the Homie plugin's version beside it.
+ *
+ * The repository keeps it at its root; the package carries an identical copy (packages/studio/CHANGELOG.md, in
+ * `files`, kept the same by `node scripts/changelog.mjs --sync`), so an installed toolkit knows its own history with
+ * no network. Read by:
+ *   - `homie-studio upgrade`: "What's new since <the pinned version>", from the NEW version's own copy (the one
+ *     `npx -y @homie-rocks/studio@<new> upgrade` runs);
+ *   - the studio card (lib/mcp-tools.mjs), when a studio pins an older toolkit than the one answering;
+ *   - scripts/changelog.mjs: CI's check, and the GitHub release notes the publish workflow writes.
+ *
+ * The shape (Keep a Changelog, https://keepachangelog.com/en/1.1.0/), newest first:
+ *
+ *   ## [0.19.2] - 2026-10-02                              one section per studio version
+ *
+ *   **Plugin 0.20.2** · [#29](…) · [release-…](…)          the meta line: the plugin's version (", then 0.20.3" when
+ *                                                          the plugin had a release of its own after it), the pull
+ *                                                          requests and the tag
+ *   One sentence: what this version is.                    the summary "What's new" prints
+ *
+ *   ### Added | ### Changed | ### Fixed | ### Upgrade notes   bullets ("- " and lines indented under them)
+ *
+ *   [0.19.2]: https://…                                    link definitions, at the end of the file
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export const CHANGELOG_FILE = fileURLToPath(new URL('../CHANGELOG.md', import.meta.url));
+export const GROUPS = Object.freeze(['Added', 'Changed', 'Fixed', 'Upgrade notes']);
+export const REPO_URL = 'https://github.com/homie-rocks/homie';
+
+const VERSION = /^\d+\.\d+\.\d+$/;
+const HEADING = /^## \[?(\d+\.\d+\.\d+)\]?(?:\s+-\s+(\d{4}-\d{2}-\d{2}))?\s*$/;
+const LINK_DEF = /^\[[^\]]+\]:\s+\S+/;
+
+/** -1, 0 or 1, as a sorts before, with or after b (x.y.z only; anything else sorts first). */
+export function compareVersions(a, b) {
+  const x = VERSION.test(String(a)) ? String(a).split('.').map(Number) : [-1, -1, -1];
+  const y = VERSION.test(String(b)) ? String(b).split('.').map(Number) : [-1, -1, -1];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+
+/** Markdown as one line of plain words: links keep their text, code and bold lose their marks. */
+export function plain(markdown) {
+  return String(markdown ?? '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** The paragraphs and bullets of a run of lines: paragraphs split on blank lines, a bullet takes the lines indented under it. */
+function blocks(lines) {
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    if (!line.trim()) { cur = null; continue; }
+    if (/^- /.test(line)) { cur = { kind: 'bullet', text: line.slice(2).trim() }; out.push(cur); continue; }
+    if (cur && (cur.kind === 'paragraph' || /^\s+\S/.test(line))) { cur.text += ` ${line.trim()}`; continue; }
+    cur = { kind: 'paragraph', text: line.trim() }; out.push(cur);
+  }
+  return out;
+}
+
+/**
+ * The file as its sections. Each: { version, date, plugin, plugins, meta, summary, notes, groups, body, line }.
+ * `body` is the section's own Markdown (no heading, no link definitions), what a release's notes are made of.
+ * `problems` lists what does not follow the shape (CI fails on them); a heading that is not a version (an
+ * "Unreleased" one, say) ends the section before it and is otherwise left alone.
+ */
+export function parseChangelog(text) {
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const versions = [];
+  const problems = [];
+  let cur = null;
+  const close = () => {
+    if (!cur) return;
+    while (cur.lines.length && !cur.lines[cur.lines.length - 1].trim()) cur.lines.pop();
+    const { lines: own, ...section } = cur;
+    section.body = own.join('\n').replace(/^\n+/, '');
+    // Before the first ### heading: the meta line, the summary and any notes; then the groups.
+    const groups = {};
+    let head = [];
+    let group = null;
+    for (const line of own) {
+      const g = /^### (.+?)\s*$/.exec(line);
+      if (g) { group = g[1]; groups[group] = []; continue; }
+      if (group === null) head.push(line); else groups[group].push(line);
+    }
+    const paras = blocks(head).map((b) => b.text);
+    const metaAt = paras.findIndex((p) => /^\*\*Plugin /.test(p));
+    section.meta = metaAt >= 0 ? paras[metaAt] : null;
+    const rest = paras.filter((_, i) => i !== metaAt);
+    section.summary = rest[0] ?? null;
+    section.notes = rest.slice(1);
+    section.plugins = section.meta ? [...(/^\*\*Plugin ([^*]+)\*\*/.exec(section.meta)?.[1] ?? '').matchAll(/\d+\.\d+\.\d+/g)].map((m) => m[0]) : [];
+    section.plugin = section.plugins.at(-1) ?? null;
+    section.groups = Object.fromEntries(Object.entries(groups).map(([k, v]) => [k, blocks(v).filter((b) => b.kind === 'bullet').map((b) => b.text)]));
+    const where = `CHANGELOG.md line ${section.line} (## [${section.version}])`;
+    if (!section.date) problems.push(`${where}: the heading has no date; write it as "## [${section.version}] - YYYY-MM-DD"`);
+    if (!section.meta) problems.push(`${where}: no "**Plugin x.y.z** · …" line under the heading`);
+    else if (!section.plugin) problems.push(`${where}: the Plugin line names no version`);
+    if (!section.summary) problems.push(`${where}: no one-sentence summary under the Plugin line`);
+    for (const k of Object.keys(section.groups)) if (!GROUPS.includes(k)) problems.push(`${where}: "### ${k}" is not one of ${GROUPS.map((g) => `"### ${g}"`).join(', ')}`);
+    if (!Object.values(section.groups).some((b) => b.length)) problems.push(`${where}: no "- " entries under ${GROUPS.map((g) => `"### ${g}"`).join(', ')}`);
+    versions.push(section);
+    cur = null;
+  };
+  lines.forEach((line, i) => {
+    if (/^## /.test(line)) {
+      close();
+      const m = HEADING.exec(line);
+      if (m) cur = { version: m[1], date: m[2] ?? null, heading: line, line: i + 1, lines: [] };
+      return;
+    }
+    if (cur && LINK_DEF.test(line)) { close(); return; }
+    if (cur) cur.lines.push(line);
+  });
+  close();
+  for (let i = 1; i < versions.length; i++) {
+    if (compareVersions(versions[i - 1].version, versions[i].version) <= 0) problems.push(`CHANGELOG.md line ${versions[i].line}: ${versions[i].version} comes after ${versions[i - 1].version}; newest first, each version once`);
+  }
+  return { versions, problems };
+}
+
+/** The package's own CHANGELOG.md, parsed; null when it is missing (a checkout from before 0.19.2) or unreadable. */
+export function readChangelog(file = CHANGELOG_FILE) {
+  try { return { file, ...parseChangelog(readFileSync(file, 'utf8')) }; } catch { return null; }
+}
+
+/** One version's section, or null. */
+export function sectionOf(changelog, version) {
+  return changelog?.versions?.find((s) => s.version === version) ?? null;
+}
+
+/**
+ * What changed after `from` up to and including `to`, newest first: each version's summary and its upgrade notes
+ * (what the person may have to do). null when there is nothing to say (no pin known, no changelog, or not older).
+ */
+export function whatsNew(from, to, { changelog = readChangelog() } = {}) {
+  if (!VERSION.test(String(from ?? '')) || !VERSION.test(String(to ?? '')) || compareVersions(from, to) >= 0 || !changelog) return null;
+  const versions = changelog.versions
+    .filter((s) => compareVersions(s.version, from) > 0 && compareVersions(s.version, to) <= 0)
+    .map((s) => ({ version: s.version, date: s.date, plugin: s.plugin, summary: plain(s.summary), upgrade: (s.groups['Upgrade notes'] ?? []).map(plain) }));
+  return versions.length ? { from, to, versions } : null;
+}
+
+/**
+ * whatsNew as a few lines for a terminal or a card's text: one line per version (the newest `maxVersions`), then the
+ * upgrade notes of every version in the range (the first `maxNotes`), each cut to `width`.
+ */
+export function whatsNewLines(news, { width = 110, maxVersions = 8, maxNotes = 8, source = null } = {}) {
+  if (!news?.versions?.length) return [];
+  const cut = (s, n) => (s.length > n ? `${s.slice(0, n - 1).replace(/\s+\S*$/, '')}…` : s);
+  const shown = news.versions.slice(0, maxVersions);
+  const pad = Math.max(...news.versions.map((v) => v.version.length));
+  const lines = [`What's new since ${news.from}${source ? ` (${source})` : ''}:`];
+  for (const v of shown) lines.push(`  ${v.version.padEnd(pad)}  ${cut(v.summary ?? '', width - pad - 4)}`);
+  const more = news.versions.length - shown.length;
+  if (more) lines.push(`  … and ${more} earlier version${more === 1 ? '' : 's'} (CHANGELOG.md has every one)`);
+  const notes = news.versions.flatMap((v) => v.upgrade.map((u) => [v.version, u]));
+  if (notes.length) {
+    lines.push('Upgrade notes (anything to do yourself):');
+    for (const [v, u] of notes.slice(0, maxNotes)) lines.push(`  ${v.padEnd(pad)}  ${cut(u, width - pad - 4)}`);
+    if (notes.length > maxNotes) lines.push(`  … and ${notes.length - maxNotes} more (--json has every one)`);
+  }
+  return lines;
+}
+
+/**
+ * Markdown with each paragraph and each "- " entry on one line. CHANGELOG.md wraps them at 120 columns, which a
+ * file ignores; GitHub's release notes render every line end as a break, so a wrapped entry would break mid-sentence.
+ */
+export function unwrap(markdown) {
+  const out = [];
+  for (const line of String(markdown ?? '').split('\n')) {
+    const prev = out.length ? out[out.length - 1] : '';
+    const starts = !line.trim() || /^(#{1,6} |- |\* |\d+\. |---\s*$|\|)/.test(line.trim()) && !/^\s+/.test(line);
+    const continues = prev.trim() && !/^(#{1,6} |---\s*$|\|)/.test(prev.trim());
+    if (!starts && continues) out[out.length - 1] = `${prev.replace(/\s+$/, '')} ${line.trim()}`;
+    else out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * A GitHub release's notes: the version's section as it is in CHANGELOG.md (each paragraph and entry on one line),
+ * then the Desktop extension's line (its .mcpb is attached to the release) and where every version is.
+ */
+export function releaseNotes(changelog, version, { tag = null, repo = REPO_URL } = {}) {
+  const s = sectionOf(changelog, version);
+  if (!s) return null;
+  return [
+    unwrap(s.body),
+    '',
+    '---',
+    '',
+    `Homie for Claude Desktop ${version}: [desktop/README.md](${repo}/blob/${tag ?? 'main'}/desktop/README.md) says how to install it (\`homie-studio-${version}.mcpb\` below).`,
+    `Every version: [CHANGELOG.md](${repo}/blob/main/CHANGELOG.md).`,
+    '',
+  ].join('\n');
+}

package/lib/jobs.mjs

@@ -159,10 +159,11 @@ export function jobView(job, { lines = 12 } = {}) {
 }
 
 /** Run the studio's pinned CLI as a job: `homie-studio <args> --json`. */
-export function cliJob(root, label, args, opts = {}) {
+export function cliJob(root, label, args, { cli = null, ...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 });
+  // `cli`: another homie-studio than the studio's pinned one (this package's, for an upgrade to it).
+  return startJob({ root, label, cmd: node.bin, args: [cli ?? cliOf(root), ...args, '--json'], json: true, ...opts });
 }
 
 /** `npm install` in a studio (its pinned toolkit and Wrangler). */

package/lib/mcp-tools.mjs

@@ -28,8 +28,10 @@ import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs,
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
-import { GAME_ID, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
+import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
+import { pinnedVersion } from './upgrade.mjs';
 import { AgentSeat } from './agent-seat.mjs';
 
 export const UI = Object.freeze({
@@ -120,8 +122,8 @@ const ok = (text, structured, extra = {}) => ({ content: [{ type: 'text', text }
 const fail = (text, structured) => ({ content: [{ type: 'text', text }], ...(structured ? { structuredContent: structured } : {}), isError: true });
 
 /** Run the pinned CLI and wait a while; { ended, job, result }. */
-async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null } = {}) {
-  const job = cliJob(root, label, args, { onEnd });
+async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null, cli: bin = null } = {}) {
+  const job = cliJob(root, label, args, { onEnd, ...(bin ? { cli: bin } : {}) });
   const ended = await waitJob(job, wait);
   return { ended, job, result: job.result };
 }
@@ -245,6 +247,18 @@ function published(root, kind) {
   } catch { return []; }
 }
 
+/**
+ * When the studio pins an older @homie-rocks/studio than this one: the pin, this version, and what's new between them
+ * (this package's own CHANGELOG.md). null when it is on this version, a newer one, or a link to a checkout.
+ */
+export function behindOf(root) {
+  let pkg = null;
+  try { pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); } catch { return null; }
+  const pinned = pinnedVersion(pkg?.devDependencies?.['@homie-rocks/studio'] ?? pkg?.dependencies?.['@homie-rocks/studio']);
+  if (!pinned || compareVersions(pinned, STUDIO_VERSION) >= 0) return null;
+  return { pinned, here: STUDIO_VERSION, whatsNew: whatsNew(pinned, STUDIO_VERSION) };
+}
+
 async function studioCard(ctx, root) {
   const studio = readStudio(root);
   const dev = devOf(root);
@@ -282,6 +296,8 @@ async function studioCard(ctx, root) {
     games, songs: published(root, 'music'), videos: published(root, 'videos'), posts,
     dev: dev ? { url: dev.url } : null, site: live, rooms, demo, installed: installed(root),
   };
+  const behind = behindOf(root);
+  if (behind) data.behind = { ...behind, whatsNew: behind.whatsNew ? { ...behind.whatsNew, versions: behind.whatsNew.versions.slice(0, 6).map(({ version, summary, upgrade }) => ({ version, summary, upgrade: upgrade.slice(0, 2) })) } : null };
   const text = [
     `${studio.name} (${root})`,
     games.length ? `Games: ${games.map((g) => `${g.name} (${g.id}${live ? (g.live ? ', live' : ', not deployed yet') : ''})`).join(', ')}` : 'No game yet: its home page says "First game coming soon".',
@@ -289,6 +305,10 @@ async function studioCard(ctx, root) {
     live ? `Live: ${live}/` : 'Not online yet (studio_deploy).',
     ...(rooms.length ? [`Live rooms: ${rooms.map((r) => `${r.game} ${r.room} (${r.players})`).join(', ')}`] : []),
     ...(demo ? [`See a working game meanwhile: ${demo.name}, ${demo.play}`] : []),
+    ...(behind ? [
+      `Toolkit: this studio pins @homie-rocks/studio ${behind.pinned}; this Homie is ${behind.here}. Tell the person what is new (below) and offer the upgrade: studio_run { "args": ["upgrade"] } shows the plan and changes nothing; with their yes, ["upgrade","--apply"], then studio_install.`,
+      ...whatsNewLines(behind.whatsNew, { maxVersions: 6, maxNotes: 6 }),
+    ] : []),
   ].join('\n');
   return ok(text, data);
 }
@@ -948,7 +968,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_run', title: 'Run a studio command',
-      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job.',
+      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
       inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' }, description: 'The command\'s words after `homie-studio`' }, ...STUDIO_ARG }, required: ['args'] },
       annotations: { title: 'Run a studio command', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
@@ -959,7 +979,9 @@ export function toolDefs(ctx, avail = {}) {
         if (refused) return fail(`not here: ${refused}`);
         if (!['help', 'version', 'setup', 'doctor', 'demo', 'starters', 'progress', 'codex', 'games', 'status'].includes(args[0])) { const need = needsInstall(ctx, root); if (need) return need; }
         if (args[0] === 'game' && args[1] === 'new') ctx.note(root).demo = true;
-        const r = await cli(ctx, root, `homie-studio ${args.slice(0, 3).join(' ')}`, args);
+        // The upgrade is the newer toolkit's to make: the studio's own pinned copy knows nothing newer than itself.
+        const own = args[0] === 'upgrade' && behindOf(root) ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {};
+        const r = await cli(ctx, root, `homie-studio ${args.slice(0, 3).join(' ')}`, args, own);
         if (!r.ended) return stillRunning(r.job, `homie-studio ${args.slice(0, 2).join(' ')}`);
         const text = r.result ? JSON.stringify(r.result, null, 1).slice(0, 12_000) : jobView(r.job, { lines: 40 }).tail.join('\n');
         return r.job.code === 0 ? ok(text, { kind: 'run', args, result: r.result }) : fail(`homie-studio ${args.join(' ')}: ${whyOf(r.job)}`, { kind: 'run', args, result: r.result });

package/lib/template-history.json

@@ -813,6 +813,43 @@
      }
     }
    }
+  },
+  "0.19.2": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8dc97df0d77e655e",
+     "## Commands (all through the pinned CLI in node_modules)": "a06ab13fc385ab25",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "677ee39dc13485e0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/upgrade.mjs

@@ -25,11 +25,16 @@
  * Media (0.18.0): the plan also says which songs and videos are big media (over studio.json media.r2Over, 1 MiB
  * unless set, or left out of git), what is in the studio's R2 already, and the step that moves the rest
  * (`media move`, which every deploy of a studio with storage also runs). Upgrade itself never moves a file.
+ *
+ * What's new (0.19.2): the plan and the applied result carry `whatsNew`, every version after the one the studio
+ * was on up to this one, each with its one-line summary and its upgrade notes, read from THIS package's own
+ * CHANGELOG.md (lib/changelog.mjs): the version being moved to says what it brings, with no network.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
+import { whatsNew } from './changelog.mjs';
 import { R2_COST, mediaPlan, r2OverOf, sizeOf } from './media.mjs';
 import { studioFiles } from './scaffold.mjs';
 import { readStudio } from './studio.mjs';
@@ -243,12 +248,15 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
   const git = spawnSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8' });
   const dirty = git.status === 0 ? git.stdout.split('\n').filter(Boolean).length : null;
   const media = mediaNote(root, studio);
+  const news = whatsNew(from, STUDIO_VERSION);
   return {
     ok: true, command: 'upgrade', applied: false, root, studio: name, from, to: STUDIO_VERSION,
+    ...(news ? { whatsNew: news } : {}),
     changes, kept,
     ...(media ? { media } : {}),
     ...(dirty ? { uncommitted: dirty } : {}),
-    next: changes.length ? ['npx --no-install homie-studio upgrade --apply   (after the person agrees)'] : [],
+    // A plan that moves the pin is this (newer) toolkit's to apply: the studio's own older copy knows nothing newer.
+    next: changes.length ? [`${changes.some((c) => c.kind === 'pin') ? `npx -y @homie-rocks/studio@${STUDIO_VERSION} upgrade --apply` : 'npx --no-install homie-studio upgrade --apply'}   (after the person agrees)`] : [],
   };
 }
 

package/mcp/ui/card.css

@@ -63,6 +63,8 @@ ol.list,ul.list{list-style:none;margin:0;padding:0;display:grid;gap:6px}
 .game b{font-size:14px}.game span{font-size:12.5px;color:var(--c-fg2)}
 .soon{padding:14px;border-radius:var(--r-md);background:linear-gradient(135deg,color-mix(in srgb,var(--accent) 18%,var(--c-bg2)),var(--c-bg2));display:grid;gap:6px}
 .soon b{font-size:16px}
+.news{margin:12px 0 0;padding:12px 14px;border-radius:var(--r-md);background:var(--c-bg2);display:grid;gap:6px;font-size:13px;color:var(--c-fg2)}
+.news b{color:var(--c-fg);font-size:14px}.news code{font-weight:600;color:var(--c-fg);margin-right:2px}.news .fine{margin:2px 0 0}
 .stats{display:flex;flex-wrap:wrap;gap:6px 16px;margin:4px 0 6px;color:var(--c-fg2);font-size:13px}.stats b{color:var(--c-fg)}
 .log{margin:10px 0 0;padding:8px 10px;border-radius:var(--r-md);background:var(--c-bg2);font:12px/1.5 var(--f-mono);color:var(--c-fg2);white-space:pre-wrap;overflow-wrap:anywhere}
 .frame{width:100%;height:620px;border:0;border-radius:var(--r-md);background:var(--c-bg2);display:block}

package/mcp/ui/studio.js

@@ -1,5 +1,5 @@
 /* The studio card: its games with Play (on this computer and live), songs, videos and posts, where it runs, its
- * live rooms, and a live game to try while it has none. */
+ * live rooms, a live game to try while it has none, and what's new when its toolkit is older than this Homie. */
 (function () {
   var C = Card;
   function initials(name) { return String(name || '?').split(/\s+/).filter(Boolean).slice(0, 2).map(function (w) { return w[0]; }).join('').toUpperCase(); }
@@ -28,6 +28,14 @@
       card.appendChild(soon);
     }
     if ((sc.rooms || []).length) card.appendChild(C.el('p', 'fine', 'Playing now: ' + sc.rooms.map(function (r) { return r.game + ' (' + r.players + ')'; }).join(', ')));
+    // A studio on an older toolkit than this Homie: what's new since (this package's CHANGELOG.md), and the words to ask.
+    if (sc.behind) {
+      var news = C.add(C.el('div', 'news'), C.el('b', '', 'New in Homie since ' + sc.behind.pinned));
+      ((sc.behind.whatsNew && sc.behind.whatsNew.versions) || []).slice(0, 3).forEach(function (v) { news.appendChild(C.add(C.el('span'), C.el('code', '', v.version), C.el('span', '', ' ' + v.summary))); });
+      news.appendChild(C.el('span', 'fine', 'This studio is on ' + sc.behind.pinned + ', and ' + sc.behind.here + ' is here. Say \u201cUpgrade my studio\u201d to see what changes; nothing does until you agree.'));
+      card.appendChild(news);
+      C.tell('behind', sc.name + ' pins @homie-rocks/studio ' + sc.behind.pinned + ' and this Homie is ' + sc.behind.here + ': offer the upgrade (studio_run ["upgrade"] shows what is new and the plan, and changes nothing).');
+    }
     var foot = C.el('div', 'foot');
     foot.appendChild(C.el('span', 'when', sc.site ? sc.site.replace(/^https?:\/\//, '') : sc.dev ? sc.dev.url.replace(/^https?:\/\//, '') : 'Not online yet'));
     var acts = C.el('div', 'actions');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,6 +50,7 @@
     "media/",
     "site/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE"
   ],

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.19.1';
+export const STUDIO_VERSION_TAG = '0.19.2';