menloapp 1.5.1 → 1.6.0

package/README.md

@@ -2,6 +2,22 @@
 
 Share your iPhone app. Let anyone try it.
 
+Starting from scratch:
+
+```sh
+npm i -g menloapp
+menloapp
+```
+
+Keep your intended iPhone connected and unlocked. Menlo checks Xcode and your
+Apple signing, installs Menlo on your iPhone, and guides you through the private
+connection. Setup finishes when the app is installed and paired. Open Menlo on
+your iPhone to send intents; your Mac builds and signs the apps you ask for.
+If setup stops for an Apple prerequisite, follow the instruction and run
+`menloapp setup` to continue.
+
+Already have an app to share:
+
 ```sh
 npm i -g menloapp
 menloapp deploy
@@ -9,6 +25,12 @@ menloapp deploy
 
 Run deploy in your app’s public GitHub repository. It returns a live link like
 **https://menloapp.lol/your-app**. Share it. New commits update the same app page.
+Interactive Mac deploy copies the link and prints a ready-to-share X link.
+Empty app descriptions are filled from your public GitHub repository description;
+supplied copy is preserved.
+When there is exactly one committed AppIcon asset catalog, deploy copies its
+normal app icon into the public presentation folder. Existing selected icons
+and artwork are preserved; ambiguous catalogs require you to choose the icon.
 
 To install someone’s app:
 
@@ -19,6 +41,37 @@ menloapp try https://menloapp.lol/hello-menlo
 MENLO uses your Mac, Xcode and Apple signing identity to build the app for your
 paired iPhone. You review the exact source before its build runs. The iPhone
 needs Trust and Developer Mode enabled.
+The app you came for installs first. You can add Menlo to your iPhone later with
+`menloapp setup`; it is not required to try the linked app.
+
+Shared versions include `?commit=<full-commit>&repository=<numeric-id>`.
+`menloapp try` preserves those parameters through installation. From an iPhone,
+Get app offers the system share sheet to send that version to your Mac. After
+a Mac download, returning to the page resumes the selected version.
+
+## Review a version
+
+Open **Review this version** on an app page, examine the linked source, sign in
+with GitHub, choose the scopes you examined, and explicitly confirm your
+recommendation. Notes are public; you can withdraw your own review from that
+same version page. Browser sign-in lasts ten minutes.
+
+You can also use Terminal:
+
+```sh
+menloapp review 'https://menloapp.lol/your-app?commit=<full-commit>&repository=<numeric-id>'
+```
+
+The command opens the exact source and asks you to confirm:
+“I reviewed this version's source and recommend it for installation.”
+Add `--scope dependencies`, `--scope networking`, or `--notes "Your findings"`
+to explain what you examined. Use `--withdraw` with the same version link to
+withdraw your recommendation. No source is executed by this command.
+
+Reviews name a verified GitHub account and one source commit/build recipe.
+They express human judgment rather than a safety guarantee. New commits and
+changed build recipes start with no inherited reviews. Share the exact-version
+link when recommending code you reviewed.
 
 [Discover apps](https://menloapp.lol)
 
@@ -65,7 +118,8 @@ The public page reads metadata and media from your Git commit. Media must be
 ordinary files inside `menloapp/`, not symbolic links or Git LFS pointers.
 Only selected files are served. Updates can take up to 60 seconds to appear.
 
-Shared links include a 1200 × 630 image with your app icon, title, description,
+Shared links include a 1200 × 630 image with your app icon, first screenshot
+when available, title, description,
 and `menloapp.lol/your-app`. To use your own artwork, set
 `"ogImage": "menloapp/share.png"` (PNG or JPEG, up to 10 MiB; 1200 × 630
 recommended), then commit and push the image and `app.json`. Leave `ogImage`

package/bin/tohseno.js

@@ -5,14 +5,16 @@ import { GUIDE, HELP, parseCommand, redact, suggestedCommand, tryArguments } fro
 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 { openProduct, startProduct } from "../src/start.js";
 import { initPresentation } from "../src/project-presentation.js";
 import { deploy } from "../src/github.js";
+import { review } from "../src/review.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;
+  if (raw[commandIndex] === "review") return review([...raw.slice(commandIndex + 1), ...raw.slice(0, commandIndex)]);
   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")) {
@@ -53,6 +55,7 @@ async function main() {
     if (!installed) throw new Error("the verified native release did not activate safely");
   }
   if (command.kind === "delegate") return delegate(command.args);
+  if (command.kind === "open") return openProduct();
   return startProduct();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "menloapp",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "MENLO: share living iOS apps from GitHub and try them on your own iPhone",
   "type": "module",
   "bin": {

package/src/app-link.js

@@ -0,0 +1,20 @@
+const SHA = /^[a-f0-9]{40}$/;
+
+/** Parse only MENLO app links. Version parameters are never silently discarded. */
+export function parseAppLink(value) {
+  let slug = value, commit = null, repositoryID = null;
+  if (value.startsWith("https://")) {
+    const url = new URL(value);
+    if (url.origin !== "https://menloapp.lol" || url.username || url.password || (url.hash && !["#get-app", "#reviews"].includes(url.hash))) throw new Error("Use a menloapp.lol app link.");
+    for (const key of url.searchParams.keys()) {
+      if (!["commit", "repository"].includes(key) || url.searchParams.getAll(key).length !== 1) throw new Error("Use a MENLO app link with one exact version.");
+    }
+    commit = url.searchParams.get("commit");
+    repositoryID = url.searchParams.get("repository");
+    if (commit !== null && !SHA.test(commit)) throw new Error("An app version needs the full Git commit.");
+    if (repositoryID !== null && (!commit || !/^[1-9]\d*$/.test(repositoryID) || !Number.isSafeInteger(Number(repositoryID)))) throw new Error("Invalid app repository identity.");
+    slug = url.pathname.replace(/^\/|\/$/g, "");
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug) || slug.length < 2 || slug.length > 64) throw new Error("Use https://menloapp.lol/your-app");
+  return { slug, commit, repositoryID };
+}

package/src/cli.js

@@ -1,9 +1,13 @@
 import { NPM_CLI_VERSION } from "./constants.js";
+import { parseAppLink } from "./app-link.js";
 
 export const HELP = `MENLO · menloapp ${NPM_CLI_VERSION}
 
+  menloapp                  Set up Menlo on your iPhone.
+  menloapp setup            Continue iPhone setup.
   menloapp deploy [path]     Share your app. Get a live URL.
   menloapp try <link>        Install an app on your iPhone.
+  menloapp review <link>     Recommend a version you reviewed.
 
   menloapp init [path]       Edit your app page before deploying
   menloapp open              Open MENLO on your Mac
@@ -12,24 +16,24 @@ export const HELP = `MENLO · menloapp ${NPM_CLI_VERSION}
 
 Run menloapp deploy --help for advanced options.`;
 
-export const GUIDE = `Share your app:
+export const GUIDE = `Start from scratch:
+  menloapp
+  Your Mac installs Menlo on your iPhone so you can send intents from there.
+
+Share your app:
   menloapp deploy
 
 Try an app:
   menloapp try https://menloapp.lol/hello-menlo
+  The linked app installs first. Menlo on iPhone is optional afterward.
 
 Discover apps at https://menloapp.lol`;
 
 export function tryArguments(args) {
   if (!args.length || args.includes("--help") || args.includes("-h")) return null;
-  let slug = args[0];
-  if (slug.startsWith("https://")) {
-    const url = new URL(slug);
-    if (url.origin !== "https://menloapp.lol" || url.username || url.password || url.search || url.hash) throw new Error("Use a menloapp.lol app link.");
-    slug = url.pathname.replace(/^\/|\/$/g, "");
-  }
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug) || slug.length < 2 || slug.length > 64) throw new Error("Use menloapp try https://menloapp.lol/your-app");
-  return ["github", "install", slug, ...args.slice(1)];
+  const { slug, commit, repositoryID } = parseAppLink(args[0]);
+  if (commit && args.slice(1).some(arg => /^(--commit|--repository-id)(=|$)/.test(arg))) throw new Error("The link already selects a version. Remove the extra version options.");
+  return ["github", "install", slug, ...(commit ? ["--commit", commit] : []), ...(repositoryID ? ["--repository-id", repositoryID] : []), ...args.slice(1)];
 }
 
 export function suggestedCommand(value) {
@@ -46,7 +50,8 @@ export function suggestedCommand(value) {
 }
 
 export function parseCommand(args) {
-  if (!args.length) return { kind: "guide", args: [] };
+  if (!args.length || (args.length === 1 && args[0] === "setup")) return { kind: "start", args: [] };
+  if (args.length === 1 && args[0] === "guide") 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: [] };

package/src/constants.js

@@ -1,4 +1,4 @@
-export const NPM_CLI_VERSION = "1.5.1";
+export const NPM_CLI_VERSION = "1.6.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"]);

package/src/deploy-ui.js

@@ -1,5 +1,5 @@
 import { createInterface } from "node:readline";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import process from "node:process";
 
 export function shellQuote(value) {
@@ -25,10 +25,16 @@ function ask(question) {
 }
 
 export function deployUI(options) {
+  const interactive = !options.json && !options.dryRun && process.env.MENLO_NONINTERACTIVE !== "1" && Boolean(process.stdin.isTTY && process.stderr.isTTY);
   return {
-    interactive: !options.json && !options.dryRun && process.env.MENLO_NONINTERACTIVE !== "1" && Boolean(process.stdin.isTTY && process.stderr.isTTY),
+    interactive,
     log: options.json || options.dryRun ? () => {} : text => console.error(text),
     print: text => console.log(text), ask, open: openBrowser,
+    copyLink: url => {
+      if (process.platform !== "darwin" || !interactive) return false;
+      execFileSync("/usr/bin/pbcopy", [], { input: url, timeout: 2000, stdio: ["pipe", "ignore", "ignore"] });
+      return true;
+    },
   };
 }
 

package/src/github.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import process from "node:process";
 import { choose, continueAfter, deployUI, openBrowser, shellQuote } from "./deploy-ui.js";
 
-import { setupPresentation, readCommittedPresentation, updatePresentationLinks, commitPresentation, previewNeedsRefresh } from "./project-presentation.js";
+import { setupPresentation, readCommittedPresentation, updatePresentationLinks, fillPresentationDescription, fillPresentationIcon, commitPresentation, previewNeedsRefresh } from "./project-presentation.js";
 import { recordExperience } from "./record.js";
 import { previewTools } from "./experience-agent.js";
 
@@ -254,6 +254,8 @@ export async function deploy(args, dependencies = {}) {
   }
   const generated = [];
   if (await setupPresentation(local.root, project.name)) generated.push("menloapp/app.json", "menloapp/README.md");
+  if (await fillPresentationDescription(local.root, repo.description)) generated.push("menloapp/app.json");
+  generated.push(...await fillPresentationIcon(local.root, project.commit));
   const presentation = await readCommittedPresentation(local.root, project.commit);
   if (!options.noPreview && (options.record || previewNeedsRefresh(local.root, project.commit, presentation))) {
     const missing = (dependencies.previewTools || previewTools)();
@@ -311,7 +313,17 @@ export async function deploy(args, dependencies = {}) {
     ui.log("Saved your GitHub and MENLO links to menloapp/app.json.");
   }
   result = { ...result, githubRepo: `https://github.com/${project.repository}`, menloLink: result.public_url };
+  const finalCommit = git(local.root, "rev-parse", "HEAD");
+  if (Number.isSafeInteger(result.repository_id) && result.repository_id > 0) result.version_url = `${result.public_url}?commit=${finalCommit}&repository=${result.repository_id}`;
+  result.share_on_x_url = `https://twitter.com/intent/tweet?${new URLSearchParams({ text: project.name, url: result.public_url })}`;
   if (options.json) ui.print(JSON.stringify(result));
-  else ui.print(`\nYour app is live:\n${result.public_url}\n\nShare this link. Testers open it in MENLO to build and run the app on their iPhone.\nKeep pushing to ${repo.default_branch}; this link follows your code automatically.\n`);
+  else {
+    let copied = false;
+    try {
+      const copyLink = dependencies.copyLink ?? ui.copyLink;
+      if (copyLink) copied = copyLink(result.public_url) !== false;
+    } catch { /* The app is deployed even if the clipboard is unavailable. */ }
+    ui.print(`\nYour app is live:\n${result.public_url}\n\n${copied ? "App link copied. " : ""}Share this link. Testers open it in MENLO to build and run the app on their iPhone.\nShare on X: ${result.share_on_x_url}\n${result.version_url ? `This exact version: ${result.version_url}\n` : ""}Keep pushing to ${repo.default_branch}; this link follows your code automatically.\n`);
+  }
   return 0;
 }

package/src/project-presentation.js

@@ -78,6 +78,52 @@ export async function updatePresentationLinks(root, repository, menloLink) {
   return true;
 }
 
+export async function fillPresentationDescription(root, description) {
+  if (typeof description !== "string" || !description.trim()) return false;
+  const file = path.join(root, PRESENTATION_PATH);
+  if (!(await lstat(file)).isFile()) throw new Error("menloapp/app.json must be a regular file.");
+  const value = validatePresentation(JSON.parse(await readFile(file, "utf8")));
+  if (value.description) return false;
+  await writeFile(file, JSON.stringify(validatePresentation({ ...value, description: description.slice(0, 4000) }), null, 2) + "\n");
+  return true;
+}
+
+/** Reuse one unambiguous committed app icon; never guess between app targets. */
+export async function fillPresentationIcon(root, commit) {
+  const file = path.join(root, PRESENTATION_PATH);
+  if (!(await lstat(file)).isFile()) throw new Error("menloapp/app.json must be a regular file.");
+  const value = validatePresentation(JSON.parse(await readFile(file, "utf8")));
+  if (value.icon) return [];
+  const git = (...args) => execFileSync("git", ["-C", root, ...args], { maxBuffer: MAX_IMAGE_BYTES + 1024, stdio: ["ignore", "pipe", "pipe"] });
+  const entries = new Map(git("ls-tree", "-r", "-z", commit).toString("utf8").split("\0").filter(Boolean).map(line => { const [info, name] = line.split("\t"); return [name, info.split(" ")[0]]; }));
+  const catalogs = [...entries.keys()].filter(name => /\/[^/]+\.appiconset\/Contents\.json$/.test(name));
+  if (catalogs.length !== 1 || entries.get(catalogs[0]) !== "100644" || !catalogs[0].endsWith("/AppIcon.appiconset/Contents.json")) return [];
+  const read = (name, maximum) => {
+    if (entries.get(name) !== "100644" || Number(git("cat-file", "-s", `${commit}:${name}`).toString()) > maximum) return null;
+    return git("show", `${commit}:${name}`);
+  };
+  const contents = read(catalogs[0], MAX_PRESENTATION_BYTES);
+  if (!contents) return [];
+  let catalog;
+  try { catalog = JSON.parse(contents.toString("utf8")); } catch { return []; }
+  if (!Array.isArray(catalog.images)) return [];
+  const choices = catalog.images.filter(image => image && !image.appearances && typeof image.filename === "string" && /^[A-Za-z0-9_.-]+\.(png|jpe?g)$/.test(image.filename));
+  const pixels = image => (parseFloat(image.size) || 0) * (parseFloat(image.scale) || 1);
+  choices.sort((a, b) => pixels(b) - pixels(a));
+  for (const image of choices) {
+    const source = `${path.posix.dirname(catalogs[0])}/${image.filename}`;
+    const bytes = read(source, MAX_IMAGE_BYTES);
+    if (!bytes) continue;
+    const destination = `menloapp/icon.${image.filename.split(".").at(-1)}`;
+    try { validateMediaBytes(destination, bytes); } catch { continue; }
+    try { await writeFile(path.join(root, destination), bytes, { flag: "wx" }); }
+    catch (error) { if (error.code === "EEXIST") return []; throw error; }
+    await writeFile(file, JSON.stringify(validatePresentation({ ...value, icon: destination }), null, 2) + "\n");
+    return [PRESENTATION_PATH, destination];
+  }
+  return [];
+}
+
 export function previewNeedsRefresh(root, commit, presentation) {
   if (!presentation?.preview) return true;
   if (presentation.preview.kind !== "simulator") return false;

package/src/review-policy.js

@@ -0,0 +1,3 @@
+export const REVIEW_POLICY = "menlo.github-source-review/1";
+export const REVIEW_STATEMENT = "I reviewed this version's source and recommend it for installation.";
+export const REVIEW_SCOPES = ["source", "dependencies", "entitlements", "permissions", "networking", "privacy", "payments", "reproducibility"];

package/src/review.js

@@ -0,0 +1,66 @@
+import { authenticate, MENLO_ORIGIN } from "./github.js";
+import { parseAppLink } from "./app-link.js";
+import { deployUI } from "./deploy-ui.js";
+import { REVIEW_POLICY, REVIEW_SCOPES, REVIEW_STATEMENT } from "./review-policy.js";
+
+export async function review(args, dependencies = {}) {
+  if (!args.length || args.includes("--help") || args.includes("-h")) {
+    (dependencies.ui?.print ?? console.log)(`menloapp review <link> [--scope dependencies] [--notes "Your findings"]
+
+Publish a GitHub-authenticated recommendation of one exact app version.
+Only publish after personally examining the source. This does not build the app.
+Scopes: ${REVIEW_SCOPES.join(", ")}.
+Use --withdraw to withdraw your recommendation of the selected version.
+Noninteractive publishing requires --confirm and a version-pinned link.`);
+    return 0;
+  }
+  const selected = parseAppLink(args[0]);
+  let withdraw = false, confirm = false, json = false, notes = "";
+  const scopes = new Set(["source"]);
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--withdraw") withdraw = true;
+    else if (args[i] === "--confirm") confirm = true;
+    else if (args[i] === "--json") json = true;
+    else if (["--scope", "--notes"].includes(args[i])) {
+      const option = args[i], value = args[++i];
+      if (!value || value.startsWith("--")) throw new Error(`${option} needs a value`);
+      if (option === "--notes") notes = value;
+      else if (REVIEW_SCOPES.includes(value)) scopes.add(value);
+      else throw new Error(`Choose a review scope: ${REVIEW_SCOPES.join(", ")}`);
+    } else throw new Error(`Unknown review option: ${args[i]}`);
+  }
+  if (notes.length > 2000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(notes)) throw new Error("Review notes must be at most 2000 characters.");
+  const ui = dependencies.ui ?? deployUI({ json });
+  if (!ui.interactive && !confirm || confirm && (!selected.commit || !selected.repositoryID)) throw new Error("Noninteractive reviews require an exact version link and --confirm after you have reviewed that source.");
+  const fetcher = dependencies.fetcher ?? fetch;
+  const request = async (url, init = {}) => {
+    const response = await fetcher(url, { ...init, redirect: "error", signal: AbortSignal.timeout(20_000) });
+    const body = await response.json();
+    if (!response.ok) throw new Error(typeof body.error === "string" ? body.error : `MENLO review failed (${response.status}).`);
+    return body;
+  };
+  const params = new URLSearchParams();
+  if (selected.commit) params.set("commit", selected.commit);
+  if (selected.repositoryID) params.set("repository", selected.repositoryID);
+  const endpoint = `${MENLO_ORIGIN}/api/menlo/v1/apps/${selected.slug}`;
+  const app = await request(`${endpoint}${params.size ? `?${params}` : ""}`);
+  if (!/^[a-f0-9]{40}$/.test(app.head_commit) || !Number.isSafeInteger(app.repository_id) || app.repository_id <= 0 || selected.commit && app.head_commit !== selected.commit || selected.repositoryID && app.repository_id !== Number(selected.repositoryID) || !/^[A-Za-z0-9-]+\/[A-Za-z0-9_.-]+$/.test(app.repository)) throw new Error("MENLO did not confirm the selected source version.");
+  const sourceURL = `https://github.com/${app.repository}/tree/${app.head_commit}`;
+  const versionURL = `${MENLO_ORIGIN}/${selected.slug}?commit=${app.head_commit}&repository=${app.repository_id}`;
+  ui.log(`Source: ${sourceURL}\nVersion: ${app.head_commit}\nReviewed scopes: ${[...scopes].join(", ")}\n${withdraw ? "Withdraw your recommendation of this version." : REVIEW_STATEMENT}\n${notes ? `Public notes: ${notes}\n` : ""}Your GitHub identity and statement will be public. A new version receives no inherited review.`);
+  if (!confirm && !withdraw) ui.open(sourceURL);
+  let identity;
+  try { identity = await authenticate(ui, { ...dependencies, fetcher }); }
+  catch (error) { throw new Error(error.message.replaceAll("menloapp deploy", "menloapp review")); }
+  if (!confirm) {
+    const word = withdraw ? "withdraw" : "recommend";
+    if (await ui.ask(`Publishing as @${identity.user.login}. Type ${word}, or press Enter to cancel: `) !== word) { ui.print("Review cancelled."); return 0; }
+  }
+  const result = await request(`${endpoint}/reviews?commit=${app.head_commit}&repository=${app.repository_id}`, {
+    method: "POST", headers: { Authorization: `Bearer ${identity.credential}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ policy: REVIEW_POLICY, statement: REVIEW_STATEMENT, outcome: withdraw ? "withdraw" : "recommend", repository_id: app.repository_id, commit: app.head_commit, project: app.project, scheme: app.scheme, scopes: withdraw ? [] : [...scopes], notes }),
+  });
+  if (result.schema !== REVIEW_POLICY || result.commit !== app.head_commit || result.repository_id !== app.repository_id || result.reviewer?.id !== identity.user.id || result.outcome !== (withdraw ? "withdraw" : "recommend")) throw new Error("MENLO did not confirm your review. Check the version page before retrying.");
+  ui.print(json ? JSON.stringify(result) : `${withdraw ? "Recommendation withdrawn" : "Source review published"}.\n${versionURL}#reviews`);
+  return 0;
+}

package/src/start.js

@@ -1,9 +1,23 @@
 import { delegate } from "./native.js";
 
 export function startProduct(run = delegate, write = console.log) {
-  write("Starting TOHSENO…");
+  write("Welcome to Menlo. First, we’ll install Menlo on your iPhone.");
+  write("You’ll send intents from your iPhone. This Mac builds and signs the apps you ask for.");
+  write("Connect your iPhone and keep it unlocked. We’ll check Xcode, your Apple signing, installation, and the private connection.");
   const service = run(["service", "install"]);
   if (service !== 0) return service;
-  write("Opening TOHSENO…");
+  const setup = run(["companion", "install"]);
+  if (setup !== 0) {
+    write("Setup is not complete. Follow the step above, then run menloapp setup to continue.");
+    return setup;
+  }
+  write("Menlo is installed and connected. Open it on your iPhone and tap the Menlo button to send your first intent.");
+  return 0;
+}
+
+export function openProduct(run = delegate, write = console.log) {
+  const service = run(["service", "install"]);
+  if (service !== 0) return service;
+  write("Opening Menlo on your Mac…");
   return run(["studio"]);
 }