menloapp 1.5.1 → 1.7.0

package/README.md

@@ -2,14 +2,43 @@
 
 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
 ```
 
-Run deploy in your app’s public GitHub repository. It returns a live link like
+Run deploy in your app’s folder. It returns a live link like
 **https://menloapp.lol/your-app**. Share it. New commits update the same app page.
 
+Deploy takes care of the Git and GitHub steps, asking before each one. A plain
+folder gets a Git repository (with a standard Xcode `.gitignore` that keeps
+`.env`, signing keys and provisioning profiles out). Uncommitted changes can be
+committed with your message, a missing GitHub repository is created as a public
+repository under your account, and unpushed commits are pushed. Deploy never
+commits files that look like secrets and stops on files GitHub would reject.
+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:
 
 ```sh
@@ -19,6 +48,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 +125,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.7.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.7.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,8 +4,9 @@ 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 { createGitHubRepository, initRepository, offerCommit, pushBranch } from "./repository-setup.js";
 import { previewTools } from "./experience-agent.js";
 
 export const MENLO_ORIGIN = "https://menloapp.lol";
@@ -121,6 +122,11 @@ export async function authenticate(ui, { fetcher = fetch, execute = run, env = p
   catch (error) { if (error.status === 401) throw new Error(`GitHub did not accept the new sign-in.\n${instructions}`); throw error; }
 }
 
+function isAncestor(root, ancestor, commit) {
+  try { execFileSync("git", ["-C", root, "merge-base", "--is-ancestor", ancestor, commit], { stdio: "ignore", timeout: 20_000 }); return true; }
+  catch { return false; }
+}
+
 function git(directory, ...args) {
   try { return run("git", ["-C", directory, ...args]); }
   catch { throw new Error("Open your app's Git repository, then run menloapp deploy. It needs a GitHub origin and at least one commit."); }
@@ -138,9 +144,34 @@ async function inspectRepository(options) {
   return { root, directory, explicitContainer, repository: githubRepository(remote) };
 }
 
+/**
+ * Take the folder as far as a GitHub repository with at least one commit,
+ * asking before each step: git init, first commit, public GitHub repository.
+ */
+async function prepareRepository(options, ui, { credential, user, fetcher, description }) {
+  let input;
+  try { input = await realpath(options.directory); } catch { throw new Error(`App directory not found: ${options.directory}\nRun menloapp deploy from your app's repository.`); }
+  const directory = /\.(xcodeproj|xcworkspace)$/.test(input) ? path.dirname(input) : input;
+  let root = optionalRun(run, "git", ["-C", directory, "rev-parse", "--show-toplevel"]);
+  if (!root) root = await initRepository(directory, ui);
+  if (!optionalRun(run, "git", ["-C", root, "rev-parse", "--verify", "-q", "HEAD"])) {
+    if (!ui.interactive) throw new Error("This repository has no commits yet.\nCommit your app (git add -A && git commit -m \"First version\"), then run menloapp deploy.");
+    if (!await offerCommit(root, ui, { first: true, name: path.basename(root) })) throw new Error("Deploy needs a first commit. Nothing was published.");
+  }
+  if (!optionalRun(run, "git", ["-C", root, "remote", "get-url", "origin"])) {
+    const call = (url, init) => api(url, { ...init, headers: { ...headers(credential), "Content-Type": "application/json" } }, fetcher);
+    await createGitHubRepository(root, ui, { credential, user, api: call, describe: description });
+  }
+  return inspectRepository(options);
+}
+
 export async function inspectProject(options, ui = deployUI(options)) {
   const { root, directory, explicitContainer, repository } = await inspectRepository(options);
   while (git(root, "status", "--porcelain", "--untracked-files=normal")) {
+    if (ui.interactive) {
+      try { if (await offerCommit(root, ui, { name: path.basename(root) })) continue; }
+      catch (error) { ui.log(`\n${error.message}`); }
+    }
     await continueAfter(ui, "Your app has uncommitted changes. MENLO shares the code pushed to GitHub.\nIn another terminal, review git status, commit the files you want to share, and push them. Local files will not be uploaded automatically.");
   }
   const commit = git(root, "rev-parse", "HEAD");
@@ -232,21 +263,43 @@ export async function deploy(args, dependencies = {}) {
   const ui = dependencies.ui || deployUI(options);
   const fetcher = dependencies.fetcher || fetch;
   if (options.help) {
-    ui.print("MENLO deploy\n\nmenloapp deploy [path]\n\nSign in to GitHub, choose your app if needed, and get a production app link.\nMENLO guides you through each step. Later pushes appear automatically.\n\nOptions: --project path/App.xcodeproj, --scheme Name, --app-slug your-app,\n         --name Name, --dry-run (local checks only), --json (no prompts)\n         --record (regenerate the automatic preview), --no-preview,\n         --seconds 3–60, --simulator UDID");
+    ui.print("MENLO deploy\n\nmenloapp deploy [path]\n\nSign in to GitHub, choose your app if needed, and get a production app link.\nMENLO sets up Git and a public GitHub repository if needed, asking first.\nLater pushes appear automatically.\n\nOptions: --project path/App.xcodeproj, --scheme Name, --app-slug your-app,\n         --name Name, --dry-run (local checks only), --json (no prompts)\n         --record (regenerate the automatic preview), --no-preview,\n         --seconds 3–60, --simulator UDID");
     return 0;
   }
   if (options.dryRun) { ui.print(JSON.stringify(await inspectProject(options, ui), null, 2)); return 0; }
-  const local = await inspectRepository(options);
-  ui.log(`MENLO deploy\nRepository: ${local.repository}`);
-  const { credential } = await authenticate(ui, { ...dependencies, fetcher });
+  // A non-GitHub origin fails before sign-in; a missing repository or origin is set up after it.
+  const existingRoot = optionalRun(run, "git", ["-C", options.directory, "rev-parse", "--show-toplevel"]);
+  const existingRemote = existingRoot && optionalRun(run, "git", ["-C", existingRoot, "remote", "get-url", "origin"]);
+  if (existingRemote) githubRepository(existingRemote);
+  ui.log("MENLO deploy");
+  const { credential, user } = await authenticate(ui, { ...dependencies, fetcher });
+  const local = await prepareRepository(options, ui, { credential, user, fetcher, description: "" });
+  ui.log(`Repository: ${local.repository}`);
   const repo = await publicRepository(local.repository, credential, ui, fetcher);
+  const sleep = dependencies.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+  let pushed = 0;
   let project;
   while (true) {
     project = await inspectProject(options, ui);
     if (project.repository !== local.repository) throw new Error("The GitHub origin changed during deployment. Run menloapp deploy again to connect the new repository.");
-    const head = await api(`https://api.github.com/repos/${project.repository}/commits/${encodeURIComponent(repo.default_branch)}`, { headers: headers(credential) }, fetcher);
-    if (head.sha === project.commit) break;
+    let head;
+    try { head = await api(`https://api.github.com/repos/${project.repository}/commits/${encodeURIComponent(repo.default_branch)}`, { headers: headers(credential) }, fetcher); }
+    catch (error) { if (error.status !== 409 && error.status !== 404) throw error; head = null; /* An empty GitHub repository. */ }
+    if (head?.sha === project.commit) break;
+    // GitHub can take a moment to report a branch that was just pushed.
+    if (pushed && pushed < 4) { pushed++; await sleep(1500); continue; }
     const branch = git(local.root, "branch", "--show-current");
+    const ahead = branch === repo.default_branch && (!head || isAncestor(local.root, head.sha, project.commit));
+    if (ahead && ui.interactive && pushed === 0) {
+      const count = Number(optionalRun(run, "git", ["-C", local.root, "rev-list", "--count", head ? `${head.sha}..HEAD` : "HEAD"])) || 1;
+      const answer = await ui.ask(`Push ${count === 1 ? "your new commit" : `${count} new commits`} to GitHub's ${branch} branch? [Y/n] `);
+      if (!answer || /^y(es)?$/i.test(answer)) {
+        pushBranch(local.root, project.repository, branch, credential);
+        pushed = 1;
+        continue;
+      }
+    }
+    pushed = 0;
     const instruction = branch === repo.default_branch
       ? `Push your committed changes: git push origin ${shellQuote(branch)}\nIf GitHub has newer commits, bring them in first: git pull --ff-only origin ${shellQuote(branch)}`
       : `MENLO follows ${repo.default_branch}. Merge your changes into that branch and push it, then switch this checkout to ${repo.default_branch}.`;
@@ -254,6 +307,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)();
@@ -269,7 +324,7 @@ export async function deploy(args, dependencies = {}) {
     }
   }
   if (generated.length) {
-    (dependencies.commitPresentation || commitPresentation)(local.root, [...new Set(generated)], repo.default_branch);
+    (dependencies.commitPresentation || commitPresentation)(local.root, [...new Set(generated)], repo.default_branch, { repository: local.repository, credential });
     project = await inspectProject(options, ui);
   }
   ui.log(`App: ${project.name}\nProject: ${project.project} · ${project.scheme}\nConnecting this app to MENLO…`);
@@ -307,11 +362,21 @@ export async function deploy(args, dependencies = {}) {
   }
   if (result.public_url !== `${MENLO_ORIGIN}/${project.slug}`) throw new Error("MENLO did not confirm the expected app link. Run menloapp deploy again to verify it.");
   if (await updatePresentationLinks(local.root, project.repository, result.public_url)) {
-    (dependencies.commitPresentation || commitPresentation)(local.root, ["menloapp/app.json"], repo.default_branch);
+    (dependencies.commitPresentation || commitPresentation)(local.root, ["menloapp/app.json"], repo.default_branch, { repository: local.repository, credential });
     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

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { pushBranch } from "./repository-setup.js";
 import { PRESENTATION_PATH, MAX_PRESENTATION_BYTES, MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, validatePresentation, presentationFiles, validateMediaBytes } from "./presentation.js";
 
 export function projectRoot(directory) {
@@ -78,6 +79,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;
@@ -88,7 +135,7 @@ export function previewNeedsRefresh(root, commit, presentation) {
   } catch { return true; }
 }
 
-export function commitPresentation(root, files, branch) {
+export function commitPresentation(root, files, branch, { repository, credential } = {}) {
   const allowed = new Set(files);
   for (const file of allowed) if (!file.startsWith("menloapp/") || file.split("/").some(part => part === ".." || part === ".")) throw new Error("Only generated app presentation files can be committed by deploy.");
   const git = (...args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 60_000, stdio: ["ignore", "pipe", "pipe"] }).trim();
@@ -99,7 +146,9 @@ export function commitPresentation(root, files, branch) {
   if (!trackedChanges.length && !untracked.length) return false;
   git("add", "--", ...allowed);
   git("commit", "-m", "Update MENLO app page", "--only", "--", ...allowed);
-  try { git("push", "origin", branch); }
-  catch { throw new Error(`The app page is committed locally, but the push did not complete. Run git push origin ${branch}, then menloapp deploy.`); }
+  try {
+    if (repository) pushBranch(root, repository, branch, credential);
+    else git("push", "origin", branch);
+  } catch { throw new Error(`The app page is committed locally, but the push did not complete. Run git push origin ${branch}, then menloapp deploy.`); }
   return true;
 }

package/src/repository-setup.js

@@ -0,0 +1,158 @@
+import { execFileSync } from "node:child_process";
+import { stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+// Deploy can take a plain folder all the way to a public GitHub repository.
+// Every step that publishes code asks first, and nothing secret-looking is committed.
+
+const GITHUB_FILE_LIMIT = 100 * 1024 * 1024;
+
+export const XCODE_GITIGNORE = `# Xcode
+build/
+DerivedData/
+xcuserdata/
+*.xcuserstate
+*.xcscmblueprint
+*.xccheckout
+.build/
+.swiftpm/xcode/
+
+# macOS
+.DS_Store
+
+# Secrets and signing material stay on this Mac
+.env
+.env.*
+*.p8
+*.p12
+*.pem
+*.key
+*.cer
+*.mobileprovision
+*.provisionprofile
+`;
+
+// Files that usually hold credentials. Deploy refuses to publish them automatically.
+const RISKY = [
+  /(?:^|\/)\.env(?:\.|$)/, /\.(?:p8|p12|pem|key|cer|mobileprovision|provisionprofile|keystore|jks)$/i,
+  /(?:^|\/)(?:credentials|secrets?)(?:\.[a-z]+)?$/i, /(?:^|\/)id_(?:rsa|ed25519|ecdsa)$/,
+];
+export const riskyFile = file => RISKY.some(pattern => pattern.test(file));
+
+const gitIn = (root, args, options = {}) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 120_000, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], ...options }).trim();
+
+/** Files that `git add -A` would stage, relative to the repository root. */
+function pendingFiles(root) {
+  const untracked = gitIn(root, ["ls-files", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean);
+  let changed = [];
+  try { changed = gitIn(root, ["diff", "HEAD", "--name-only", "-z"]).split("\0").filter(Boolean); }
+  catch { changed = gitIn(root, ["ls-files", "-z"]).split("\0").filter(Boolean); }
+  return [...new Set([...changed, ...untracked])].sort();
+}
+
+async function checkPublishable(root, files) {
+  const risky = files.filter(riskyFile);
+  if (risky.length) throw new Error(`These files look like secrets, so Menlo will not publish them:\n${risky.slice(0, 10).map(file => `  ${file}`).join("\n")}\nAdd them to .gitignore (or remove them), then run menloapp deploy again.`);
+  const large = [];
+  for (const file of files) {
+    const info = await stat(path.join(root, file)).catch(() => null);
+    if (info?.isFile() && info.size > GITHUB_FILE_LIMIT) large.push(file);
+  }
+  if (large.length) throw new Error(`GitHub does not accept files over 100 MB:\n${large.map(file => `  ${file}`).join("\n")}\nAdd them to .gitignore, then run menloapp deploy again.`);
+}
+
+function summary(files) {
+  const shown = files.slice(0, 12).map(file => `  ${file}`).join("\n");
+  return files.length > 12 ? `${shown}\n  …and ${files.length - 12} more` : shown;
+}
+
+const yes = (answer, fallback) => answer === "" ? fallback : /^y(es)?$/i.test(answer);
+
+/** Make a plain app folder into a Git repository with one reviewed first commit. */
+export async function initRepository(directory, ui) {
+  if (!ui.interactive) throw new Error("This folder is not a Git repository yet.\nRun menloapp deploy in a terminal and Menlo will set it up, or run:\n  git init && git add -A && git commit -m \"First version\"");
+  const projects = execFileSync("find", [directory, "-maxdepth", "4", "(", "-name", "*.xcodeproj", "-o", "-name", "*.xcworkspace", ")", "-not", "-path", "*/DerivedData/*", "-not", "-path", "*/build/*", "-not", "-path", "*.xcodeproj/*"], { encoding: "utf8", timeout: 20_000 }).trim();
+  if (!projects) throw new Error("No Xcode project was found in this folder.\nRun menloapp deploy from your iOS app's folder.");
+  ui.log(`\nThis folder is not a Git repository yet. Menlo shares apps from public GitHub source,\nso it will set one up here (with a standard Xcode .gitignore that keeps secrets out).`);
+  if (!yes(await ui.ask("Set up Git here? [Y/n] "), true)) throw new Error("Deploy stopped. Nothing was changed.");
+  gitIn(directory, ["init", "-q", "--initial-branch=main"]);
+  const ignore = path.join(directory, ".gitignore");
+  try { await writeFile(ignore, XCODE_GITIGNORE, { flag: "wx" }); }
+  catch (error) { if (error.code !== "EEXIST") throw error; }
+  return directory;
+}
+
+/**
+ * Offer to commit pending work. Returns true when a commit was made.
+ * `first` describes a brand-new repository's first commit.
+ */
+export async function offerCommit(root, ui, { first = false, name = "app" } = {}) {
+  const files = pendingFiles(root);
+  if (!files.length) return false;
+  await checkPublishable(root, files);
+  ui.log(`\n${first ? "Files for the first version" : "Uncommitted changes"} (${files.length}):\n${summary(files)}`);
+  const question = first ? `Commit ${files.length === 1 ? "this file" : `these ${files.length} files`}? [Y/n] ` : `Commit ${files.length === 1 ? "this change" : `these ${files.length} changes`} and publish them to GitHub? [y/N] `;
+  if (!yes(await ui.ask(question), first)) return false;
+  const message = (first ? "" : await ui.ask(`Commit message [Update ${name}]: `)) || (first ? `First version of ${name}` : `Update ${name}`);
+  gitIn(root, ["add", "-A"]);
+  try { gitIn(root, ["commit", "-q", "-m", message]); }
+  catch (error) {
+    const detail = String(error.stderr || "").trim();
+    throw new Error(`Git could not commit${detail ? `:\n${detail}` : "."}${/user\.(?:name|email)|identity/i.test(detail) ? "\nSet your Git name and email, then run menloapp deploy again:\n  git config --global user.name \"Your Name\"\n  git config --global user.email you@example.com" : ""}`);
+  }
+  return true;
+}
+
+/**
+ * Push a branch to GitHub. Use the person's own Git credentials first; if
+ * those are not set up, use the GitHub sign-in deploy already verified for this
+ * one push, passed through the environment and never saved.
+ */
+export function pushBranch(root, repository, branch, credential, { upstream = false } = {}) {
+  const target = `HEAD:refs/heads/${branch}`;
+  const quiet = { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" };
+  try { gitIn(root, ["push", "-q", ...(upstream ? ["-u"] : []), "origin", target], { env: quiet, timeout: 600_000 }); return; }
+  catch { /* Fall back to the verified sign-in below. */ }
+  if (!credential) throw new Error(`Git could not push to GitHub. Run git push origin ${branch}, then menloapp deploy.`);
+  const header = `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${credential}`).toString("base64")}`;
+  const env = { ...quiet, GIT_CONFIG_COUNT: "2", GIT_CONFIG_KEY_0: "credential.helper", GIT_CONFIG_VALUE_0: "", GIT_CONFIG_KEY_1: "http.https://github.com/.extraheader", GIT_CONFIG_VALUE_1: header };
+  try { gitIn(root, ["push", "-q", `https://github.com/${repository}.git`, target], { env, timeout: 600_000 }); }
+  catch { throw new Error(`GitHub did not accept the push to ${repository}.\nRun git push origin ${branch} to see why, then menloapp deploy again.`); }
+  // Keep `git status` accurate after a push that bypassed the remote's configured URL.
+  try { gitIn(root, ["fetch", "-q", "origin", branch], { env: quiet, timeout: 60_000 }); } catch { /* Cosmetic only. */ }
+}
+
+/** A GitHub repository name derived from the folder, e.g. "My App!" → "My-App". */
+export function repositoryName(directory) {
+  return path.basename(directory).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "").slice(0, 100) || "my-app";
+}
+
+/** Create the public GitHub repository for this folder, connect it as origin, and push. */
+export async function createGitHubRepository(root, ui, { credential, user, api, describe = "" }) {
+  if (!ui.interactive) throw new Error(`This repository has no GitHub origin.\nRun menloapp deploy in a terminal and Menlo will create the public GitHub repository, or run:\n  gh repo create --public --source=. --remote=origin --push`);
+  let name = repositoryName(root);
+  ui.log(`\nThis app is not on GitHub yet. Menlo shares apps from public GitHub source:\nanyone can read the code and its history.`);
+  while (true) {
+    const answer = await ui.ask(`Create the public repository github.com/${user.login}/${name}? [Y/n, or type another name] `);
+    if (/^n(o)?$/i.test(answer)) throw new Error("Deploy stopped. Nothing was published.");
+    if (answer && !/^y(es)?$/i.test(answer)) {
+      if (!/^[A-Za-z0-9._-]{1,100}$/.test(answer) || /^\.+$/.test(answer)) { ui.log("Use letters, numbers, dots, hyphens and underscores."); continue; }
+      name = answer;
+    }
+    try {
+      await api("https://api.github.com/user/repos", { method: "POST", body: JSON.stringify({ name, private: false, ...(describe ? { description: describe.slice(0, 350) } : {}) }) });
+      break;
+    } catch (error) {
+      if (error.status === 422) { ui.log(`You already have a repository named ${name} on GitHub. Choose another name.`); name = `${name}-app`; continue; }
+      if (error.status === 403 || error.status === 404) throw new Error(`Your GitHub sign-in cannot create repositories.\nCreate it at https://github.com/new (public), then run:\n  git remote add origin https://github.com/${user.login}/${name}.git\n  menloapp deploy`);
+      throw error;
+    }
+  }
+  const repository = `${user.login}/${name}`;
+  gitIn(root, ["remote", "add", "origin", `https://github.com/${repository}.git`]);
+  const branch = gitIn(root, ["branch", "--show-current"]) || "main";
+  ui.log(`Created https://github.com/${repository}\nPushing ${branch}…`);
+  pushBranch(root, repository, branch, credential, { upstream: true });
+  return repository;
+}

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"]);
 }