@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/cli/state.mjs

@@ -0,0 +1,173 @@
+// 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";
+
+/**
+ * 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; }
+}

package/cli/update.mjs

@@ -0,0 +1,57 @@
+// Whether a newer lamp is out, for a lamp installed from npm (@lampdotdev/lamp). The copy in Lamp's app updates with
+// Lamp (Sparkle) and a checkout with its repository, so neither asks. At most once a day a process of its own asks npm's
+// registry, without holding up the command, and keeps what it heard; the next command says so in one line, once a day,
+// with the command that updates it. lamp never updates itself: a global install is the person's.
+
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NAME = "@lampdotdev/lamp";
+const DAY = 24 * 60 * 60 * 1000;
+const here = dirname(fileURLToPath(import.meta.url));
+const cache = () => join(process.env.LAMP_DEV_HOME ? dirname(process.env.LAMP_DEV_HOME) : join(homedir(), ".lamp"), "update.json");
+
+/** Whether this copy is one npm installed, and so one npm updates. */
+const fromNpm = () => here.includes(`${sep}node_modules${sep}@lampdotdev${sep}lamp${sep}`);
+
+const own = () => { try { return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version ?? null; } catch { return null; } };
+const read = () => { try { return JSON.parse(readFileSync(cache(), "utf8")); } catch { return {}; } };
+const keep = (state) => { try { mkdirSync(dirname(cache()), { recursive: true }); writeFileSync(cache(), JSON.stringify(state)); } catch {} };
+
+/** Whether version a is newer than b, by their numbers (a pre-release is older than its release). */
+export function newer(a, b) {
+  const parts = (version) => { const [main, pre] = String(version).split("-"); return { numbers: main.split(".").map(Number), pre: pre ?? null }; };
+  const x = parts(a), y = parts(b);
+  for (let i = 0; i < 3; i++) if ((x.numbers[i] || 0) !== (y.numbers[i] || 0)) return (x.numbers[i] || 0) > (y.numbers[i] || 0);
+  return y.pre !== null && x.pre === null;
+}
+
+/**
+ * The line to say, when there's a newer lamp than this one and it hasn't been said today; and a check of npm started
+ * in the background when the last is a day old. Nothing for a copy npm didn't install, in CI, or with
+ * LAMP_NO_UPDATE_CHECK set.
+ */
+export function updateNotice() {
+  if (!fromNpm() || process.env.CI || process.env.LAMP_NO_UPDATE_CHECK) return null;
+  const mine = own(), state = read(), now = Date.now();
+  if (!(state.checked > now - DAY)) {
+    try { spawn(process.execPath, [fileURLToPath(import.meta.url), "--check"], { detached: true, stdio: "ignore" }).unref(); } catch {}
+  }
+  if (!mine || !state.latest || !newer(state.latest, mine) || state.told > now - DAY) return null;
+  keep({ ...state, told: now });
+  return `lamp ${state.latest} is out (this is ${mine}): npm install -g ${NAME}`;
+}
+
+// The background check: npm's registry, a few seconds at most, and what it said kept for the next command.
+if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === "--check") {
+  const state = read();
+  keep({ ...state, checked: Date.now() });
+  try {
+    const answer = await fetch(`https://registry.npmjs.org/${NAME.replace("/", "%2F")}/latest`, { signal: AbortSignal.timeout(5000) });
+    const latest = answer.ok ? (await answer.json()).version : null;
+    if (typeof latest === "string" && /^\d+\.\d+\.\d+/.test(latest)) keep({ ...read(), checked: Date.now(), latest });
+  } catch {}
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@lampdotdev/lamp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.35.0",
+  "description": "Runs a web app or game from its folder and puts each saved change into the open page.",
+  "type": "module",
+  "bin": {
+    "lamp": "cli/lamp.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lampdotdev/Lamp.git",
+    "directory": "cli"
+  },
+  "homepage": "https://lamp.dev",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/site/lib/quota.js

@@ -0,0 +1,59 @@
+import { createHmac } from "node:crypto";
+
+// Expiring counters in Upstash, checked and incremented together, for the first-idea endpoints. A process-local
+// counter would reset whenever Vercel starts another instance. ARGV holds each key's limit, then each key's
+// lifetime in seconds, so one script serves every quota.
+export const quotaScript = `
+local n = #KEYS
+local retry = 0
+for i, key in ipairs(KEYS) do
+  if tonumber(redis.call('GET', key) or '0') >= tonumber(ARGV[i]) then
+    retry = math.max(retry, math.max(1, redis.call('TTL', key)))
+  end
+end
+if retry > 0 then return retry end
+for i, key in ipairs(KEYS) do
+  if redis.call('INCR', key) == 1 then redis.call('EXPIRE', key, tonumber(ARGV[n + i])) end
+end
+return 0
+`;
+
+// Increments one field of a day's tally after a per-IP check, so a script can't flood the numbers. The tally
+// keeps no text and no IP address, only counts, for about a year.
+export const tallyScript = `
+if tonumber(redis.call('GET', KEYS[1]) or '0') >= tonumber(ARGV[1]) then return 0 end
+if redis.call('INCR', KEYS[1]) == 1 then redis.call('EXPIRE', KEYS[1], 3600) end
+redis.call('HINCRBY', KEYS[2], ARGV[2], 1)
+redis.call('EXPIRE', KEYS[2], 34560000)
+return 1
+`;
+
+export function redis(env) {
+  // The names BUG_REPORTS.md has set by hand, else the ones the Upstash integration gives a project it's connected to.
+  const url = env.UPSTASH_REDIS_REST_URL || env.KV_REST_API_URL;
+  const token = env.UPSTASH_REDIS_REST_TOKEN || env.KV_REST_API_TOKEN;
+  if (!url || !token || new URL(url).protocol !== "https:") throw new Error("Limiter unavailable");
+  const scope = env.VERCEL_ENV === "production" ? "production" : "preview";
+  return { url, token, prefix: `lamp:first-idea:{${scope}}`, ipHash: (ip) => createHmac("sha256", token).update(ip).digest("hex") };
+}
+
+export async function evaluate(db, command, fetcher = fetch) {
+  const response = await fetcher(db.url, {
+    method: "POST", redirect: "error", signal: AbortSignal.timeout(3000),
+    headers: { Authorization: `Bearer ${db.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(command),
+  });
+  if (!response.ok) throw new Error("Limiter unavailable");
+  const body = await response.json();
+  if (body.error || !Number.isInteger(body.result) || body.result < 0) throw new Error("Limiter unavailable");
+  return body.result;
+}
+
+/** Seconds to wait before trying again, or 0 when the call may go ahead (and has been counted). */
+export async function reserve(db, ip, quotas, fetcher = fetch) {
+  const keys = quotas.map((q) => `${db.prefix}:${q.name}${q.perIP ? ":" + db.ipHash(ip) : ""}`);
+  return evaluate(db, ["EVAL", quotaScript, String(keys.length), ...keys,
+    ...quotas.map((q) => String(q.limit)), ...quotas.map((q) => String(q.seconds))], fetcher);
+}
+
+export const today = (now = new Date()) => now.toISOString().slice(0, 10);