menloapp 1.4.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 TOHSENO contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,120 @@
+# MENLO (`menloapp`)
+
+Share your iOS app from a public GitHub repository:
+
+```sh
+npm i -g menloapp
+cd YourApp
+menloapp init
+# Edit menloapp/app.json, then commit and push your changes.
+menloapp deploy
+```
+
+Deploy returns `https://menloapp.lol/your-app`. Subsequent pushes update the same
+page automatically. GitHub supplies repository identity, commits, source and
+feedback. MENLO checks that you have write access before registering the app.
+There is no gas, wallet, or Companion publication approval on this path.
+
+You can also install it as a project dependency:
+
+```sh
+npm install menloapp
+npx menloapp init
+# Review, commit and push package.json, package-lock.json and menloapp/.
+npx menloapp deploy
+```
+
+For a local dependency, keep `/node_modules/` in your project’s `.gitignore`;
+commit the package manifests and your public `menloapp/` folder.
+
+Installation runs no setup, download or upload scripts. `menloapp init` creates
+`menloapp/app.json` and a short README without replacing existing files. The
+first deploy creates that folder if it is missing, then asks you to review,
+commit and push it. Node 20+ and Git are required. An existing `gh auth login`
+session works; a configured GitHub device flow is also supported.
+
+## Your app page
+
+The website reads this file from the same exact Git commit as its media:
+
+```json
+{
+  "version": 1,
+  "name": "Your App",
+  "subtitle": "A short reason to try it",
+  "description": "What the app does and who it helps.",
+  "icon": "menloapp/icon.png",
+  "screenshots": [
+    "menloapp/screenshot-1.png",
+    "menloapp/screenshot-2.png",
+    "menloapp/screenshot-3.png"
+  ],
+  "preview": null
+}
+```
+
+Put the real files at those paths before committing. An icon is optional
+(`null`), and zero to three PNG/JPEG screenshots are supported, up to 10 MiB per
+image. No placeholder icon or fake screenshot is inserted. Metadata limits:
+100 characters for the name, 160 for the subtitle, and 4,000 for the description.
+Descriptions support line breaks and are rendered as text.
+
+Files must be ordinary Git files inside `menloapp/`; symbolic links, external
+URLs and Git LFS pointers are not supported. Only files explicitly selected in
+`app.json` are served as presentation media. Media URLs contain the full commit,
+and the server checks the downloaded bytes against that commit's Git blob.
+Pages follow the default branch with a cache of up to 60 seconds. A recording
+can show an earlier app version; its recorded source commit stays visible.
+
+## Record an experience
+
+Open an iPhone Simulator, then:
+
+```sh
+menloapp deploy --record --seconds 20
+```
+
+This builds an isolated copy of the current committed source for that Simulator,
+launches the chosen app, and records its screen while you use it. It executes
+your project's normal Xcode build scripts. It does not use your physical phone
+or Apple signing identity. The duration is 3–60 seconds. With multiple booted
+Simulators, pass `--simulator UDID` from `xcrun simctl list devices booted`.
+
+The command writes a new MP4 and updates `app.json`, then stops for your review.
+Review the recording, commit and push `menloapp/`, and run `menloapp deploy` to
+publish its selection. The page labels it as a Simulator recording and shows
+the exact source commit used to build it. Recording is explicit; deploy does
+not silently record an app or publish private captures.
+
+You can supply an existing MP4 of up to 50 MiB instead:
+
+```json
+"preview": { "path": "menloapp/preview.mp4", "kind": "screen-recording" }
+```
+
+Use `"kind": "device"` for your own physical-device recording. These are
+maker-supplied descriptions, not installation attestations. H.264 MP4 gives
+broad browser playback support. Previews have playback controls and are not
+interactive versions of the app.
+
+## Deploy and try
+
+`menloapp deploy --project path/App.xcodeproj --scheme App --app-slug your-app`
+handles explicit project selection. Slugs use 2–64 lowercase letters, numbers
+and single hyphens. `--dry-run` checks local committed metadata without writing,
+authenticating or publishing. `--json` and noninteractive sessions do not prompt.
+`--name` supplies an initial scaffold name; committed `app.json` is authoritative.
+
+Recipients open the link in the MENLO Mac app, or run
+`menloapp github install your-app`. They review the exact source and build with
+Xcode and their own Apple signing identity for their paired intended iPhone.
+Build scripts can require `--approve-mac-review` after local review.
+
+Commands needing the native runtime retain the exact signed native 1.3.0
+manifest at `https://tohseno.com/releases/cli-1.3.0.json`; hashes, archive layout,
+and Apple signature checks remain unchanged. Deployment and recording run in
+Node directly. Existing `tohseno` and `menlo` commands belong to the earlier
+package; this package installs only `menloapp`, so it can coexist with them.
+Historical publication is available through `deploy --legacy-registry`.
+
+Development: `npm test`, `npm pack --dry-run`.

package/bin/tohseno.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { GUIDE, HELP, parseCommand, redact, suggestedCommand } from "../src/cli.js";
+import { NPM_CLI_VERSION, PRODUCT_VERSION } from "../src/constants.js";
+import { delegate, installedNative } from "../src/native.js";
+import { installAuthorizedNative } from "../src/installer.js";
+import { startProduct } from "../src/start.js";
+import { initPresentation } from "../src/project-presentation.js";
+import { deploy } from "../src/github.js";
+
+async function main() {
+  const raw = process.argv.slice(2);
+  if (raw[0] === "init") return initPresentation(raw.slice(1));
+  const commandIndex = raw[0] === "--json" ? 1 : 0;
+  const suggestion = suggestedCommand(raw[commandIndex]);
+  if (suggestion) throw new Error(`Unknown command: ${raw[commandIndex]}. Did you mean menloapp ${suggestion}?`);
+  if (raw[commandIndex] === "deploy" && !raw.includes("--legacy-registry")) {
+    return deploy([...raw.slice(0, commandIndex), ...raw.slice(commandIndex + 1)]);
+  }
+  const command = parseCommand(process.argv.slice(2));
+  if (command.kind === "help") { console.log(HELP); return 0; }
+  if (command.kind === "version") { console.log(`menloapp ${NPM_CLI_VERSION}`); return 0; }
+  if (command.kind === "guide") { console.log(GUIDE); return 0; }
+  if (process.platform !== "darwin") throw new Error("TOHSENO installs on macOS only.");
+  let installed = await installedNative(PRODUCT_VERSION);
+  if (command.kind === "doctor") {
+    const diagnosticNative = installed ?? await installedNative();
+    const macOS = spawnSync("/usr/bin/sw_vers", ["-productVersion"], { encoding: "utf8" });
+    const tools = spawnSync("/usr/bin/xcode-select", ["-p"], { encoding: "utf8" });
+    const xcode = spawnSync("/usr/bin/xcodebuild", ["-version"], { encoding: "utf8" });
+    console.log(`macOS: ${macOS.status === 0 ? macOS.stdout.trim() : "unknown"}`);
+    console.log(`architecture: ${process.arch}`);
+    console.log(`Node: ${process.version}`);
+    console.log(`Xcode command-line tools: ${tools.status === 0 ? "ready" : "not ready"}`);
+    console.log(`Xcode: ${xcode.status === 0 ? xcode.stdout.split("\n", 1)[0] : "not installed"}`);
+    if (!diagnosticNative) {
+      console.log("native TOHSENO: not installed");
+      console.log("release manifest: checked during install");
+      console.log("Local Workspace Service: unavailable until native install");
+      console.log("Companion and entitlement: unavailable until native install");
+      return 0;
+    }
+    return delegate(["doctor"]);
+  }
+  if (!installed) {
+    console.log("Installing the verified TOHSENO CLI runtime…");
+    await installAuthorizedNative();
+    installed = await installedNative(PRODUCT_VERSION);
+    if (!installed) throw new Error("the verified native release did not activate safely");
+  }
+  if (command.kind === "delegate") return delegate(command.args);
+  return startProduct();
+}
+
+main().then((code) => { process.exitCode = code; }).catch((error) => {
+  console.error(`menloapp: ${redact(error.message)}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "menloapp",
+  "version": "1.4.0",
+  "description": "MENLO: share living iOS apps from GitHub and try them on your own iPhone",
+  "type": "module",
+  "bin": {
+    "menloapp": "bin/tohseno.js"
+  },
+  "files": [
+    "bin/tohseno.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpfraneto/menloapp.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://menloapp.lol",
+  "bugs": {
+    "url": "https://github.com/jpfraneto/menloapp/issues"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:pack": "node test/pack-install.test.js"
+  }
+}

package/src/archive.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { access, lstat, mkdir, open, readFile, readdir, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const SAFE_PATH = /^[A-Za-z0-9._/-]+$/;
+
+export function validateArchivePaths(listing) {
+  const names = listing.split("\n").filter(Boolean);
+  if (!names.length || names.length > 100_000) throw new Error("native release archive has an invalid entry count");
+  for (const name of names) {
+    const normalized = name.replace(/^\.\//, "").replace(/\/$/, "");
+    if (!normalized || normalized.startsWith("/") || !SAFE_PATH.test(normalized)
+      || normalized.split("/").some((part) => !part || part === "." || part === "..")) {
+      throw new Error("native release archive contains an unsafe path");
+    }
+  }
+  return names;
+}
+
+export async function extractVerifiedArchive(archive, destination) {
+  const table = spawnSync("/usr/bin/tar", ["-tzf", archive], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+  if (table.status !== 0) throw new Error("native release archive could not be listed");
+  validateArchivePaths(table.stdout);
+  const verbose = spawnSync("/usr/bin/tar", ["-tvzf", archive], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  if (verbose.status !== 0 || verbose.stdout.split("\n").filter(Boolean).some((line) => !["-", "d"].includes(line[0]))) {
+    throw new Error("native release archive contains links or unsupported entries");
+  }
+  await mkdir(destination, { mode: 0o700 });
+  const extracted = spawnSync("/usr/bin/tar", ["-xzf", archive, "-C", destination, "--no-same-owner"], { encoding: "utf8" });
+  if (extracted.status !== 0) throw new Error("native release archive extraction failed");
+  const roots = (await readdir(destination)).filter((name) => !name.startsWith("."));
+  if (roots.length !== 1) throw new Error("native release archive must contain one root directory");
+  const root = path.join(destination, roots[0]);
+  if (!(await lstat(root)).isDirectory()) throw new Error("native release root is not a directory");
+  return root;
+}
+
+async function walk(root, current = root, output = []) {
+  for (const entry of await readdir(current, { withFileTypes: true })) {
+    const absolute = path.join(current, entry.name);
+    const relative = path.relative(root, absolute).split(path.sep).join("/");
+    const metadata = await lstat(absolute);
+    if (metadata.isSymbolicLink()) throw new Error("native release contains a symlink");
+    if (metadata.isDirectory()) await walk(root, absolute, output);
+    else if (metadata.isFile()) output.push(relative);
+    else throw new Error("native release contains an unsupported file");
+  }
+  return output;
+}
+
+export async function verifyReleaseTree(root, version, target) {
+  const release = JSON.parse(await readFile(path.join(root, "RELEASE.json"), "utf8"));
+  if (release.schema !== "tohseno.release/1" || release.version !== version || release.target !== target
+    || release.channel !== "stable" || release.prerelease !== false || release.dirty !== false) {
+    throw new Error("native RELEASE.json does not match the authorized release");
+  }
+  const manifestBytes = await readFile(path.join(root, "CHECKSUMS.sha256"));
+  const manifest = manifestBytes.toString("ascii");
+  if (!manifest.endsWith("\n")) throw new Error("native checksum manifest is not canonical");
+  const expected = new Map();
+  for (const line of manifest.trimEnd().split("\n")) {
+    const match = /^([0-9a-f]{64})  ([A-Za-z0-9._/-]+)$/.exec(line);
+    if (!match || match[2] === "CHECKSUMS.sha256" || expected.has(match[2])
+      || match[2].split("/").some((part) => !part || part === "." || part === "..")) {
+      throw new Error("native checksum manifest is invalid");
+    }
+    expected.set(match[2], match[1]);
+  }
+  const actual = (await walk(root)).filter((name) => name !== "CHECKSUMS.sha256").sort();
+  if (actual.length !== expected.size || actual.some((name, index) => name !== [...expected.keys()].sort()[index])) {
+    throw new Error("native checksum manifest does not cover the exact release tree");
+  }
+  for (const [name, digest] of expected) {
+    const bytes = await readFile(path.join(root, name));
+    if (createHash("sha256").update(bytes).digest("hex") !== digest) throw new Error("native release tree checksum differs");
+  }
+  const launcher = path.join(root, "bin", "tohseno");
+  const launcherMetadata = await stat(launcher);
+  if (!launcherMetadata.isFile() || (launcherMetadata.mode & 0o022) !== 0) {
+    throw new Error("native release launcher is missing or writable by another user");
+  }
+  await access(launcher, constants.X_OK);
+  const descriptor = await open(launcher, "r");
+  await descriptor.close();
+  return release;
+}

package/src/cli.js

@@ -0,0 +1,54 @@
+import { NPM_CLI_VERSION } from "./constants.js";
+
+export const HELP = `MENLO (menloapp ${NPM_CLI_VERSION})
+
+Usage:
+  menloapp init [path]            Create your public app metadata folder
+  menloapp deploy [path]          Connect a public GitHub app and get its link
+  menloapp deploy --record        Record the app in Simulator for review
+  menloapp github install <slug>  Build a GitHub app for your iPhone
+  menloapp open                   Open MENLO on your Mac
+  menloapp doctor                 Check this Mac
+  menloapp --version              Print the npm CLI version
+
+Commit and push your app and menloapp/ assets, then deploy. Its link follows
+GitHub's default branch. Testers use Xcode and their own Apple signing identity.`;
+
+export const GUIDE = `MENLO CLI ${NPM_CLI_VERSION} is installed.
+
+From your app's public GitHub repository:
+  cd /path/to/YourApp
+  menloapp init
+  # Edit menloapp/app.json, then commit and push.
+  menloapp deploy
+
+Share the link. Keep pushing code. Your testers choose when to update.
+Deploy guides you through GitHub sign-in and choosing an app if needed.`;
+
+export function suggestedCommand(value) {
+  if (!value || value === "deploy") return null;
+  const target = "deploy";
+  if (Math.abs(value.length - target.length) > 1) return null;
+  for (let i = 0; i < Math.max(value.length, target.length); i++) {
+    if (value[i] === target[i]) continue;
+    if (value.slice(i + 1) === target.slice(i + 1) || value.slice(i + 1) === target.slice(i) || value.slice(i) === target.slice(i + 1)) return target;
+    if (value[i] === target[i + 1] && value[i + 1] === target[i] && value.slice(i + 2) === target.slice(i + 2)) return target;
+    return null;
+  }
+  return null;
+}
+
+export function parseCommand(args) {
+  if (!args.length) return { kind: "guide", args: [] };
+  if (args.length === 1 && ["--help", "-h", "help"].includes(args[0])) return { kind: "help", args: [] };
+  if (args.length === 1 && ["--version", "-V"].includes(args[0])) return { kind: "version", args: [] };
+  if (args.length === 1 && ["open", "doctor"].includes(args[0])) return { kind: args[0], args: [] };
+  return { kind: "delegate", args };
+}
+
+export function redact(message) {
+  return String(message)
+    .replace(/([?&](?:token|claim|nonce|secret|key)=)[^&\s]+/gi, "$1[redacted]")
+    .replace(/\b(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+)\b/g, "[redacted]")
+    .replace(/\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9_-]+\b/g, "[redacted]");
+}

package/src/constants.js

@@ -0,0 +1,12 @@
+export const NPM_CLI_VERSION = "1.4.0";
+export const PRODUCT_VERSION = "1.3.0";
+export const MANIFEST_URL = "https://tohseno.com/releases/cli-1.3.0.json";
+export const MANIFEST_ORIGINS = new Set(["https://tohseno.com"]);
+export const ARTIFACT_ORIGINS = new Set([
+  "https://github.com",
+  "https://objects.githubusercontent.com",
+  "https://release-assets.githubusercontent.com",
+]);
+export const MAX_MANIFEST_BYTES = 64 * 1024;
+export const MAX_ARTIFACT_BYTES = 512 * 1024 * 1024;
+export const RELEASE_LAYOUT = "tohseno-user-release/2";

package/src/deploy-ui.js

@@ -0,0 +1,51 @@
+import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
+import process from "node:process";
+
+export function shellQuote(value) {
+  return /^[A-Za-z0-9_./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+  const child = spawn(command, args, { stdio: "ignore" });
+  child.on("error", () => {});
+  child.unref();
+}
+
+function ask(question) {
+  return new Promise((resolve, reject) => {
+    const reader = createInterface({ input: process.stdin, output: process.stderr });
+    let answered = false;
+    reader.on("close", () => { if (!answered) reject(new Error("Deploy cancelled. Run menloapp deploy when you are ready.")); });
+    reader.on("SIGINT", () => reader.close());
+    reader.question(question, answer => { answered = true; reader.close(); resolve(answer.trim()); });
+  });
+}
+
+export function deployUI(options) {
+  return {
+    interactive: !options.json && !options.dryRun && process.env.MENLO_NONINTERACTIVE !== "1" && Boolean(process.stdin.isTTY && process.stderr.isTTY),
+    log: options.json || options.dryRun ? () => {} : text => console.error(text),
+    print: text => console.log(text), ask, open: openBrowser,
+  };
+}
+
+export async function choose(ui, title, values, flag) {
+  if (values.length === 1) return values[0];
+  const choices = values.map((value, i) => `  ${i + 1}. ${value}`).join("\n");
+  if (!ui.interactive) throw new Error(`${title}\n${choices}\n\nRun menloapp deploy in a terminal to choose, or use ${flag} ${shellQuote(values[0])}.`);
+  ui.log(`\n${title}\n${choices}`);
+  while (true) {
+    const answer = await ui.ask(`Choose 1–${values.length}: `);
+    if (/^[1-9]\d*$/.test(answer) && Number(answer) <= values.length) return values[Number(answer) - 1];
+    ui.log(`Enter a number from 1 to ${values.length}.`);
+  }
+}
+
+export async function continueAfter(ui, message, question = "After fixing this, press Enter to continue (Ctrl+C to cancel): ") {
+  if (!ui.interactive) throw new Error(`${message}\n\nThen run menloapp deploy again.`);
+  ui.log(`\n${message}`);
+  await ui.ask(question);
+}

package/src/download.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { NPM_CLI_VERSION } from "./constants.js";
+import { validatedHttpsURL } from "./manifest.js";
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 3;
+
+async function fetchAllowlisted(url, allowedOrigins) {
+  let current = validatedHttpsURL(url, allowedOrigins);
+  for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+    const response = await fetch(current, {
+      redirect: "manual",
+      headers: { "user-agent": `tohseno-npm/${NPM_CLI_VERSION}` },
+    });
+    if (!REDIRECT_STATUSES.has(response.status)) return response;
+    if (redirects === MAX_REDIRECTS) throw new Error("release download has too many redirects");
+    const location = response.headers.get("location");
+    if (!location) throw new Error("release download redirect is missing its destination");
+    current = validatedHttpsURL(new URL(location, current).href, allowedOrigins);
+    if (response.body) await response.body.cancel();
+  }
+  throw new Error("release download has too many redirects");
+}
+
+export async function fetchBounded(url, maximumBytes, allowedOrigins) {
+  const response = await fetchAllowlisted(url, allowedOrigins);
+  if (!response.ok) throw new Error(`release download failed with HTTP ${response.status}`);
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maximumBytes) throw new Error("release response is oversized");
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength > maximumBytes) throw new Error("release response is oversized");
+  return bytes;
+}
+
+export async function downloadArtifact(url, destination, expectedSize, expectedDigest) {
+  const response = await fetchAllowlisted(url);
+  if (!response.ok || !response.body) throw new Error(`native release download failed with HTTP ${response.status}`);
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared !== expectedSize) throw new Error("native release declared byte size differs");
+  const hash = createHash("sha256");
+  let observed = 0;
+  const transform = new TransformStream({
+    transform(chunk, controller) {
+      observed += chunk.byteLength;
+      if (observed > expectedSize) throw new Error("native release exceeds its authorized byte size");
+      hash.update(chunk);
+      controller.enqueue(chunk);
+    },
+  });
+  await pipeline(Readable.fromWeb(response.body.pipeThrough(transform)), createWriteStream(destination, { flags: "wx", mode: 0o600 }));
+  if (observed !== expectedSize) throw new Error("native release byte size differs");
+  if (hash.digest("hex") !== expectedDigest) throw new Error("native release SHA-256 differs");
+  const descriptor = await open(destination, "r");
+  try { await descriptor.sync(); } finally { await descriptor.close(); }
+  if ((await stat(destination)).size !== expectedSize) throw new Error("native release changed after download");
+}
+
+export function verifyArtifactBytes(bytes, expectedSize, expectedDigest) {
+  if (bytes.byteLength !== expectedSize) throw new Error("native release byte size differs");
+  const observed = createHash("sha256").update(bytes).digest("hex");
+  if (observed !== expectedDigest) throw new Error("native release SHA-256 differs");
+}