@lampdotdev/lamp 0.0.0-stage → 0.36.2-nightly.16

package/cli/skill/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: lamp
+description: Make, run, see and try an app with lamp's command line - a web app, a web game, or a Mac app Lamp made in Swift. Use when the person asks for a new web game, or when working in a folder made with Lamp (a page beside lamp-game.js or in Web/, or Package.swift with build.sh and Sources/LampSupport.swift) or in a plain site's folder and they ask to change the app, to see it, or to check that a change works. Every saved change goes into the open app, and a game keeps the player's place.
+---
+
+# Working on an app with lamp
+
+`{{lamp}}` runs the page in the app's folder and puts each change into it while it's open. Save a file and the change
+goes in. Never build, restart or reload anything for a change.
+
+Run the commands from the app's folder, or give the folder after the command (`{{lamp}} look path/to/app`).
+
+Most of this is about an app that is a web page: a web game, a web app, a plain site. An app Lamp made that way has
+the page in `Web/`, beside the Swift of the app around it, which stays as it is. An app whose own screens are Swift
+is a Mac app: "A Mac app" below says what's different for one.
+
+## A new game
+
+`{{lamp}} new path/to/folder --name "Its Name"` makes a new web game's folder from Lamp's starting files: the game
+runtime (`lamp-game.js`), three.js and Phaser, `APP.md`, and a page that shows a card until the game replaces it. The
+page is at the top of the folder: what Lamp's skills call `Web/` is the folder itself.
+
+Before writing, read Lamp's `web-game` and `game-feel` skills, which are for every game, and `game-playtest` when
+you're asked to play it; "Lamp's skills" below says what in them is Lamp's app's doing. The card's `game.js`,
+`world.js` and `making.js` are yours to replace, as `web-game` says.
+
+The card is a small game of its own, and the runtime keeps what it registered (a state called `play`, a camera)
+through a change, as it would the player's place. So write the whole game before the first look, and make that look
+with `--reopen` (`{{lamp}} look --reopen`): the game then opens from its beginning, not from the card's. If you
+looked earlier, `--reopen` puts it right.
+
+## A new web app
+
+`{{lamp}} new path/to/folder --web --name "Its Name"` makes a new web app's page from Lamp's starting files:
+`index.html`, `style.css` and `app.js`, which are yours to write, `APP.md`, and `lamp.js`, Lamp's building blocks for
+a page (saved data with `LampStore`, the app's files and more). Read Lamp's `web-app` skill before writing it, and
+the comments in `lamp.js` for how each block is used; never edit `lamp.js`. Its AI (`LampAI`: ask, act, decide) is
+answered by lamp itself on this Mac, with the person's own Claude Code or Codex (or OpenRouter, with their key in `OPENROUTER_API_KEY`), in every page lamp runs here (`dev`,
+`open`, `look`, `use`); pictures and hearing need Lamp's app. Shared on lamp.dev, it's answered on the computer the page is played on while Lamp is open there or `{{lamp}} ai` runs there in a terminal, once the person allows that page. Never put a key or a model provider's address in the page. A page that wants none of Lamp's needs no starting files: write its
+`index.html` in an empty folder.
+
+## A Mac app
+
+A folder with `Package.swift`, `build.sh` and `Sources/LampSupport.swift` and no page is a Mac app Lamp made in
+Swift. `{{lamp}} new path/to/folder --mac --name "Its Name"` makes a new one: Lamp's building blocks, and a card it
+shows until its code in `Sources/` is written. The same commands work on it, with these differences:
+
+- **Lamp's building blocks** are what the app is made with: saved data, AI, windows, the menu bar and the rest.
+  `{{lamp}} blocks` lists them with what each is for, and `{{lamp}} blocks LampStore` says how one is used: read the
+  ones the app needs before writing it. Lamp's `building-blocks` and `app-kinds` skills say which to reach for and
+  how such an app is laid out; where a skill points to rules of Lamp's own that aren't here (a base design), use
+  your judgment.
+- **A change is a build.** Each save to the app's code builds it again, a few seconds for a small change, and opens
+  it again: what was typed or open in it is gone, so change first and try after. `look` waits for the build.
+- **`look`** answers pictures of the app's windows (taken by the app itself, so nothing is asked of the person),
+  what it printed, and when it didn't build, the compiler's errors with their file and line: the app is then as it
+  was before the change. It answers the screen as text too once the app has been in front with the Mac unlocked;
+  without it, aim by the picture, whose points are the points to click. `look --reopen` quits the app and opens it
+  again first, as `{{lamp}} reload` does.
+- **`use`** takes `click` (a point of the picture, or a name or id from the screen as text: `{{lamp}} use click "Add"`),
+  `type`, `key` (`return`, `escape`, `cmd+a`…), `drag`, `scroll` and `wait`. It brings the app to the front. Only
+  when asked to try it.
+- **What you add while trying it is the app's real saved data**, kept under the app's own name in the person's
+  Application Support: take it out again, or tell them it's there.
+- **The app stays open** when you finish, as the person's to use. `{{lamp}} stop` quits it, when they only wanted it
+  checked.
+- **Lamp's own files** are `Sources/LampSupport.swift`, `build.sh` and `Package.swift`: never edit any of them.
+- **A change into the open app, without reopening it**, is Lamp's app's: when the person has Lamp open and wants that,
+  `{{lamp}} open --in-lamp` gives the app to it (Lamp shows them its review the first time). From then on `look`, `dev`
+  and `reload` say how each change went in (live, held for their Reload, reopened, not built), and the person tries it
+  there, and `use` tries the app Lamp has open, in plain sight. `{{lamp}} open --here` has lamp run its own copy again.
+- **Not here:** the app's AI (`LampAI`), and a link to one on lamp.dev (its Lamp app file is here: see "A Lamp app
+  file"). Those
+  are Lamp's app's: say so rather than working around it. What the app keeps secret (`LampSecrets`) is kept for it.
+
+## A game that's already there
+
+A web game from somewhere else runs as it is: every command here works on it, each change opens its page again from
+the start, and `look` can't know when it has finished loading. Putting it on Lamp's runtime is what lets it take
+changes while it's played and say when it's really playing. `{{lamp}} init` puts Lamp's own files beside its page and
+changes none of the page's; taking the runtime up in the game's code is the work. It goes in steps, each worth having
+by itself:
+
+1. **The runtime runs the game's loop** (`game()` in place of the game's own), with its renderer kept and the
+   player's place given and taken back. A change then runs the game's code again in place, where before it opened
+   the page again. A page laid out at the window's size that reads its own keys and touches says so to `game()`:
+   the options are in `lamp-game.js`'s comments on the frame.
+2. **The modules that get tuned accept their changes**, and those go in live.
+3. **What's slow to build is kept**, so running the code again doesn't build it again.
+
+Lamp's `game-live` skill says how each is done (its "A game from before this, or one brought in" is step 1), and
+`lamp-game.js`'s comments are the whole interface: read those, not `web-game`, which is for a new game. A game
+brought in reads its own input until its code reads the runtime's, so try it with keys, not Lamp's controller.
+
+Where Lamp's `github-projects` skill has Lamp's app keep the project's credit and licenses (`lampify`), nothing does
+here: keep its license file, its copyright headers and its author's credit on screen yourself.
+
+## The loop
+
+1. **Show the person the app** once, when you start, unless they don't want to watch: `{{lamp}} open`. It opens a
+   window they can use and play in while you work, and returns at once.
+2. **Change the files.** First say what you're changing, in a few words of theirs: `{{lamp}} changing "Rain on the
+   roads"`. Do it before every change, however small: the app shows it on the card it puts up as the change goes in,
+   and without it the card says only that it's updating. It stands until you say something new.
+3. **Look**: `{{lamp}} look`. It waits for the change to go in, then answers how it went, a picture of the page (a
+   file: read it; the last forty are kept), the screen as text, and the errors and the log since your last look. Look
+   after every change, and read the errors and the picture before saying it works. `{{lamp}} look --reopen` opens the
+   page again from its beginning first, a game with its saves kept: what someone opening it sees. `--size 900x600`
+   looks at it as a window of that size shows it, for a layout that has to hold at any shape (with no window open).
+   When the answer says lamp found no Chrome, Edge, Brave or Chromium, there's no picture and `use` can't play the
+   page: tell the person, since only they can install one.
+
+Nothing has to be running first. With no window open, `look` runs the app itself in a copy of the page nobody sees,
+opened from the files as they are, so the first look has no changes to report. The copy goes on running between
+commands, as a window would: what you clicked and typed is still there, and a game's clock doesn't wait for you. It
+closes by itself ten minutes after you last used it: there's nothing to stop when you finish.
+
+## Trying it
+
+Only when the person asks you to try, play or test the app: a request to change it is made and looked at, not played.
+
+- `{{lamp}} use click "Add"` clicks a control by its name in the screen as text, and `{{lamp}} use click 640 400` a
+  point of the picture, for what has no name there (a canvas, a drawing). The answer names what the click landed on.
+- `{{lamp}} use type hello` types into whatever has the keyboard: click a field first.
+- `{{lamp}} use key w 2` holds a key for two seconds (a letter, a digit, `space`, `enter`, `escape`, `up`, `left`…),
+  and `w+d` holds two at once.
+- `{{lamp}} use drag 400 300 700 300` presses at one point, moves to the other and lets go.
+- `{{lamp}} use scroll 600` scrolls down, and up with a negative number. A look shows only what's in the window.
+- `{{lamp}} use wait 3` waits, for something that takes time: thirty seconds at most, so wait again for longer.
+
+Several moves go in one command with `then` between them, one after another with nothing in between and one look at
+the end: `{{lamp}} use click 640 400 then key w 3 then key w+d 2`. Play anything with a clock that way, a whole
+stretch of it to a command, and end the stretch on the game's pause when it has one (`… then button menu`): the game
+runs on while you read a picture. Where a canvas is drawn at another size than it's shown, the screen as text says
+how a point of the game is found in the picture.
+
+A game on Lamp's runtime is played with Lamp's own controller, as Lamp's game skills say (`use_app`'s `stick` and
+`button`):
+
+- `{{lamp}} use stick left 1 0 2` holds the left stick to the right for two seconds: `left` or `right`, then x and y
+  from -1 to 1, right and up being 1. A button named after the seconds is held with it (`… 2 a`).
+- `{{lamp}} use button a` presses a button, `a 1.5` holds it, and `a+rt` holds two: `a`, `b`, `x`, `y`, `lb`, `rb`,
+  the triggers `lt` and `rt`, `menu`, `view`, `up`, `down`, `left`, `right`.
+
+It's the first player's controller, from wherever the game is. It isn't a controller plugged in, so the game's
+prompts go on naming keys. If the person plays meanwhile they have it back at once and the answer says so: the game
+is theirs until they ask again. A key works in a game here too.
+
+Each answers with a look. With the window open it happens in the person's own window, where they see it.
+
+## How a change went in
+
+`look` says one of these for each change since the last look:
+
+- **live**: swapped in while the page ran. Nothing was lost.
+- **reran**: the game's code ran again, with the player where they were. In a small game that takes a moment, and
+  is as good as live.
+- **reopened**: the page opened again. A game opens from the player's place. A plain page always takes a change this
+  way and starts over: what was typed or counted in it is gone, so change first and try after.
+- **held**: the change waits, and the page shows the person a Reload to apply button. Either it waits for a pause in
+  the game (the end of a round, a menu), and goes in by itself then: a later look says so. Or for that button, because
+  the page must open again for it: `{{lamp}} reload` presses it, so with a window open ask the person first.
+
+The reason given after one names the file that changed, where an `accept()` would have taken the change, and the
+module it's loaded through. A game that takes changes live is written for it. When a change won't go in, needs Reload
+or loses the player's place, read Lamp's `game-live` skill before working around it.
+
+## A Lamp app file
+
+A folder with `lamp-app.json` at its top (or in `.lamp-wish/`) is an app in Lamp's format, from GitHub or a shared file:
+every command here works on a web app, a game, a screen or a Mac app in one, and says so for a kind it doesn't run.
+
+- `{{lamp}} unpack Name.lampapp` unpacks a Lamp app file (what Lamp's Share… makes) into a new folder beside it, with
+  Lamp's own files put in, and says how to see it.
+- `{{lamp}} export` makes the app's Lamp app file beside its folder, for the person to send or open in Lamp: only when
+  they ask. It's refused when something in the app is shaped like a key, or a license its credits name is gone; when
+  it uses work that came with no license, ask the person before `--anyway`.
+
+## Sharing it
+
+Only when the person asks: a link is public, and anyone who has it can play the page.
+
+- Start with `{{lamp}} share --preview`: it says what would go and sends nothing. Show the person, and share only once they
+  say so.
+- **A web app or game of Lamp's own** (its folder is in Lamp's) is shared here like any other page, whether Lamp is open
+  or not, to the link Lamp already has for it, and `ideas` and `unshare` work on that link too. Run `{{lamp}} share` with
+  no words of your own (it keeps the link's), and give `--line`, `--by` or `--asks "a|b"` only for what the person
+  wants changed.
+- **Any other app of Lamp's** (a Mac or iPhone app, a wish of several; the preview says it's going through Lamp) is
+  shared by Lamp, which must be open, filled as its Share Link card fills itself: its words, the questions and what's new
+  Lamp writes, its file, its GitHub release. Give `--notes "What's new|And more"` and the rest only for what the person
+  wants changed. Its ideas and taking it down are on Lamp's Share Link card.
+- **Any other page:** `{{lamp}} share --words "What it is, in a sentence or a few"` puts it on lamp.dev and answers its
+  link. `--line` is a line under its name, `--asks "Found a bug?|What's missing?"` what the box under the page asks
+  people, and `--by "Their Name"` who it's by, when they want another name than the one it goes out with (the name they last
+  gave, or Lamp's, or their name on this computer, which the share says). A link goes under the person's username on
+  lamp.dev (`lamp.dev/<username>/<app>`) once they have one: the first time you share, ask them which username they want
+  and their email, and run `{{lamp}} account <username> --email <theirs>`; they confirm it from the email, and the link
+  moves there at its next share. `{{lamp}} account` says which they're signed in as. A page that's logging errors
+  isn't shared until they're put right. Again, after changes, it sends the page as it is now to the same link, with the
+  same words unless you give new ones.
+- `{{lamp}} ideas` lists what people playing it have sent, each with the address of a picture of the app as they saw
+  it when they kept one in: look at it before building the idea. Once one is in the game and the game shared again,
+  `{{lamp}} ideas in <number>` says so, and whoever asked to hear is written to; `{{lamp}} ideas dismiss <number>` lets
+  one go. Words after the number are a note to whoever sent it, shown on the link's page and put in that email: write
+  one only when the person asks you to answer them, in their words. Senders can answer by email: `{{lamp}} ideas` shows
+  what's been said under each idea, and those they've answered; `{{lamp}} ideas reply <number> <words>` answers again,
+  and `{{lamp}} ideas done <number>` leaves one without a word. `{{lamp}} ideas --earlier` lists those seen to. `{{lamp}} ideas email <address>` sends new ideas and replies to the
+  person's own address too, once they confirm it from the email it sends (`off` stops them): only with an address
+  they gave you.
+- `{{lamp}} unshare` takes the link down.
+
+Tell the person the link, and that it's public.
+
+## On the person's Xbox
+
+A page goes on an Xbox in Developer Mode, in Lamp's own host for the console's browser: the same files, played with
+the console's controller. Only when the person asks for it there, and only on a device they set up.
+
+- `{{lamp}} devices` lists the devices set up with lamp and those found on the network. One only found may not be
+  theirs: never put anything on it.
+- Setting one up asks for the console's Device Portal password, which only the person types. Ask them to run
+  `{{lamp}} devices add` in a terminal themselves; never ask for the password, and never type one.
+- `{{lamp}} open --on xbox` packages the page as it is now, installs it and opens it on the console, in place of the
+  copy that was there. A change isn't live there: put the page on again once it works on this computer.
+- `{{lamp}} look --on xbox` is the console's screen as a picture, whether the app is open there, and what it logged
+  there. A game on Lamp's runtime logs how many frames a second it gets: that, never this computer's, says how it
+  runs on the console.
+- You can't press the controller there. Try the game in its window here (`stick`, `button`), where it's the same
+  code, and tell the person what's left for them to try with the controller in their hands.
+- `{{lamp}} stop --on xbox` ends it, and `{{lamp}} remove --on xbox` takes it off the console.
+
+## On Android
+
+A page goes on Android in Lamp's own Android app around it: the same files, on a phone, a tablet or a TV. It needs a
+Mac with Android's tools, which `{{lamp}} devices` says are there or not. If they aren't, ask the person to run
+`{{lamp}} devices add android` in a terminal themselves: it downloads Google's tools and accepts Google's terms for
+them, which is theirs to do.
+
+- `{{lamp}} open --on android` builds the app and opens it in lamp's Android emulator, a phone in a window on the Mac;
+  `--on android-tv` is its TV emulator. Use these when the person asks to see it on Android.
+- For a check of your own, add `--hidden`: the emulator starts with no window and no sound, and
+  `{{lamp}} stop --on android` closes it when you're done. Don't leave one running.
+- A phone, tablet or TV of the person's goes by its name (`{{lamp}} devices` lists those plugged in with USB debugging
+  on): only when they ask for it there. If it says to allow debugging, that's a tap on the device's own screen, theirs.
+- `{{lamp}} look --on android` is the device's screen as a picture, whether the app is open, and what the page logged
+  there: a game on Lamp's runtime logs how many frames a second it gets.
+- `{{lamp}} use --on android click <x> <y>` taps a point of that picture; `drag`, `type`, `key` and `button` work too,
+  one key or button at a time, with no stick. A game shows touch controls until a controller's button is pressed.
+- A change isn't live there: `{{lamp}} open --on android` again builds and installs it, in a few seconds.
+- `{{lamp}} remove --on android` takes it off.
+
+## Lamp's skills
+
+An app Lamp made (its page loads `lamp.js`) is built from Lamp's own building blocks, and Lamp has guidance for each
+kind of work on one: a new web game, 3D, how a game feels, a web app's page. `{{lamp}} skills game` lists those about a
+word, `{{lamp}} skills` all of them, and `{{lamp}} skill <name>` prints one. Read the ones that fit before changing what
+they cover: they are the one place that says which building blocks to use and how.
+
+Those skills are written for Lamp's app, which builds the game, opens it and looks at it for you when your turn
+ends, and so tells you to write and finish without looking or playing. Nothing does that here: you look after every
+change, as above, and that comes first. Where one names a tool of Lamp's:
+
+- `look_at_app` is `{{lamp}} look`, and its `reopen` is `--reopen`. There's no `motion`: look twice.
+- `use_app` is `{{lamp}} use`, one move to each of its actions. A control on the page is clicked at its point from the
+  screen as text, not by an id.
+- `read_skill` is `{{lamp}} skill <name>`, and `make_app_for` is `{{lamp}} new`, for a web game only.
+- `delete_file` is deleting the file, and putting a change in needs no tool.
+- `assets`, `make_art` and `lampify` aren't here: make what's needed in code, or say what's missing.
+
+A plain site, on neither `lamp.js` nor Lamp's runtime, uses none of them: skip the skills there.
+
+## Rules
+
+- Lamp's own files in the folder are rewritten by Lamp, so read them and never edit them: `lamp.js`, `lamp-game.js`,
+  `lamp-phaser.js`, `lamp-controllers.js`, and the `three/` and `phaser/` folders.
+- The page's whole log is the file `look` names.
+- lamp runs the page in a browser on this computer, and puts it on an Xbox ("On the person's Xbox") and on Android
+  ("On Android"). iPhones, Samsung and LG TVs,
+  and whatever needs Lamp's Mac app around the page, aren't here: say so rather than working around it.

package/cli/skills.mjs

@@ -0,0 +1,71 @@
+// Lamp's skills as `lamp skill` prints them: read from Lamp's own folder (Resources/skills), and put together the way
+// Lamp's app puts them together (`Skills.parse`, `Skills.assembled`, `Skills.section`). A skill made of sections of
+// others names them in its frontmatter ("game#Fun; game-ui#Proof") and has them put where its body says
+// `{{sections}}`, so each section is written in one place.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCES } from "./state.mjs";
+
+export const SKILLS = join(RESOURCES, "skills");
+
+/** A SKILL.md: frontmatter between `---` lines, a field a line, then the instructions. */
+function parse(text) {
+  const lines = text.split("\n");
+  const close = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || close < 0) return null;
+  const fields = {};
+  for (const line of lines.slice(1, close)) {
+    const colon = line.indexOf(":");
+    if (colon > 0) fields[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+  }
+  if (!fields.name || !fields.description) return null;
+  return { name: fields.name, description: fields.description, sections: fields.sections ?? null, body: lines.slice(close + 1).join("\n").trim() };
+}
+
+/** One section of a skill, as "skill#Heading": its heading, made a second-level one, and what's under it. */
+function section(name, skills) {
+  const at = name.indexOf("#");
+  const source = at < 0 ? null : skills.get(name.slice(0, at))?.body;
+  if (source == null) return null;
+  const title = name.slice(at + 1), lines = source.split("\n");
+  // A line of a code block is never a heading, whatever it starts with.
+  let fenced = false;
+  const headings = [];
+  lines.forEach((line, index) => {
+    if (line.startsWith("```")) { fenced = !fenced; return; }
+    const marks = /^(#+) /.exec(line);
+    if (!fenced && marks) headings.push({ index, level: marks[1].length, title: line.slice(marks[1].length).trim() });
+  });
+  if (!title) {
+    // The text before the skill's first section.
+    const first = headings.find((heading) => heading.level === 1), second = headings.find((heading) => heading.level === 2);
+    const start = first ? first.index + 1 : 0, end = second ? second.index : lines.length;
+    return lines.slice(start, Math.max(start, end)).join("\n").trim() || null;
+  }
+  const found = headings.findIndex((heading) => heading.title === title && heading.level > 1);
+  if (found < 0) return null;
+  const heading = headings[found], next = headings.slice(found + 1).find((later) => later.level <= heading.level);
+  return `## ${heading.title}\n\n${lines.slice(heading.index + 1, next ? next.index : lines.length).join("\n").trim()}`;
+}
+
+/** Every skill by name, each as Lamp's app hands it over. Empty when Lamp's skills aren't beside this copy of lamp. */
+export function allSkills() {
+  const skills = new Map();
+  if (!existsSync(SKILLS)) return skills;
+  for (const entry of readdirSync(SKILLS, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    let skill = null;
+    try { skill = parse(readFileSync(join(SKILLS, entry.name, "SKILL.md"), "utf8")); } catch {}
+    if (skill) skills.set(skill.name, skill);
+  }
+  // Sections come from the skills as they're written, never from one already put together.
+  const written = new Map(skills);
+  for (const skill of written.values()) {
+    if (!skill.sections) continue;
+    const text = skill.sections.split(";").map((name) => name.trim()).filter(Boolean).map((name) => section(name, written)).filter(Boolean).join("\n\n");
+    skills.set(skill.name, { ...skill, body: skill.body.includes("{{sections}}") ? skill.body.replaceAll("{{sections}}", text) : `${skill.body}\n\n${text}` });
+  }
+  return skills;
+}

package/cli/state.mjs

@@ -0,0 +1,176 @@
+// Where a folder's page is, where lamp keeps what it needs for it, and how one lamp command finds the server another
+// started for the same folder.
+
+import { createHash } from "node:crypto";
+import { existsSync, statSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Where Lamp's own resources are (its game kit, libraries, skills, device integrations): the repository's Resources/
+ * beside cli/, or in Lamp's app, the bundle's Resources, which holds this copy of lamp in its cli/ (build.sh).
+ */
+export const RESOURCES = (() => {
+  const cli = dirname(fileURLToPath(import.meta.url));
+  const repository = join(cli, "..", "Resources");
+  return existsSync(join(repository, "GameKit")) ? repository : join(cli, "..");
+})();
+
+/** Something the person or agent can put right, said in plain words and shown without a stack. */
+export class Problem extends Error {}
+
+/** The runtime whose presence makes a page a game's (`GamePage.runtimeFile`). */
+export const RUNTIME_FILE = "lamp-game.js";
+// The app's notes, at the top of its page: what it is and how it's made, for whoever works on it. Never part of the
+// page: saving it changes nothing a page runs, and a shared page goes without it.
+export const NOTES_FILE = "APP.md";
+
+/**
+ * How the folder is laid out: an app Lamp made keeps its page in Web/, and any other folder with an index.html is a
+ * plain site whose page is the folder itself.
+ */
+export function layoutOf(given) {
+  let folder = resolve(given);
+  if (!existsSync(folder) || !statSync(folder).isDirectory()) throw new Problem(`${folder} isn't a folder`);
+  folder = realpathSync(folder);
+  const root = [join(folder, "Web"), folder].find((candidate) => existsSync(join(candidate, "index.html")));
+  if (!root) throw new Problem(`${folder} has no page: no Web/index.html and no index.html`);
+  return { folder, root, lamps: root !== folder, game: existsSync(join(root, RUNTIME_FILE)) };
+}
+
+/**
+ * What Lamp's own record in the folder says it is (`lamp-app.json`, which an app Lamp shared or put on GitHub carries
+ * at its top, or a site in `.lamp-wish/`): its kind (`platform`), its name and the wish's other apps (`parts`). Null in
+ * a folder without one.
+ */
+export function manifestOf(folder) {
+  for (const at of ["lamp-app.json", join(".lamp-wish", "lamp-app.json")]) {
+    try {
+      const said = JSON.parse(readFileSync(join(folder, at), "utf8"));
+      if (said && typeof said === "object" && !Array.isArray(said)) return said;
+    } catch {}
+  }
+  return null;
+}
+
+/** Whether some Swift of the app's own imports RealityKit (`Template.importsRealityKit`), which Lamp builds a scene around. */
+function importsRealityKit(folder) {
+  let entries;
+  try { entries = readdirSync(folder, { withFileTypes: true }); } catch { return false; }
+  return entries.some((entry) => entry.isDirectory() ? importsRealityKit(join(folder, entry.name))
+    : entry.name.endsWith(".swift") && entry.name !== "LampSupport.swift" && entry.name !== "LampScene.swift"
+      && /^\s*(@\w+\s+)?import\s+RealityKit\b/m.test(readFileSync(join(folder, entry.name), "utf8")));
+}
+
+/**
+ * The newest Lamp app format this lamp reads (`Sharing.formatVersion`, which CLIFilesTests holds it to): a folder in a
+ * newer one was made by a newer Lamp, laid out in a way this lamp may misread.
+ */
+export const FORMAT = 12;
+
+// The kinds Lamp makes that lamp doesn't build or run, in the words a person knows them by (`Platform`'s kinds).
+const ELSEWHERE = {
+  iphone: "an iPhone app", universal: "an app for both the Mac and the iPhone", android: "an Android app",
+  "android-tv": "an Android TV app", tv: "a TV app", device: "an app for a device through its integration",
+};
+
+/**
+ * What the folder is to lamp: a page (as `layoutOf` reads it), or an app Lamp made in Swift for the Mac (its code in
+ * Sources/; `missing` lists Lamp's own files it lacks, which a shared file never carries and lamp writes before it
+ * builds). A folder in Lamp's format is read by what its `lamp-app.json` says it is: a web app, a game or a screen is
+ * its page (a game Lamp made has the Mac app around its page too), a Mac app its code, and a kind lamp doesn't run, or
+ * a wish of several apps, is said so rather than taken for another.
+ */
+export function projectOf(given) {
+  const folder = resolve(given);
+  if (!existsSync(folder) || !statSync(folder).isDirectory()) throw new Problem(`${folder} isn't a folder`);
+  const real = realpathSync(folder);
+  const hasPage = [join(real, "Web"), real].some((candidate) => existsSync(join(candidate, "index.html")));
+  const owned = ["Package.swift", "build.sh", join("Sources", "LampSupport.swift")];
+  const manifest = manifestOf(real);
+  if (manifest) {
+    if (Number.isInteger(manifest.format) && manifest.format > FORMAT) throw new Problem(`${real} was made by a newer Lamp than this lamp knows (its format is ${manifest.format}): update lamp, or open it in Lamp's app`);
+    const parts = Array.isArray(manifest.parts) ? manifest.parts.length : 0;
+    if (parts) throw new Problem(`${real} is a wish of ${parts + 1} apps, and lamp works on one app in a folder: open it in Lamp's app`);
+    const kind = typeof manifest.platform === "string" ? manifest.platform : "mac";
+    if (ELSEWHERE[kind]) throw new Problem(`${real} is ${ELSEWHERE[kind]}, which lamp doesn't build or run: open it in Lamp's app`);
+    if (["web-app", "game", "screen"].includes(kind)) {
+      if (!hasPage) throw new Problem(kind === "game" ? `${real} is a game written in C++, which lamp doesn't run: open it in Lamp's app` : `${real} has no page: no Web/index.html and no index.html`);
+      return { kind: "page", ...layoutOf(real) };
+    }
+    if (kind === "mac") {
+      if (!existsSync(join(real, "Sources"))) throw new Problem(`${real} is a Mac app with no code: no Sources/`);
+      const missing = owned.filter((path) => !existsSync(join(real, path)));
+      // Lamp's starting files build an app alone: a widget, a share extension or a 3D scene is built with files of
+      // Lamp's that only its app writes (`Template.writeSwiftOwnedFiles`).
+      const more = missing.length && (["Widget", "Share"].find((extra) => existsSync(join(real, extra))) ?? (importsRealityKit(join(real, "Sources")) ? "a 3D scene" : null));
+      if (more) throw new Problem(`${real} is a Mac app with ${more.includes(" ") ? more : `a ${more === "Widget" ? "widget" : "share extension"}`}, which only Lamp's app builds from a shared file: open it in Lamp's app first`);
+      return { kind: "mac", folder: real, missing };
+    }
+    throw new Problem(`${real} is a kind of app this lamp doesn't know ("${kind}"): a newer Lamp made it`);
+  }
+  if (hasPage) return { kind: "page", ...layoutOf(real) };
+  if (existsSync(join(real, "Package.swift")) && existsSync(join(real, "build.sh")) && existsSync(join(real, "Sources"))) return { kind: "mac", folder: real, missing: [] };
+  throw new Problem(`${real} has no page (no Web/index.html and no index.html), and isn't a Mac app Lamp made (no Package.swift with its build.sh, and no lamp-app.json)`);
+}
+
+/**
+ * Where lamp keeps what it needs for a folder: the browser's own files (so a game's saves last from one run to the
+ * next), the picture of the last look, and which server is running. Outside the folder, so nothing of lamp's is
+ * published or committed with a plain site.
+ */
+export function stateOf(folder) {
+  const home = process.env.LAMP_DEV_HOME || join(homedir(), ".lamp", "dev");
+  const name = basename(folder).replace(/[^\w.-]+/g, "-").slice(0, 40) || "app";
+  return join(home, `${name}-${hashOf(folder).slice(0, 8)}`);
+}
+
+const hashOf = (folder) => createHash("sha256").update(folder).digest("hex");
+
+/**
+ * The port a folder's page is first served on: its own, from its path, so two apps run side by side and each keeps
+ * its address (a game's saves belong to the address) from the first run on.
+ */
+export const firstPortOf = (folder) => 4400 + (parseInt(hashOf(folder).slice(0, 6), 16) % 500);
+
+/**
+ * The page's log, with the rest of lamp's state: lamp writes nothing in the app's folder, which may be one Lamp's app
+ * is running too, with a log of its own where an app made by Lamp keeps it.
+ */
+export function logFileOf(layout) {
+  return join(stateOf(layout.folder), "log.txt");
+}
+
+export const serverFileOf = (folder) => join(stateOf(folder), "server.json");
+
+/** Asks a running server something only lamp's own commands may ask: they hold the token it wrote for them. */
+export async function ask(server, path, body, { timeout = 10_000 } = {}) {
+  let answer;
+  try {
+    answer = await fetch(`http://127.0.0.1:${server.port}/__lamp/cli/${path}`, {
+      method: body === undefined ? "GET" : "POST",
+      headers: { "x-lamp-token": server.token, "content-type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch (error) {
+    throw new Problem(error.name === "TimeoutError" ? "lamp dev didn't answer in time" : "lamp dev isn't running for this folder");
+  }
+  const said = await answer.json().catch(() => null);
+  if (!answer.ok) throw new Problem(said?.problem || `lamp dev answered ${answer.status}`);
+  return said;
+}
+
+/**
+ * The server running for this folder, if one is: what it wrote when it started, checked by asking it. `own` is one a
+ * lamp command started for itself that has no window open: a `lamp dev` run by hand takes its place.
+ */
+export async function running(folder) {
+  let server;
+  try { server = JSON.parse(readFileSync(serverFileOf(folder), "utf8")); } catch { return null; }
+  try {
+    const hello = await ask(server, "hello", undefined, { timeout: 1500 });
+    return hello.folder === folder ? { ...server, url: hello.url, own: !!hello.own } : null;
+  } catch { return null; }
+}