@homie-rocks/studio 0.10.0 → 0.11.0

package/README.md

@@ -72,8 +72,8 @@ site. A game made with Homie's arcade controls that knocks for a Homie box (`/__
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.10.0 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.10.0 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.11.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.11.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -113,6 +113,60 @@ npx homie-studio stats share on                         # tell the directory "pl
 Each key is minted on the owner's computer; only its SHA-256 goes into D1, through the
 studio's own Cloudflare login. `worker/stats.mjs` says exactly what is counted.
 
+## Setup status
+
+```sh
+npx -y @homie-rocks/studio@0.11.0 setup status --connector yes   # before a studio exists
+npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
+```
+
+One checklist of what this computer and the person's accounts have for a studio: Node.js, the Homie
+connector (the AI says whether its Homie tools are there; the directory is reached), Cloudflare (signed in
+with the studio's own Wrangler, and the account's email verified: a deploy that went through proves it, a
+deploy refused for it is remembered), Chrome for the checks, ffmpeg, and the optional GitHub, ElevenLabs and
+fal (and, in Claude Code, the status line). Each row is green, missing or "do this now", says what it
+unlocks, and gives the exact fix: a command the AI runs or a page the person taps. It only reads, answers in
+seconds, and never prints a key, a token or an account's name. A studio the Claude app's setup card made
+(`setup attach`) counts as connected to Cloudflare and GitHub there. `--json` gives the rows.
+
+## The Game Codex
+
+`games/<id>/CODEX.md` is a game's plan: Markdown with a small frontmatter for its look (palette, fonts, a
+cover, pixel art) and a few conventions that become cards (`### Name` with a picture, `` `M-01` `` id and tag
+chips, an italic subtitle and `**Key:** value` stats), tables, checklists, a dated decision log and open
+questions (`lib/codex.mjs` has the whole format).
+
+```sh
+npx homie-studio codex new crown-thief          # every section, in the studio's colours
+npx homie-studio codex crown-thief --open       # .studio/codex/crown-thief.html, in the browser
+npx homie-studio codex crown-thief --artifact   # one self-contained page to publish as a Claude artifact
+npx homie-studio codex link crown-thief         # a one-time link to the site's private copy
+```
+
+The page has a tab per section and a **Build status** tab from the game's progress feed; the local copy
+redraws itself whenever the feed changes and refreshes in the browser while a build runs. `npm run build`
+puts each game's codex on the site at `/_studio/codex/<id>/`, served only to the studio's owner (the same
+one-time sign-in as the stats page), never listed or indexed. Text is escaped and the page runs only its own
+script (the site allows it by its hash); pictures and fonts come only from inside the studio and are
+embedded, so it loads nothing but Google Fonts. CODEX.md is never in a game's remix source or among a
+static game's served files.
+
+## The Claude Code status line
+
+```sh
+npx homie-studio statusline --install    # .claude/settings.local.json: this person, this studio
+npx homie-studio statusline --install --project ..   # Claude Code started in the folder above the studio
+npx homie-studio statusline --remove
+```
+
+One line under the prompt, from the current build's feed: `▶ Crown Thief · Checks ▰▰▰▰▰▰▱▱▱▱ 62% · 3/5 checks
+· $0.40 of $2.00`; the studio's name, dimmed, when nothing runs; a finished build's result for ten minutes.
+Claude Code runs `bin/statusline.mjs` with the session as JSON on stdin (it reads only the studio's progress
+files, in about 40 ms) and, with the 5 s `refreshInterval` it sets, keeps it moving while a long check runs.
+It never replaces a status line the person already has (`--replace` puts this one in for this studio only).
+Plugins cannot set a status line, so it is always the person's yes. Codex CLI's status line takes only its
+own built-in items, so there the codex page is the progress view.
+
 ## A build the person can watch (the progress feed)
 
 A build of a game, song or video can keep a small progress feed, so the person follows it

package/bin/homie-studio.mjs

@@ -62,6 +62,24 @@
  *
  *   homie-studio setup attach <hs_…>      (this repository is the studio the Claude app's setup card is making: say so, once,
  *                                          learn its live address, and give a template copy its real name)
+ *   homie-studio setup status [--connector yes|no]   (also: homie-studio doctor)
+ *                                         what this computer and the person's accounts have for a studio: Node, the Homie
+ *                                         connector, Cloudflare (signed in, email verified), Chrome, ffmpeg, GitHub,
+ *                                         ElevenLabs, fal; green, missing or "do this now", what each unlocks and its
+ *                                         exact fix. Read-only and safe any time, inside a studio or before one exists.
+ *
+ *   homie-studio codex new <id>           games/<id>/CODEX.md: the Game Codex, every section, in the game's colours
+ *   homie-studio codex <id> [--artifact] [--open]
+ *                                         the codex as a page in the game's own look (.studio/codex/<id>.html; it redraws
+ *                                         itself as the build's progress changes); --artifact: a copy to publish as a
+ *                                         Claude artifact; --open: open it in this computer's browser
+ *   homie-studio codex link <id>          a one-time link to the codex on the live site (a private page for the owner)
+ *
+ *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
+ *   homie-studio statusline --install [--project <folder>]
+ *                                         turn it on in Claude Code for this studio (.claude/settings.local.json);
+ *                                         --project: the folder Claude Code was started in, when that is above the
+ *                                         studio; --remove turns it off; --replace when another status line is set
  *
  * Every command prints a few lines for a person; --json prints the result.
  */
@@ -84,10 +102,13 @@ import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, star
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
+import { formatStatus, setupStatus } from '../lib/doctor.mjs';
+import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
+import { installStatusLine, statusLine } from '../lib/statusline.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh'];
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -128,6 +149,7 @@ function print(result) {
       for (const m of result.mediaSkipped ?? []) lines.push(`  left out: ${m.kind}/${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
       for (const m of result.postsSkipped ?? []) lines.push(`  left out: posts/${m.post}: ${m.why}`);
       for (const m of result.siteSkipped ?? []) lines.push(`  left out: ${m.what}: ${m.why}`);
+      if (result.codexes?.length) lines.push(`Game Codex (the owner's private pages; codex link <id> opens one): ${result.codexes.map((x) => `/_studio/codex/${x}/`).join(', ')}`);
       break;
     case 'media list':
       for (const kind of ['music', 'videos']) {
@@ -197,6 +219,27 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'setup status':
+      lines.push(formatStatus(result));
+      break;
+    case 'codex':
+      lines.push(`The Game Codex for ${result.title}: ${result.file}${result.opened ? ' (opened in the browser)' : ''}`,
+        `  tabs: ${result.sections.map((x) => x.title).join(' · ')} · Build status${result.build ? ` (${result.build.state}, ${result.build.percent}%)` : ''}`,
+        ...(result.missing.length ? [`  not decided yet: ${result.missing.join(', ')}`] : ['  every section has something in it']),
+        `  open questions: ${result.openQuestions}`,
+        ...result.warnings.map((w) => `  warning: ${w}`),
+        result.mode === 'artifact' ? '  publish this file as an artifact where your app can (Claude: the Artifact tool); it is one self-contained page' : '  on the site, for the owner only, after the next deploy: npx --no-install homie-studio codex link ' + result.id);
+      break;
+    case 'codex new':
+      lines.push(`Wrote ${result.file}.`, ...result.next.map((n) => `  next: ${n}`));
+      break;
+    case 'codex link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'statusline install':
+    case 'statusline remove':
+      lines.push(result.message);
+      break;
     case 'setup attach':
       lines.push(result.message, ...(result.site ? [`  live site: ${result.site}`] : []), ...(result.renamed?.length ? ['  changed (commit these on a branch):', ...result.renamed.map((f) => `    ${f}`)] : []), ...(result.next ?? []).map((n) => `  next: ${n}`));
       break;
@@ -282,7 +325,16 @@ async function main() {
   if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
   if (cmd === 'chrome' && sub === 'install') return installChrome({ log, fresh: flags.has('fresh') });
   if (cmd === 'chrome') { const chrome = findChrome(); return chrome ? { ok: true, command: 'chrome', chrome, args: chromeArgs() } : { ok: false, command: 'chrome', why: noChrome() }; }
+  if ((cmd === 'setup' && sub === 'status') || cmd === 'doctor') return setupStatus({ connector: flags.get('connector') ?? null, homie: flags.get('homie') ?? null });
+  if (cmd === 'statusline' && !flags.has('install') && !flags.has('remove')) {
+    const line = statusLine({ columns: Number(process.env.COLUMNS) || 100, color: !process.env.NO_COLOR && !asJson && process.stdout.isTTY });
+    if (asJson) return { ok: true, command: 'statusline', line };
+    if (line) process.stdout.write(`${line}\n`);
+    return { ok: true, command: 'help' };
+  }
   const root = requireStudio();
+  if (cmd === 'statusline') return installStatusLine(root, { remove: flags.has('remove'), replace: flags.has('replace'), project: flags.get('project') ?? null });
+  if (cmd === 'codex') return codexCommand(root, sub);
   if (cmd === 'progress') return progressCommand(root, sub);
   if (cmd === 'setup' && sub === 'attach') return setupAttach(root, positional[2], { homie: flags.get('homie') });
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
@@ -351,6 +403,28 @@ async function main() {
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
 
+/** `homie-studio codex …` (lib/codex.mjs): the Game Codex of one game. */
+function codexCommand(root, sub) {
+  const games = listGames(root);
+  if (sub === 'new') return newCodex(root, positional[2] ?? (games.length === 1 ? games[0].id : undefined));
+  if (sub === 'link') {
+    const id = positional[2] ?? (games.length === 1 ? games[0].id : null);
+    if (!id || !games.some((g) => g.id === id)) return { ok: false, command: 'codex link', why: 'name the game: homie-studio codex link <id>' };
+    const r = statsLink(root, { url: flags.get('url') });
+    if (!r.ok) return { ...r, command: 'codex link' };
+    return { ...r, command: 'codex link', link: `${r.link}&to=${encodeURIComponent(codexTarget(id))}`, use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, opens the codex, and keeps that browser signed in to the studio\'s private pages (the codex and the stats) for 30 days. Do not post it anywhere.' };
+  }
+  const id = sub ?? (games.length === 1 ? games[0].id : null);
+  if (!id) return { ok: false, command: 'codex', why: `name the game: homie-studio codex <id> (${games.map((g) => g.id).join(', ') || 'no games yet'})` };
+  let r;
+  try { r = writeCodexPage(root, id, { mode: flags.has('artifact') ? 'artifact' : 'file' }); } catch (error) { return { ok: false, command: 'codex', why: error.message }; }
+  if (flags.has('open')) {
+    const opener = process.platform === 'darwin' ? ['open', [r.path]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', r.path]] : ['xdg-open', [r.path]];
+    r.opened = spawnSync(opener[0], opener[1], { stdio: 'ignore', timeout: 10_000 }).status === 0;
+  }
+  return r;
+}
+
 /*
  * THE PROGRESS FEED (lib/progress.mjs). A command that is a stage of the open build (build, check, port check,
  * deploy) says so: the stage runs, then is done or failed with one line; a check's steps go green as they pass; a

package/bin/statusline.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * The Claude Code status line for a Homie studio (lib/statusline.mjs). Claude Code runs it with the session as
+ * JSON on stdin and shows what it prints; it must be quick and must never fail loudly, so it reads only the
+ * studio's own progress files and prints nothing at all when anything goes wrong.
+ *
+ *   echo '{"workspace":{"current_dir":"."}}' | node node_modules/@homie-rocks/studio/bin/statusline.mjs
+ */
+import { statusLine } from '../lib/statusline.mjs';
+
+let input = '';
+let printed = false;
+function print() {
+  if (printed) return;
+  printed = true;
+  let dirs = [process.cwd()];
+  try {
+    const session = JSON.parse(input || '{}');
+    dirs = [session?.workspace?.current_dir, session?.workspace?.project_dir, session?.cwd, process.cwd()].filter((d) => typeof d === 'string' && d);
+  } catch { /* no session: this folder */ }
+  // `--studio <folder>`: set up in the folder above the studio, the setting names the studio.
+  const named = process.argv.indexOf('--studio');
+  if (named > 0 && process.argv[named + 1]) dirs.push(process.argv[named + 1]);
+  try {
+    const columns = Number(process.env.COLUMNS) || 100;
+    const color = !process.env.NO_COLOR;
+    for (const dir of dirs) {
+      const line = statusLine({ dir, columns, color });
+      if (line) { process.stdout.write(`${line}\n`); break; }
+    }
+  } catch { /* quiet: a status line never shows a stack */ }
+  // A caller that never closes stdin must not keep this process alive.
+  if (!process.stdin.isTTY) process.stdin.destroy();
+}
+if (process.stdin.isTTY) print();
+else {
+  const timer = setTimeout(print, 400);
+  process.stdin.on('data', (d) => { input += d; });
+  process.stdin.on('end', () => { clearTimeout(timer); print(); });
+  process.stdin.on('error', () => { clearTimeout(timer); print(); });
+}

package/lib/build.mjs

@@ -10,6 +10,8 @@
  *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
  *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
  *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
+ *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
+ *                                          the studio's owner (worker/stats-page.mjs), never listed or indexed
  *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
  *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
  *
@@ -25,6 +27,7 @@ import { spawnSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
+import { buildCodexPages } from './codex.mjs';
 import { buildMedia } from './media.mjs';
 import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
@@ -33,7 +36,7 @@ import { STUDIO_VERSION } from './version.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
-const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md']);
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md']);
 const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
 
 /** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
@@ -67,7 +70,7 @@ export function sourceOf(dir, id) {
   let total = 0;
   const walk = (rel) => {
     for (const entry of readdirSync(join(dir, rel), { withFileTypes: true })) {
-      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name)) continue;
+      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name) || (!rel && entry.name === 'CODEX.md')) continue;
       const path = rel ? `${rel}/${entry.name}` : entry.name;
       if (entry.isDirectory()) walk(path);
       else if (TEXT.test(entry.name)) {
@@ -222,6 +225,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   });
   const { posts, skipped: postsSkipped } = readPosts(root, { games: rows, songs: media.songs, videos: media.videos, log });
   const site = buildSiteFiles(root, dist, { gameIds: rows.map((g) => g.id), log });
+  // Each game's Game Codex (games/<id>/CODEX.md), as the owner's private page at /_studio/codex/<id>/ (never listed).
+  const codexes = buildCodexPages(root, dist, games.map((g) => g.id), { log });
   mkdirSync(join(dist, '_site'), { recursive: true });
   writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
   const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
@@ -257,7 +262,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   return {
     ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
-    posts: posts.map((p) => p.slug), postsSkipped, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
+    posts: posts.map((p) => p.slug), postsSkipped, codexes, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
     landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };
 }

package/lib/cloudflare.mjs

@@ -129,7 +129,12 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     return { ok: false, command: 'deploy', needs: 'cloudflare-account', why: `This Cloudflare login can reach ${who.accounts.length} accounts; ask the person which one this studio uses and put its id in studio.json (cloudflare.accountId).`, accounts: who.accounts };
   }
   const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
-  const refuse = (why, out) => ({ ok: false, command: 'deploy', ...(explainCloudflare(out, accountId) ?? { why }) });
+  const refuse = (why, out) => {
+    const r = { ok: false, command: 'deploy', ...(explainCloudflare(out, accountId) ?? { why }) };
+    // What the account asked for (an email to verify…) stays on this computer, for `setup status`.
+    if (r.needs) { try { writeLocal(root, { needs: r.needs, needsAt: new Date().toISOString() }); } catch { /* not recorded */ } }
+    return r;
+  };
   // Record every resource the moment it exists, so a deploy cut short (an expired login, a network drop) resumes
   // instead of refusing its own database as "someone else's" next time.
   const remember = (key) => {
@@ -201,7 +206,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   // .studio/local.json (git-ignored), and never in the committed studio.json. A custom domain stays in studio.json.
   if (ensureLocalIgnored(root)) step(`added .studio/ to .gitignore (${LOCAL_STATE} keeps this computer's own state)`);
   const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? readLocal(root).url ?? (isWorkersDev(cf.url) ? cf.url : null);
-  if (workersDev) writeLocal(root, { url: workersDev, deployedAt: new Date().toISOString() });
+  if (workersDev) writeLocal(root, { url: workersDev, deployedAt: new Date().toISOString(), needs: null, needsAt: null });
   const movedOut = isWorkersDev(cf.url);
   if (movedOut) {
     cf.url = null;