@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/cli/browser.mjs

@@ -0,0 +1,268 @@
+// A browser lamp opens and can see into: the window the person uses, or a copy with no window that's only looked at.
+// It's a Chromium-family browser already on the computer, started with files of its own (never the person's own
+// browser profile) and spoken to over a pipe only this process holds, so nothing else on the computer can drive it.
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Problem } from "./state.mjs";
+
+const MAC = ["Google Chrome", "Chromium", "Microsoft Edge", "Brave Browser", "Google Chrome Canary"];
+const LINUX = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge", "brave-browser"];
+const WINDOWS = ["Google\\Chrome\\Application\\chrome.exe", "Microsoft\\Edge\\Application\\msedge.exe", "BraveSoftware\\Brave-Browser\\Application\\brave.exe"];
+
+/** A browser lamp can drive, or null: LAMP_BROWSER names one, else the first of the usual ones found. */
+export function findBrowser() {
+  const named = process.env.LAMP_BROWSER;
+  if (named !== undefined) return named && existsSync(named) ? named : null;
+  if (process.platform === "darwin") {
+    for (const apps of ["/Applications", join(homedir(), "Applications")]) {
+      for (const name of MAC) {
+        const path = join(apps, `${name}.app`, "Contents", "MacOS", name);
+        if (existsSync(path)) return path;
+      }
+    }
+    return null;
+  }
+  if (process.platform === "win32") {
+    for (const base of [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA]) {
+      for (const name of WINDOWS) if (base && existsSync(join(base, name))) return join(base, name);
+    }
+    return null;
+  }
+  for (const name of LINUX) {
+    const found = spawnSync("which", [name], { encoding: "utf8" });
+    if (found.status === 0 && found.stdout.trim()) return found.stdout.trim();
+  }
+  return null;
+}
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+// The keys a person names, as the browser is told them: the key, its place on the keyboard, its number, and what it
+// types if anything.
+const NAMED = {
+  enter: ["Enter", "Enter", 13, "\r"], return: ["Enter", "Enter", 13, "\r"], escape: ["Escape", "Escape", 27], esc: ["Escape", "Escape", 27],
+  space: [" ", "Space", 32, " "], tab: ["Tab", "Tab", 9], backspace: ["Backspace", "Backspace", 8], delete: ["Delete", "Delete", 46],
+  up: ["ArrowUp", "ArrowUp", 38], down: ["ArrowDown", "ArrowDown", 40], left: ["ArrowLeft", "ArrowLeft", 37], right: ["ArrowRight", "ArrowRight", 39],
+  shift: ["Shift", "ShiftLeft", 16], control: ["Control", "ControlLeft", 17], ctrl: ["Control", "ControlLeft", 17],
+  alt: ["Alt", "AltLeft", 18], option: ["Alt", "AltLeft", 18], command: ["Meta", "MetaLeft", 91], meta: ["Meta", "MetaLeft", 91],
+};
+
+// The browser's bit for each modifier key while it's held.
+const MODIFIERS = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+
+export function keyNamed(name) {
+  const lower = String(name).toLowerCase();
+  const named = NAMED[lower] ?? NAMED[lower.replace(/^arrow/, "")];
+  if (named) return { key: named[0], code: named[1], number: named[2], text: named[3] };
+  if (/^[a-z]$/.test(lower)) return { key: lower, code: `Key${lower.toUpperCase()}`, number: lower.toUpperCase().charCodeAt(0), text: lower };
+  if (/^[0-9]$/.test(lower)) return { key: lower, code: `Digit${lower}`, number: 48 + Number(lower), text: lower };
+  const f = /^f([1-9]|1[0-2])$/.exec(lower);
+  if (f) return { key: `F${f[1]}`, code: `F${f[1]}`, number: 111 + Number(f[1]) };
+  throw new Problem(`lamp doesn't know the key "${name}": a letter, a digit, F1 to F12, or one of ${Object.keys(NAMED).join(", ")}`);
+}
+
+/** One page of the browser, as lamp looks at it and uses it. */
+class Page {
+  constructor(browser, target, session) { this.browser = browser; this.target = target; this.session = session; }
+
+  send(method, params, timeout) { return this.browser.send(method, params, this.session, timeout); }
+
+  /** What an expression gives in the page, as JSON; null when the page can't answer in time. */
+  async evaluate(expression, { timeout = 5000 } = {}) {
+    const answer = await this.send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true }, timeout).catch(() => null);
+    return answer?.result?.value ?? null;
+  }
+
+  /** A picture of the page as it is, one pixel of it for each point of the page, so a point of the picture is a point to click. */
+  async picture({ width, height, dpr = 1, jpeg = false }) {
+    const clip = width && height ? { x: 0, y: 0, width, height, scale: 1 / dpr } : undefined;
+    const shot = await this.send("Page.captureScreenshot", { ...(jpeg ? { format: "jpeg", quality: 85 } : { format: "png" }), ...(clip ? { clip } : {}) }, 8000);
+    return Buffer.from(shot.data, "base64");
+  }
+
+  /** The page answers as the page in front, with the keyboard its own, however it's shown. */
+  async focus() { await this.send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => {}); }
+
+  /**
+   * Holds a key, or several at once (`w+a`, `control+a`), for some seconds. Each key goes down with the modifiers held
+   * before it, as a keyboard sends them: with Control, Alt or Command held it's a shortcut and types nothing, and with
+   * Shift a letter is a capital.
+   */
+  async key(names, seconds = 0) {
+    const keys = String(names).split("+").filter(Boolean).map(keyNamed);
+    let held = 0;
+    const sent = [];
+    for (const { key, code, number, text } of keys) {
+      const shifted = held & 8 && /^[a-z]$/.test(key) ? key.toUpperCase() : key;
+      const typed = held & 7 ? null : text && held & 8 && /^[a-z]$/.test(text) ? text.toUpperCase() : text;
+      const common = { key: shifted, code, windowsVirtualKeyCode: number, nativeVirtualKeyCode: number };
+      await this.send("Input.dispatchKeyEvent", { type: typed ? "keyDown" : "rawKeyDown", modifiers: held, ...common, ...(typed ? { text: typed, unmodifiedText: text } : {}) });
+      held |= MODIFIERS[key] ?? 0;
+      sent.push(common);
+    }
+    await sleep(Math.max(40, seconds * 1000));
+    for (const common of sent.reverse()) {
+      held &= ~(MODIFIERS[common.key] ?? 0);
+      await this.send("Input.dispatchKeyEvent", { type: "keyUp", modifiers: held, ...common });
+    }
+  }
+
+  async click(x, y) {
+    await this.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    await this.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", buttons: 1, clickCount: 1 });
+    await this.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button: "left", buttons: 0, clickCount: 1 });
+  }
+
+  async type(text) { await this.send("Input.insertText", { text }); }
+
+  /** Presses at one point, moves to another and lets go, as a hand would: in steps. */
+  async drag(x, y, toX, toY) {
+    await this.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    await this.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", buttons: 1, clickCount: 1 });
+    for (let step = 1; step <= 12; step++) {
+      await this.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: x + ((toX - x) * step) / 12, y: y + ((toY - y) * step) / 12, button: "left", buttons: 1 });
+      await sleep(16);
+    }
+    await this.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: toX, y: toY, button: "left", buttons: 0, clickCount: 1 });
+  }
+
+  async scroll(x, y, points) { await this.send("Input.dispatchMouseEvent", { type: "mouseWheel", x, y, deltaX: 0, deltaY: points }); }
+
+  async front() { await this.send("Page.bringToFront").catch(() => {}); }
+
+  /** Shows the page at another size, as a window of that size would, or at its own again with none given. */
+  async size(width, height) {
+    if (width && height) await this.send("Emulation.setDeviceMetricsOverride", { width, height, deviceScaleFactor: 0, mobile: false });
+    else await this.send("Emulation.clearDeviceMetricsOverride").catch(() => {});
+  }
+}
+
+class Browser {
+  constructor(child) {
+    this.child = child;
+    this.alive = true;
+    this.count = 0;
+    this.waiting = new Map();
+    this.pages = new Map();     // target id → Page
+    this.gone = [];
+    let held = "";
+    // The pipe's messages are JSON, each ended by a zero byte.
+    child.stdio[4].setEncoding("utf8");
+    child.stdio[4].on("data", (chunk) => {
+      held += chunk;
+      let end;
+      while ((end = held.indexOf("\0")) >= 0) {
+        const text = held.slice(0, end);
+        held = held.slice(end + 1);
+        let message;
+        try { message = JSON.parse(text); } catch { continue; }
+        this.heard(message);
+      }
+    });
+    child.stdio[3].on("error", () => {});
+    child.stdio[4].on("error", () => {});
+    child.on("exit", () => this.ended());
+    child.on("error", () => this.ended());
+  }
+
+  heard(message) {
+    if (message.id !== undefined) {
+      const waiter = this.waiting.get(message.id);
+      if (!waiter) return;
+      this.waiting.delete(message.id);
+      clearTimeout(waiter.timer);
+      if (message.error) waiter.reject(new Error(message.error.message)); else waiter.resolve(message.result);
+      return;
+    }
+    if (message.method === "Target.targetDestroyed" || message.method === "Target.detachedFromTarget") {
+      const id = message.params.targetId;
+      if (id) this.pages.delete(id);
+      // The person closed the window: on a Mac the browser would stay running with none, so it's closed with it.
+      if (message.method === "Target.targetDestroyed") this.closeIfEmpty();
+    }
+  }
+
+  async closeIfEmpty() {
+    const targets = await this.send("Target.getTargets").catch(() => null);
+    if (targets && !targets.targetInfos.some((target) => target.type === "page")) this.close();
+  }
+
+  ended() {
+    if (!this.alive) return;
+    this.alive = false;
+    for (const waiter of this.waiting.values()) { clearTimeout(waiter.timer); waiter.reject(new Error("the browser closed")); }
+    this.waiting.clear();
+    this.pages.clear();
+    for (const told of this.gone) told();
+  }
+
+  /** Called once the browser has gone, however it went. */
+  onGone(told) { this.gone.push(told); }
+
+  send(method, params = {}, session, timeout = 10_000) {
+    if (!this.alive) return Promise.reject(new Error("the browser closed"));
+    const id = ++this.count;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.waiting.delete(id); reject(new Error(`the browser didn't answer ${method}`)); }, timeout);
+      this.waiting.set(id, { resolve, reject, timer });
+      this.child.stdio[3].write(JSON.stringify({ id, method, params, ...(session ? { sessionId: session } : {}) }) + "\0");
+    });
+  }
+
+  /** The page showing what's at this address, or null when the browser has none (the person went elsewhere in it). */
+  async page(origin, timeout) {
+    if (!this.alive) return null;
+    const targets = await this.send("Target.getTargets", {}, undefined, timeout).catch(() => null);
+    const target = targets?.targetInfos.find((info) => info.type === "page" && info.url.startsWith(origin));
+    if (!target) return null;
+    let page = this.pages.get(target.targetId);
+    if (!page) {
+      const attached = await this.send("Target.attachToTarget", { targetId: target.targetId, flatten: true });
+      page = new Page(this, target.targetId, attached.sessionId);
+      this.pages.set(target.targetId, page);
+    }
+    return page;
+  }
+
+  close() {
+    if (!this.alive) return;
+    this.send("Browser.close").catch(() => {});
+    setTimeout(() => { try { this.child.kill(); } catch {} }, 1500).unref();
+  }
+
+  /** At once, as lamp itself goes. */
+  kill() { try { this.child.kill(); } catch {} }
+}
+
+/**
+ * Starts the browser at an address: `window` a window for the person, else a copy that's never shown. Its files are
+ * kept in `profile`, apart from the person's own browser.
+ */
+export async function launch({ path, url, profile, window, size = [1280, 800] }) {
+  mkdirSync(profile, { recursive: true });
+  const args = [
+    "--remote-debugging-pipe", `--user-data-dir=${profile}`, "--no-first-run", "--no-default-browser-check",
+    "--disable-features=Translate,MediaRouter,OptimizationHints", "--disable-sync", "--disable-component-update", "--hide-crash-restore-bubble",
+    `--window-size=${size[0]},${size[1]}`,
+    // The page goes on running, and takes changes, while it's behind other windows.
+    "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding", "--disable-background-timer-throttling",
+    ...(window ? [`--app=${url}`] : ["--headless=new", "--hide-scrollbars", "--mute-audio", url]),
+  ];
+  let child;
+  try { child = spawn(path, args, { stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"] }); }
+  catch (error) { throw new Problem(`${path} didn't start: ${error.message}`); }
+  const browser = new Browser(child);
+  // Target ids come with what happens to them, so a closed window is noticed.
+  await browser.send("Target.setDiscoverTargets", { discover: true }).catch(() => {});
+  const origin = new URL(url).origin;
+  const until = Date.now() + 15_000;
+  while (browser.alive && Date.now() < until) {
+    if (await browser.page(origin, 2000)) return browser;
+    await sleep(100);
+  }
+  browser.kill();
+  throw new Problem("the browser started but didn't open the page");
+}

package/cli/calls.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+// What Lamp's app asks of lamp. The work that's lamp's own (this folder) is done here once, and Lamp's app has it done
+// (`LampCLI`, in Swift) rather than doing it a second time itself. Each call is one run of this file: the call's name
+// is its one argument, what it's given is one JSON object on standard input (never in the arguments, which any
+// process on the computer can list), and its answer is the last line it prints, one JSON object: {"done": …}, or
+// {"problem": "…"} for something the person can put right, said in a sentence. Anything else that goes wrong ends
+// the run with its own words on standard error.
+//
+// A call works on what Lamp's app hands it from Lamp's own folders, by path. It's never pointed at an app's folder:
+// what's there is the agent's to write, and Lamp's app reads it its own way before anything comes here.
+//
+// Run with --serve in the place of a call's name, it stays: each line on standard input is {"id", "call", "given"},
+// and each is answered, in whatever order they finish, by a line {"id", "done"} or {"id", "problem"}, or {"id",
+// "failed"} with lamp's own words for anything else. A line {"stop": id} lets go of a call that hasn't answered, when
+// whoever asked no longer wants it. It ends when its input does, which is when Lamp's app does. The many small things
+// go this way (a request to a device), so each doesn't wait for a program to start.
+//
+// Lamp's app runs this on the JavaScript runtime it carries (the Bun its bundled agent is built on), and a test run on
+// Node: what's imported here, and by what it imports, has to run on both.
+
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Away, OffNetwork, Refused, Rejected, Runner, StillWorking, answersOn, bonjour, pinsAt, searchNetwork, send, ssdp } from "./devices.mjs";
+import { adbCommand, connectTo, deviceListing, deviceProperties, displaySizeOf, dumpIn, installApk, installTools, launchApp, makeEmulator, pairWith, processIn, processOf,
+  rowsOf, saveState, screenItems, screenshotOf, tellApp, toolsThere, useLamps } from "./android.mjs";
+import { Unreachable, ideasOf, latestOf, publishLink, removeFile, removeIdea, removeLink, sendFile } from "./link.mjs";
+import { defaultRoute, homeNetwork, neighbours, samsungAt, subnetOn, tvsIn } from "./network.mjs";
+import { PUBLISHER, identityName, keptSigner, namesOf, packageOf, versionAfter } from "./msix.mjs";
+import { tile } from "./png.mjs";
+import { Problem } from "./state.mjs";
+
+/** A number of seconds a call was given, within what it may take. */
+const seconds = (given, standard, most = 10) => Math.min(Math.max(Number(given) > 0 ? Number(given) : standard, 0.5), most);
+
+const text = (given, name) => {
+  if (typeof given[name] !== "string" || !given[name]) throw new Error(`the call needs "${name}"`);
+  return given[name];
+};
+
+/** Every file in a folder, by its path from the folder's top, in a settled order. A link is never followed: it's refused. */
+function filesIn(folder) {
+  const files = [];
+  const walk = (at, prefix) => {
+    for (const name of readdirSync(at).sort()) {
+      const file = join(at, name), kind = lstatSync(file);
+      if (kind.isSymbolicLink()) throw new Problem(`${prefix}${name} is a shortcut to another file. Put the file itself in its place`);
+      if (kind.isDirectory()) walk(file, `${prefix}${name}/`);
+      else if (kind.isFile()) files.push([prefix + name, readFileSync(file)]);
+    }
+  };
+  walk(folder, "");
+  return files;
+}
+
+/** Written whole or not at all: beside its place, then moved in. */
+function write(file, bytes, mode) {
+  mkdirSync(dirname(file), { recursive: true });
+  const beside = `${file}.writing`;
+  writeFileSync(beside, bytes, mode ? { mode } : undefined);
+  renameSync(beside, file);
+}
+
+/**
+ * The runner for an integration's device, as Lamp's app hands it over: the integration (its JSON), the device (its
+ * id, name and address), the values to fill in (what the person typed among them, kept by Lamp's app), the file its
+ * certificates are kept in, and where a key it gives is kept. `event` tells whoever asked each time the device is
+ * waited on; `stopped` ends the run.
+ */
+function runnerOf(given, { stopped, event = () => {} } = {}) {
+  if (typeof given.integration?.id !== "string" || typeof given.device?.id !== "string") throw new Error('the call needs "integration" and "device"');
+  return new Runner({ integration: given.integration, device: { id: given.device.id, name: String(given.device.name ?? "The device"), address: given.device.address },
+    values: given.values ?? {}, pins: pinsAt(text(given, "pins")), keyFile: typeof given.keyFile === "string" ? given.keyFile : undefined,
+    stopped, onWaiting: () => event({ waiting: true }) });
+}
+
+/** What a sequence gave back, as Lamp's app reads it: a picture in base64, and the cookies its next part sends back. */
+const outcomeOf = (outcome) => ({ ...outcome, picture: outcome.picture ? Buffer.from(outcome.picture).toString("base64") : null });
+
+/** A shared link as Lamp's app keeps it: its id and secret, and the site it's on. */
+const linkOf = (given) => ({ id: text(given, "id"), secret: text(given, "secret") });
+const siteOf = (given) => text(given, "site").replace(/\/+$/, "");
+
+/** Lamp's app's Android, handed over with every adb call: its tools list, folders and environment (its own adb server and key). */
+const androidFor = (given) => useLamps(given.lamp ?? {});
+const serialOf = (given) => text(given, "serial");
+
+export const CALLS = {
+  /** One adb command for Lamp's app (`args` after the serial), with `input` on adb's input when given: what it said. */
+  async adb(given) {
+    androidFor(given);
+    return adbCommand(Array.isArray(given.args) ? given.args.map(String) : [], { serial: typeof given.serial === "string" ? given.serial : undefined,
+      timeout: Math.round((Number(given.timeout) > 0 ? Number(given.timeout) : 60) * 1000), input: typeof given.input === "string" ? given.input : undefined });
+  },
+  /** The devices adb can see, each with what it says of itself when it's ready, and what adb's search sees on the network. */
+  async androidDevices(given) { androidFor(given); return deviceListing(); },
+  /** adb's listing read into rows, for what Lamp's app was handed some other way. */
+  async androidRows(given) { return { rows: rowsOf(text(given, "listing")) }; },
+  /** What one device says of itself now. */
+  async androidProperties(given) { androidFor(given); return { properties: await deviceProperties(serialOf(given)) }; },
+  async androidConnect(given) { androidFor(given); return { connected: await connectTo(text(given, "target")) }; },
+  /** Pairs with a device by its code, which comes on the call's input and goes on adb's. */
+  async androidPair(given) { androidFor(given); return { pairing: await pairWith(text(given, "host"), Number(given.port), text(given, "code")) }; },
+  async androidInstallApp(given) { androidFor(given); await installApk(serialOf(given), text(given, "apk"), text(given, "package")); return {}; },
+  async androidTell(given) { androidFor(given); return { problem: await tellApp(serialOf(given), text(given, "package"), given.values ?? {}) }; },
+  async androidSaveState(given) { androidFor(given); return { saved: await saveState(serialOf(given), text(given, "package")) }; },
+  async androidLaunch(given) { androidFor(given); return { pid: await launchApp(serialOf(given), text(given, "package")) }; },
+  /** Whether the app runs on the device: running (with its process), gone, or unreachable. With `said`, what pidof said, read without asking. */
+  async androidProcess(given) {
+    if (given.said) return processIn(given.said);
+    androidFor(given);
+    return processOf(serialOf(given), text(given, "package"));
+  },
+  /** The screen as a PNG in base64, a pixel to a point by the device's density. */
+  async androidScreenshot(given) {
+    androidFor(given);
+    const png = await screenshotOf(serialOf(given), given.density);
+    return { png: png ? png.toString("base64") : null };
+  },
+  async androidDisplaySize(given) { androidFor(given); return { size: await displaySizeOf(serialOf(given)) }; },
+  /** The screen's dump, as `uiautomator dump` gave it (`said`), read into what's on it, in points at `scale`; null items when it held no dump. */
+  async androidScreenItems(given) {
+    const xml = dumpIn(text(given, "said"));
+    return { items: xml ? screenItems(xml, Number(given.scale) > 0 ? Number(given.scale) : 1) : null };
+  },
+
+
+  /**
+   * Downloads whichever of Android's tools Lamp's app is missing, into its tools folder, as its tools list says (each
+   * archive checked against what its maker publishes, then Google's packages through its own package manager, which
+   * accepts Google's terms for them: only when the person asked). With `emulator`, the emulator and its phone's image
+   * too; with `tv`, the TV's image. `lamp` is Lamp's app's tools list, folders and environment. Tells how far along it
+   * is (`part`, 0 to 1) and what it's doing (`said`) as it goes; answers which tools are there.
+   */
+  async androidInstall(given, how = {}) {
+    useLamps(given.lamp ?? {});
+    return { there: await installTools({ emulator: given.emulator === true, tv: given.tv === true,
+      said: (line) => how.event?.({ said: line }), progress: (part) => how.event?.({ part }) }) };
+  },
+
+  /** Makes Lamp's app's emulator of a kind ("phone" or "tv") from its downloaded system image. */
+  async androidMakeEmulator(given) {
+    useLamps(given.lamp ?? {});
+    if (given.kind !== "phone" && given.kind !== "tv") throw new Error('the call needs "kind": "phone" or "tv"');
+    await makeEmulator(given.kind);
+    return { there: toolsThere() };
+  },
+
+
+  /**
+   * Shares a wish's link, or changes what it shows (`earlier`: its id and secret), on `site`, with `body` as the site
+   * takes it. Its id, address and secret.
+   */
+  async linkPublish(given) {
+    const earlier = given.earlier && typeof given.earlier.id === "string" ? given.earlier : null;
+    return publishLink({ site: siteOf(given), body: given.body ?? {}, earlier });
+  },
+
+  /** What a followed link has now, asked with nothing of the person's; `latest` null when it can't be asked or is gone. */
+  async linkLatest(given) {
+    return { latest: await latestOf({ site: siteOf(given), id: text(given, "id") }) };
+  },
+
+  /** The link's file (or with `page`, its playable page), from a file of Lamp's at `file`, sent in parts. */
+  async linkUpload(given, how = {}) {
+    return { version: await sendFile({ site: siteOf(given), link: linkOf(given), bytes: readFileSync(text(given, "file")), page: given.page === true,
+      said: (line) => how.event?.({ said: line }) }) };
+  },
+
+  /** Takes the link's file away (with `page`, only its page). */
+  async linkRemoveFile(given) {
+    await removeFile({ site: siteOf(given), link: linkOf(given), page: given.page === true });
+    return {};
+  },
+
+  /** The ideas sent to the link that are still open. */
+  async linkIdeas(given) {
+    return { ideas: await ideasOf({ site: siteOf(given), link: linkOf(given) }) };
+  },
+
+  /** Lets an idea go; with `built` it's in, and the site writes to whoever asked to hear. */
+  async linkRemoveIdea(given) {
+    return removeIdea({ site: siteOf(given), link: linkOf(given), n: Number(given.n), built: given.built === true });
+  },
+
+  /** Takes the link down. */
+  async linkRemove(given) {
+    await removeLink({ site: siteOf(given), link: linkOf(given) });
+    return {};
+  },
+
+
+  /**
+   * One part of an integration's sequence on a device (`sequence`: its requests, waits and probes; what only Lamp's
+   * app does, a command on the device or a sign-in page, is between parts), with `cookies` from the part before. The
+   * settings it changes for itself (`restore`) come back in `changed`, which Lamp's app hands to `putBack` once it's
+   * done with them, or they're put back as the part ends when it asks for that (`putBack: true`).
+   */
+  async run(given, how = {}) {
+    const runner = runnerOf(given, how), changed = Array.isArray(given.changed) ? given.changed : [], before = changed.length;
+    try {
+      const outcome = await runner.run(Array.isArray(given.sequence) ? given.sequence : [], { extra: given.extra ?? {}, files: given.files ?? {}, changed, cookies: given.cookies ?? {} });
+      if (given.putBack === true) await runner.putBack(changed);
+      return { outcome: outcomeOf(outcome), changed };
+    } catch (error) {
+      // A part that fails puts back what it changed itself: the answer that says so carries no settings to hand back.
+      await runner.putBack(changed.splice(before));
+      throw error;
+    }
+  },
+
+  /** Puts back what parts of a sequence changed for themselves (`changed`, as `run` gave it), last first: the settings it couldn't. */
+  async putBack(given, how = {}) {
+    return { missed: await runnerOf(given, how).putBack(Array.isArray(given.changed) ? given.changed : []) };
+  },
+
+  /**
+   * Opens an app just put on the device: `launch`, then `running` until it's seen running, launched again while the
+   * device refuses or doesn't open it, up to `tries` launches. Whether it opened, whether it was ever launched, and
+   * what the device last refused with.
+   */
+  async open(given, how = {}) {
+    const changed = Array.isArray(given.changed) ? given.changed : [];
+    const opened = await runnerOf(given, how).open(given.launch ?? [], given.running ?? null, { extra: given.extra ?? {}, changed, tries: Number.isInteger(given.tries) ? given.tries : 8 });
+    return { ...opened, refused: opened.refused ?? null, changed };
+  },
+
+  /** What a check of a setup's `conditions` finds on the device now: holds, waiting, away or rejected, with why and what it read. */
+  async check(given, how = {}) {
+    return runnerOf(given, how).evaluate(Array.isArray(given.conditions) ? given.conditions : []);
+  },
+
+  /**
+   * A signed Windows package (msix.mjs) of the files in `payload`, a folder Lamp's app laid out, written to `out`, with
+   * the certificate a device installs beside it at `certificate`. The package is named for the app (`slug`) and is a
+   * newer version than `after`, the last one made; `entry` is what it starts ("webHost", {page} or {program}), `icon`
+   * a picture of the app for its tiles, and `signer` the folder lamp's key for packages is kept in, made the first time.
+   */
+  msix(given) {
+    const entry = given.entry === "webHost" || typeof given.entry?.page === "string" || typeof given.entry?.program === "string" ? given.entry : null;
+    if (!entry) throw new Error('the call needs "entry": "webHost", {page} or {program}');
+    const identity = { name: identityName(text(given, "slug")), publisher: PUBLISHER, version: versionAfter(typeof given.after === "string" ? given.after : undefined) };
+    if (typeof given.architecture === "string") identity.architecture = given.architecture;
+    let icon = null;
+    if (typeof given.icon === "string") { try { icon = readFileSync(given.icon); } catch { /* the tile's color alone */ } }
+    const payload = filesIn(text(given, "payload")), signer = keptSigner(text(given, "signer"));
+    const made = packageOf({ payload, displayName: text(given, "displayName"), identity, entry, logo: (width, height) => tile(icon, width, height), signer });
+    write(text(given, "out"), made);
+    write(text(given, "certificate"), signer.certificate);
+    return { identity, ...namesOf(identity), bytes: made.length, files: payload.length };
+  },
+
+  /**
+   * One request of an integration's to a device (devices.mjs's `send`, with every guard it has): `request` as the
+   * integration writes one, to the device at `address`, with `values` filled in (what the person typed for the device
+   * among them, which is why this comes on standard input), `files` it may send by path, and `pins`, the file the
+   * device's certificates are kept in, without which nothing secret goes over HTTPS. The answer's body is in base64.
+   */
+  async send(given, { stopped } = {}) {
+    const answer = await send(given.request ?? {}, text(given, "address"), given.values ?? {}, {
+      files: given.files ?? {}, pins: typeof given.pins === "string" ? pinsAt(given.pins) : undefined,
+      timeout: Math.round((Number(given.timeout) > 0 ? Number(given.timeout) : 30) * 1000), stopped,
+    });
+    return { status: answer.status, body: answer.body.toString("base64"), cookies: answer.cookies, certificate: answer.certificate?.toString("base64") ?? null };
+  },
+
+  /**
+   * One look at the home network for the `integrations` Lamp's app has (each as its JSON): every answer to a search
+   * for everything, what each integration found and read of its devices, with `unknown` the devices none of them
+   * knows, read from their own descriptions, and with `tvs` what each Samsung or LG TV that answered says of itself.
+   * Which of those Lamp keeps, and what it called them, is Lamp's app's.
+   */
+  async look(given) {
+    const list = (Array.isArray(given.integrations) ? given.integrations : []).filter((integration) => typeof integration?.id === "string");
+    const answers = await ssdp("ssdp:all", seconds(given.seconds, 2.5));
+    const [seen, tvs] = await Promise.all([searchNetwork({ integrations: list, answers, unknown: given.unknown === true }), given.tvs === true ? tvsIn(answers) : []]);
+    return { ...seen, tvs };
+  },
+
+  /** What a Samsung TV at `address` says of itself now, as the look reads it; null when it doesn't answer as one. */
+  async tv(given) {
+    return { tv: await samsungAt(text(given, "address")) };
+  },
+
+  /**
+   * Everything on this computer's subnet besides what the look finds: each host with its hardware address and its
+   * Bonjour services, and which subnet was swept.
+   */
+  async network(given) {
+    return homeNetwork({ seconds: seconds(given.seconds, 3) });
+  },
+
+  /**
+   * The network as it is now, read with nothing sent: this computer's neighbor table (each neighbor's IPv4 address
+   * and hardware address), its gateway, and the subnet a sweep would take.
+   */
+  async neighbours() {
+    const route = await defaultRoute();
+    return { table: await neighbours(), gateway: route?.gateway ?? null, subnet: route ? subnetOn(route.interface) : null };
+  },
+
+  /** A search of the home network for one search target, for a few seconds: every answer. */
+  async search(given) {
+    return { answers: await ssdp(typeof given.target === "string" ? given.target : "ssdp:all", seconds(given.seconds, 2)) };
+  },
+
+  /**
+   * Whether the device at `address` is there now, as a step's check asks: it takes a connection on a port (`tcp`), it
+   * answers a search for a target (`ssdp`), or it offers a Bonjour service (`bonjour`).
+   */
+  async probe(given) {
+    const address = text(given, "address");
+    if (Number.isInteger(given.tcp)) return { present: await answersOn(address, given.tcp, { timeout: seconds(given.seconds, 3) * 1000 }) };
+    if (typeof given.ssdp === "string") return { present: (await ssdp(given.ssdp, seconds(given.seconds, 2))).some((answer) => answer.address === address) };
+    if (typeof given.bonjour === "string") return { present: (await bonjour(given.bonjour, seconds(given.seconds, 3))).some((found) => found.address === address) };
+    throw new Error('the call needs "tcp", "ssdp" or "bonjour"');
+  },
+};
+
+/** A problem as Lamp's app shows one: a sentence, in which lamp is Lamp. */
+const sentence = (words) => `${words[0].toUpperCase()}${words.slice(1)}${/[.!?]$/.test(words) ? "" : "."}`.replace(/\blamp\b/g, "Lamp");
+
+/**
+ * What went wrong, as the answer says it: a problem the person can put right, with its kind where Lamp's app does
+ * something about that kind (a certificate that changed, a device that's away); null for anything else, lamp's own fault.
+ */
+function problemOf(error) {
+  if (!(error instanceof Problem)) return null;
+  const said = { problem: sentence(error.message) };
+  if (error instanceof Refused) said.kind = error.kind;
+  else if (error instanceof Rejected) said.kind = "rejected";
+  else if (error instanceof StillWorking) said.kind = "still-working";
+  else if (error instanceof OffNetwork) said.kind = "off-network";
+  else if (error instanceof Unreachable) said.kind = "unreachable";
+  else if (error instanceof Away) Object.assign(said, { kind: "away", code: error.code ?? null, timedOut: error.timedOut });
+  if (Number.isInteger(error.status)) said.status = error.status;
+  return said;
+}
+
+/** One call, run to its end, as a single run of this file. */
+async function once(name) {
+  const call = CALLS[name];
+  if (!call) throw new Error(`lamp has no call named "${name ?? ""}"`);
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const given = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+  try {
+    console.log(JSON.stringify({ done: await call(given) }));
+  } catch (error) {
+    const said = problemOf(error);
+    if (!said) throw error;
+    console.log(JSON.stringify(said));
+    process.exitCode = 1;
+  }
+}
+
+/** Calls answered as they come, for as long as there's someone to ask. */
+async function serve() {
+  const say = (line) => process.stdout.write(JSON.stringify(line) + "\n");
+  const under = new Map();
+  const answer = async (line) => {
+    let asked;
+    try { asked = JSON.parse(line); } catch { return; }
+    if (asked?.stop !== undefined) return void under.get(asked.stop)?.abort();
+    const id = asked?.id, call = CALLS[asked?.call], stopping = new AbortController();
+    under.set(id, stopping);
+    try {
+      if (!call) throw new Error(`lamp has no call named "${asked?.call ?? ""}"`);
+      say({ id, done: await call(asked.given ?? {}, { stopped: stopping.signal, event: (said) => say({ id, event: said }) }) });
+    } catch (error) {
+      say({ id, ...(problemOf(error) ?? { failed: String(error?.stack ?? error) }) });
+    } finally { under.delete(id); }
+  };
+  let waiting = [];
+  for await (const chunk of process.stdin) {
+    let from = 0;
+    for (let end = chunk.indexOf(10, from); end >= 0; end = chunk.indexOf(10, from)) {
+      const line = Buffer.concat([...waiting, chunk.subarray(from, end)]).toString("utf8");
+      waiting = [];
+      from = end + 1;
+      if (line.trim()) answer(line);
+    }
+    if (from < chunk.length) waiting.push(chunk.subarray(from));
+  }
+  // Nobody is left to hear an answer.
+  process.exit(0);
+}
+
+const here = () => { try { return realpathSync(process.argv[1] ?? "") === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } };
+if (here()) await (process.argv[2] === "--serve" ? serve() : once(process.argv[2]));