menloapp 1.4.0

package/src/presentation.js

@@ -0,0 +1,57 @@
+export const PRESENTATION_PATH = "menloapp/app.json";
+export const MAX_PRESENTATION_BYTES = 16 * 1024;
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_VIDEO_BYTES = 50 * 1024 * 1024;
+
+function text(value, field, maximum, required = false) {
+  if (typeof value !== "string" || value.length > maximum || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value) || required && !value.trim()) {
+    throw new Error(`menloapp/app.json: ${field} must be ${required ? "nonempty " : ""}text of at most ${maximum} characters.`);
+  }
+  return value.trim();
+}
+
+export function mediaPath(value, video = false) {
+  if (typeof value !== "string" || value.length > 240 || !/^menloapp\/[A-Za-z0-9_./-]+$/.test(value) || value.split("/").some(part => !part || part === "." || part === "..") || !(video ? /\.mp4$/ : /\.(png|jpe?g)$/).test(value)) {
+    throw new Error(`Use a path inside menloapp/ ending in ${video ? ".mp4" : ".png or .jpg"}; URLs and parent paths are not supported.`);
+  }
+  return value;
+}
+
+/** Public presentation is deliberately small; build and identity are derived elsewhere. */
+export function validatePresentation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== 1) throw new Error("menloapp/app.json requires version: 1.");
+  for (const key of Object.keys(value)) if (!["version", "name", "subtitle", "description", "icon", "screenshots", "preview"].includes(key)) throw new Error(`Unknown menloapp/app.json field: ${key}`);
+  const name = text(value.name, "name", 100, true);
+  const subtitle = text(value.subtitle ?? "", "subtitle", 160);
+  const description = text(value.description ?? "", "description", 4000);
+  const icon = value.icon == null ? null : mediaPath(value.icon);
+  const screenshots = value.screenshots ?? [];
+  if (!Array.isArray(screenshots) || screenshots.length > 3 || new Set(screenshots).size !== screenshots.length) throw new Error("Choose up to three distinct screenshots in menloapp/app.json.");
+  let preview = null;
+  if (value.preview != null) {
+    const item = value.preview;
+    if (typeof item !== "object" || Array.isArray(item) || !["simulator", "device", "screen-recording"].includes(item.kind) || Object.keys(item).some(key => !["path", "kind", "source_commit"].includes(key))) throw new Error("Preview needs a path and kind: simulator, device, or screen-recording.");
+    if (item.source_commit != null && !/^[a-f0-9]{40}$/.test(item.source_commit)) throw new Error("Preview source_commit must be a full Git commit.");
+    preview = { path: mediaPath(item.path, true), kind: item.kind, ...(item.source_commit ? { source_commit: item.source_commit } : {}) };
+  }
+  return { version: 1, name, subtitle, description, icon, screenshots: screenshots.map(item => mediaPath(item)), preview };
+}
+
+export function presentationFiles(value) {
+  return [...(value.icon ? [value.icon] : []), ...value.screenshots, ...(value.preview ? [value.preview.path] : [])];
+}
+
+export function mediaType(file) {
+  return file.endsWith(".mp4") ? "video/mp4" : file.endsWith(".png") ? "image/png" : "image/jpeg";
+}
+
+export function validateMediaBytes(file, bytes) {
+  const type = mediaType(file);
+  const maximum = type === "video/mp4" ? MAX_VIDEO_BYTES : MAX_IMAGE_BYTES;
+  if (!bytes.length || bytes.length > maximum) throw new Error(`${file} exceeds the ${maximum / 1024 / 1024} MiB limit or is empty.`);
+  const valid = type === "image/png" ? bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+    : type === "image/jpeg" ? bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255
+    : bytes.length >= 12 && bytes.subarray(4, 8).toString("ascii") === "ftyp";
+  if (!valid) throw new Error(`${file} is not a supported ${type} file. Commit the actual media bytes, not a Git LFS pointer.`);
+  return type;
+}

package/src/project-presentation.js

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import { lstat, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PRESENTATION_PATH, MAX_PRESENTATION_BYTES, MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, validatePresentation, presentationFiles, validateMediaBytes } from "./presentation.js";
+
+export function projectRoot(directory) {
+  try { return execFileSync("git", ["-C", directory, "rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
+  catch { throw new Error("Run menloapp from your app's Git repository."); }
+}
+
+export async function setupPresentation(root, name = path.basename(root)) {
+  const directory = path.join(root, "menloapp");
+  await mkdir(directory, { recursive: true });
+  if (!(await lstat(directory)).isDirectory()) throw new Error("menloapp/ must be a real directory, not a symbolic link.");
+  try {
+    await writeFile(path.join(root, PRESENTATION_PATH), JSON.stringify(validatePresentation({ version: 1, name, subtitle: "", description: "", icon: null, screenshots: [], preview: null }), null, 2) + "\n", { flag: "wx" });
+  } catch (error) { if (error.code === "EEXIST") return false; throw error; }
+  const guide = `# Your public app page\n\nEdit app.json, then commit and push this folder with your app.\nMENLO reads it and the selected assets from the same public Git commit.\n\nAdd your real icon and up to three screenshots (PNG/JPEG, at most 10 MiB each).\nSet icon to "menloapp/icon.png" and screenshots to paths such as\n["menloapp/screenshot-1.png", "menloapp/screenshot-2.png", "menloapp/screenshot-3.png"].\nNo sample artwork is published as if it were your app.\n\nRun menloapp deploy --record to build and launch this app in an already booted\nSimulator and record a short walkthrough. Review the recording, commit and push,\nthen deploy again. To use your own MP4 (at most 50 MiB), set preview to\n{"path":"menloapp/preview.mp4","kind":"screen-recording"}.\n\nUse normal Git files, not Git LFS pointers. Never put secrets or private captures\nin this public folder. If you install menloapp as a local npm dependency, ignore /node_modules/ in your\nproject .gitignore and commit package.json plus the lockfile.\nAn npm install runs no setup or upload scripts.\n`;
+  try { await writeFile(path.join(directory, "README.md"), guide, { flag: "wx" }); }
+  catch (error) { if (error.code !== "EEXIST") throw error; }
+  return true;
+}
+
+export async function readCommittedPresentation(root, commit) {
+  const git = (...args) => execFileSync("git", ["-C", root, ...args], { maxBuffer: MAX_VIDEO_BYTES + 1024, stdio: ["ignore", "pipe", "pipe"] });
+  const entries = new Map(git("ls-tree", "-r", "-z", commit, "--", "menloapp/").toString("utf8").split("\0").filter(Boolean).map(line => { const [info, file] = line.split("\t"); return [file, info.split(" ")[0]]; }));
+  if (!entries.has(PRESENTATION_PATH)) return null;
+  const read = (file, maximum) => {
+    if (!["100644", "100755"].includes(entries.get(file))) throw new Error(`${file} must be a committed regular file; links are not supported.`);
+    const size = Number(git("cat-file", "-s", `${commit}:${file}`).toString());
+    if (size > maximum) throw new Error(`${file} exceeds its supported size.`);
+    return git("show", `${commit}:${file}`);
+  };
+  let value;
+  try { value = JSON.parse(read(PRESENTATION_PATH, MAX_PRESENTATION_BYTES).toString("utf8")); }
+  catch (error) { throw new Error(`Cannot read ${PRESENTATION_PATH}: ${error.message}`); }
+  const presentation = validatePresentation(value);
+  for (const file of presentationFiles(presentation)) validateMediaBytes(file, read(file, file.endsWith(".mp4") ? MAX_VIDEO_BYTES : MAX_IMAGE_BYTES));
+  return presentation;
+}
+
+export async function initPresentation(args) {
+  if (args.includes("--help")) { console.log("menloapp init [path]\n\nCreate menloapp/app.json and instructions for your public app page."); return 0; }
+  if (args.length > 1 || args[0]?.startsWith("-")) throw new Error("Usage: menloapp init [path]");
+  const root = projectRoot(args[0] || ".");
+  const created = await setupPresentation(root);
+  console.log(`${created ? "Created" : "Keeping existing"} ${PRESENTATION_PATH}.\nAdd your app's name, subtitle, description, icon and up to three screenshots.\nReview, commit and push menloapp/, then run menloapp deploy.`);
+  return 0;
+}

package/src/record.js

@@ -0,0 +1,79 @@
+import { execFileSync, spawn } from "node:child_process";
+import { lstat, mkdir, mkdtemp, readFile, rm, writeFile, copyFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PRESENTATION_PATH, validatePresentation, validateMediaBytes } from "./presentation.js";
+
+export function selectSimulator(devices, requested) {
+  const booted = Object.entries(devices).filter(([runtime]) => /ios/i.test(runtime)).flatMap(([, items]) => items).filter(device => device.state === "Booted" && device.isAvailable !== false && (device.deviceTypeIdentifier?.includes(".iPhone-") || device.name?.startsWith("iPhone")));
+  const selected = requested ? booted.filter(device => device.udid === requested) : booted;
+  if (selected.length !== 1) throw new Error("Open your intended iPhone Simulator first. If several are running, choose --simulator UDID (xcrun simctl list devices booted).");
+  return selected[0];
+}
+
+async function build(args, directory, log) {
+  log("Building your app for Simulator. This can take several minutes; recording starts after the app launches.");
+  await new Promise((resolve, reject) => {
+    const child = spawn("xcodebuild", args, { cwd: directory, stdio: ["ignore", "inherit", "inherit"] });
+    const timer = setTimeout(() => { child.kill("SIGTERM"); }, 5 * 60_000);
+    child.once("error", error => { clearTimeout(timer); reject(error); });
+    child.once("exit", code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error("Simulator build did not finish successfully. Fix the Xcode error, then run menloapp deploy --record again.")); });
+  });
+}
+
+export async function recordExperience(root, project, options, ui) {
+  if (process.platform !== "darwin") throw new Error("Recording requires macOS, Xcode, and a running iPhone Simulator.");
+  const run = (args) => execFileSync("xcrun", ["simctl", ...args], { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
+  const device = selectSimulator(JSON.parse(run(["list", "devices", "booted", "--json"])).devices, options.simulator);
+  const destination = path.join(root, "menloapp", `preview-${project.commit.slice(0, 12)}-${Date.now()}.mp4`);
+  const manifestPath = path.join(root, PRESENTATION_PATH);
+  if (!(await lstat(path.dirname(manifestPath))).isDirectory() || !(await lstat(manifestPath)).isFile()) throw new Error("The public presentation must use regular files, not links.");
+  const before = await readFile(manifestPath, "utf8");
+  const presentation = validatePresentation(JSON.parse(before));
+  const temporary = await mkdtemp(path.join(os.tmpdir(), "menloapp-record-"));
+  try {
+    const source = path.join(temporary, "source");
+    await mkdir(source);
+    const archive = path.join(temporary, "source.tar");
+    execFileSync("git", ["-C", root, "archive", "--format=tar", "--output", archive, project.commit], { timeout: 30_000 });
+    execFileSync("tar", ["-xf", archive, "-C", source], { timeout: 30_000 });
+    const args = [project.project.endsWith(".xcworkspace") ? "-workspace" : "-project", path.join(source, project.project), "-scheme", project.scheme, "-configuration", "Debug", "-sdk", "iphonesimulator", "-destination", `id=${device.udid}`, "-derivedDataPath", path.join(temporary, "build"), "CODE_SIGNING_ALLOWED=NO"];
+    await build([...args, "build"], source, ui.log);
+    const settings = JSON.parse(execFileSync("xcodebuild", [...args, "-showBuildSettings", "-json"], { cwd: source, encoding: "utf8", timeout: 60_000, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }));
+    const apps = settings.map(item => item.buildSettings).filter(item => item.WRAPPER_EXTENSION === "app" && item.PRODUCT_BUNDLE_IDENTIFIER);
+    if (apps.length !== 1) throw new Error("The scheme builds several apps. Select a scheme that builds just the app you want to record.");
+    const app = apps[0];
+    run(["install", device.udid, path.join(app.TARGET_BUILD_DIR, app.FULL_PRODUCT_NAME)]);
+    run(["launch", "--terminate-running-process", device.udid, app.PRODUCT_BUNDLE_IDENTIFIER]);
+    spawn("open", ["-a", "Simulator"], { stdio: "ignore" }).unref();
+    ui.log(`Recording ${project.name} in ${device.name} for ${options.seconds} seconds. Use the app now; only this Simulator's screen is recorded.`);
+    const movie = path.join(temporary, "preview.mp4");
+    await new Promise((resolve, reject) => {
+      const child = spawn("xcrun", ["simctl", "io", device.udid, "recordVideo", "--codec=h264", movie], { stdio: ["ignore", "ignore", "pipe"] });
+      let timer;
+      let started = false;
+      let cancelled = false;
+      let diagnostic = "";
+      const cancel = () => { cancelled = true; child.kill("SIGINT"); };
+      process.once("SIGINT", cancel);
+      const deadline = setTimeout(() => child.kill("SIGKILL"), (options.seconds + 30) * 1000);
+      child.stderr.on("data", chunk => {
+        diagnostic = (diagnostic + chunk.toString()).slice(-1024);
+        if (!started && diagnostic.includes("Recording started")) { started = true; timer = setTimeout(() => child.kill("SIGINT"), options.seconds * 1000); }
+      });
+      const cleanup = () => { clearTimeout(timer); clearTimeout(deadline); process.removeListener("SIGINT", cancel); };
+      child.once("error", error => { cleanup(); reject(error); });
+      child.once("exit", code => { cleanup(); !cancelled && started && code === 0 ? resolve() : reject(new Error("Recording did not finish. Your public presentation was not changed.")); });
+    });
+    const bytes = await readFile(movie);
+    validateMediaBytes(destination, bytes);
+    if (await readFile(manifestPath, "utf8") !== before) throw new Error("app.json changed while recording. Run recording again after saving your edits.");
+    await copyFile(movie, destination, constants.COPYFILE_EXCL);
+    // Recording describes the source that was actually built, even when a later
+    // commit adds the resulting video to the public presentation.
+    presentation.preview = { path: path.relative(root, destination), kind: "simulator", source_commit: project.commit };
+    await writeFile(manifestPath, JSON.stringify(presentation, null, 2) + "\n");
+    ui.print(`Saved ${presentation.preview.path}\nReview the video, commit and push menloapp/, then run menloapp deploy to share it.\nThis is a Simulator recording; it is not evidence of an iPhone installation.`);
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}

package/src/semver.js

@@ -0,0 +1,16 @@
+const EXACT = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export function parseVersion(value) {
+  const match = EXACT.exec(value);
+  if (!match) throw new Error("version must be an exact stable semantic version");
+  return match.slice(1).map(Number);
+}
+
+export function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}

package/src/start.js

@@ -0,0 +1,9 @@
+import { delegate } from "./native.js";
+
+export function startProduct(run = delegate, write = console.log) {
+  write("Starting TOHSENO…");
+  const service = run(["service", "install"]);
+  if (service !== 0) return service;
+  write("Opening TOHSENO…");
+  return run(["studio"]);
+}