@swipt/cli 0.1.0-nightly.47 → 0.1.0-nightly.49

package/sideload.mjs

@@ -1,4 +1,4 @@
-import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { execFile, execFileSync, spawn } from "node:child_process";
 import { X509Certificate, createHash } from "node:crypto";
 import fs from "node:fs";
 import { createRequire } from "node:module";
@@ -7,12 +7,23 @@ import path from "node:path";
 import readline from "node:readline";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { promisify } from "node:util";
+
+import password from "@inquirer/password";
+import select from "@inquirer/select";
 
 import { UsageError, open } from "./client.mjs";
-import { apps, coreDevice, devicectl } from "./coredevice.mjs";
-import { printScriptError } from "./output.mjs";
+import {
+  apps,
+  coreDevice,
+  devicectl,
+  provisioningProfiles,
+} from "./coredevice.mjs";
+import { choose, interactive, printScriptError, step } from "./output.mjs";
 import { LogLevel } from "./proto/common_pb.js";
 
+const exec = promisify(execFile);
+
 const bundleId = "io.nekohasekai.swipt";
 const repository = "swipt-automation/swipt";
 const teamPattern = /^[A-Z0-9]{10}$/;
@@ -21,6 +32,10 @@ const sideloadedPattern = new RegExp(
 );
 
 const accountsHint = "Xcode › Settings › Accounts";
+const xcodeProfiles = "Library/Developer/Xcode/UserData/Provisioning Profiles";
+
+const expiresSoon = ({ creation, expiration }) =>
+  expiration - Date.now() < (expiration - creation) / 2;
 
 const passcodeTypes = ["pin", "numeric", "alphanumeric"];
 
@@ -71,22 +86,33 @@ async function github(url, accept, signal) {
   }
   if (!response.ok) {
     let message = `GitHub answered ${response.status} for ${url}`;
-    if ([401, 403, 404, 429].includes(response.status)) {
+    if ([401, 403, 429].includes(response.status)) {
       message += `; ${process.env.GITHUB_TOKEN ? "GITHUB_TOKEN" : "set GITHUB_TOKEN to a token that"} must read the repository and stay under the rate limit`;
     }
-    throw new Error(message);
+    const error = new Error(message);
+    error.status = response.status;
+    throw error;
   }
   return response;
 }
 
 async function findRelease(nightly, signal) {
-  const release = await (
-    await github(
-      `https://api.github.com/repos/${repository}/releases/${nightly ? "tags/nightly" : "latest"}`,
-      "application/vnd.github+json",
-      signal,
-    )
-  ).json();
+  const read = async (name) =>
+    (
+      await github(
+        `https://api.github.com/repos/${repository}/releases/${name}`,
+        "application/vnd.github+json",
+        signal,
+      )
+    ).json();
+  const release = nightly
+    ? await read("tags/nightly")
+    : await read("latest").catch((error) => {
+        if (error.status !== 404) {
+          throw error;
+        }
+        return read("tags/nightly");
+      });
   const asset = (name) => {
     const found = release.assets.find((it) => it.name === name);
     if (!found) {
@@ -105,15 +131,31 @@ async function findRelease(nightly, signal) {
   };
 }
 
-async function download(url, file, signal) {
+async function download(url, file, signal, update) {
   const response = await github(url, "application/octet-stream", signal);
-  await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(file), {
-    signal,
-  });
+  const total = Number(response.headers.get("content-length"));
+  const megabytes = (bytes) => (bytes / 1_000_000).toFixed(1);
+  let received = 0;
+  await pipeline(
+    Readable.fromWeb(response.body),
+    async function* (source) {
+      for await (const chunk of source) {
+        received += chunk.length;
+        update(
+          total > 0
+            ? `${megabytes(received)} / ${megabytes(total)} MB  ${Math.floor((received / total) * 100)}%`
+            : `${megabytes(received)} MB`,
+        );
+        yield chunk;
+      }
+    },
+    fs.createWriteStream(file),
+    { signal },
+  );
 }
 
-function unpack(ipa, directory) {
-  execFileSync("unzip", ["-q", ipa, "-d", directory]);
+async function unpack(ipa, directory) {
+  await exec("unzip", ["-q", ipa, "-d", directory]);
   const payload = path.join(directory, "Payload");
   const app = fs.readdirSync(payload).find((name) => name.endsWith(".app"));
   if (app === undefined) {
@@ -155,6 +197,7 @@ const pbxproj = (id, team) => `// !$*UTF8*$!
 				CODE_SIGN_STYLE = Automatic;
 				DEVELOPMENT_TEAM = "${team}";
 				GENERATE_INFOPLIST_FILE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 16.4;
 				PRODUCT_BUNDLE_IDENTIFIER = "${id}";
 				PRODUCT_NAME = Stub;
 				SDKROOT = iphoneos;
@@ -199,9 +242,20 @@ function explain(output, team) {
   return errors || output.trim();
 }
 
-function provision(work, id, team, device) {
+function profileField(file, key) {
+  return execFileSync("plutil", ["-extract", key, "raw", "-o", "-", "-"], {
+    input: execFileSync("security", ["cms", "-D", "-i", file], {
+      stdio: ["ignore", "pipe", "ignore"],
+    }),
+    encoding: "utf8",
+  }).trim();
+}
+
+async function provision(work, id, team, device, update) {
   const stub = path.join(work, "Stub");
   const products = path.join(stub, "Products");
+  const app = path.join(products, "Stub.app");
+  const profile = path.join(app, "embedded.mobileprovision");
   fs.mkdirSync(path.join(stub, "Stub.xcodeproj"), { recursive: true });
   fs.mkdirSync(path.join(stub, "Stub"));
   fs.writeFileSync(
@@ -212,34 +266,65 @@ function provision(work, id, team, device) {
     path.join(stub, "Stub.xcodeproj/project.pbxproj"),
     pbxproj(id, team),
   );
-  const result = spawnSync(
-    "xcodebuild",
-    [
-      "build",
-      "-project",
-      path.join(stub, "Stub.xcodeproj"),
-      "-target",
-      "Stub",
-      "-configuration",
-      "Release",
-      "-destination",
-      `id=${device.udid}`,
-      `CONFIGURATION_BUILD_DIR=${products}`,
-      `OBJROOT=${path.join(stub, "Objects")}`,
-      "-allowProvisioningUpdates",
-      "-allowProvisioningDeviceRegistration",
-    ],
-    { encoding: "utf8" },
-  );
-  if (result.error) {
-    throw result.error.code === "ENOENT"
-      ? new Error("xcodebuild is missing; install Xcode")
-      : result.error;
-  }
-  if (result.status !== 0) {
-    throw new Error(explain(`${result.stdout}${result.stderr}`, team));
+  const build = async () => {
+    const running = exec(
+      "xcodebuild",
+      [
+        "build",
+        "-project",
+        path.join(stub, "Stub.xcodeproj"),
+        "-scheme",
+        "Stub",
+        "-configuration",
+        "Release",
+        "-destination",
+        `id=${device.udid}`,
+        `CONFIGURATION_BUILD_DIR=${products}`,
+        `OBJROOT=${path.join(stub, "Objects")}`,
+        "-allowProvisioningUpdates",
+        "-allowProvisioningDeviceRegistration",
+      ],
+      { maxBuffer: Infinity },
+    );
+    running.child.stdout.on("data", (chunk) => {
+      const line = String(chunk)
+        .split("\n")
+        .findLast((it) => /^[A-Z]\w* /.test(it));
+      if (line) {
+        update(line.split(" ")[0]);
+      }
+    });
+    try {
+      await running;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new Error("xcodebuild is missing; install Xcode");
+      }
+      if (typeof error.code !== "number") {
+        throw error;
+      }
+      throw new Error(explain(`${error.stdout}${error.stderr}`, team));
+    }
+  };
+  await build();
+  if (
+    expiresSoon({
+      creation: Date.parse(profileField(profile, "CreationDate")),
+      expiration: Date.parse(profileField(profile, "ExpirationDate")),
+    })
+  ) {
+    // Xcode keeps a valid cached profile and creates a new one once it is removed.
+    fs.rmSync(
+      path.join(
+        os.homedir(),
+        xcodeProfiles,
+        `${profileField(profile, "UUID")}.mobileprovision`,
+      ),
+      { force: true },
+    );
+    update("renewing the profile");
+    await build();
   }
-  const app = path.join(products, "Stub.app");
   const certificates = path.join(work, "certificate");
   const stdio = ["ignore", "pipe", "ignore"];
   execFileSync(
@@ -260,11 +345,11 @@ function provision(work, id, team, device) {
       .digest("hex")
       .toUpperCase(),
     entitlements,
-    profile: path.join(app, "embedded.mobileprovision"),
+    profile,
   };
 }
 
-function resign(app, id, signing) {
+async function resign(app, id, signing, update) {
   const info = path.join(app, "Info.plist");
   execFileSync("plutil", [
     "-replace",
@@ -306,10 +391,12 @@ function resign(app, id, signing) {
   const frameworks = path.join(app, "Frameworks");
   if (fs.existsSync(frameworks)) {
     for (const name of fs.readdirSync(frameworks)) {
-      execFileSync("codesign", [...codesign, path.join(frameworks, name)]);
+      update(name);
+      await exec("codesign", [...codesign, path.join(frameworks, name)]);
     }
   }
-  execFileSync("codesign", [
+  update(path.basename(app));
+  await exec("codesign", [
     ...codesign,
     "--entitlements",
     signing.entitlements,
@@ -350,13 +437,81 @@ function xcodeTeams() {
   return [...teams].map(([id, name]) => ({ id, name }));
 }
 
+function xcodeSignedIn() {
+  try {
+    const lists = JSON.parse(
+      execFileSync(
+        "plutil",
+        [
+          "-extract",
+          "DVTDeveloperAccountManagerAppleIDLists",
+          "json",
+          "-o",
+          "-",
+          "-",
+        ],
+        {
+          input: execFileSync("defaults", [
+            "export",
+            "com.apple.dt.Xcode",
+            "-",
+          ]),
+          stdio: ["pipe", "pipe", "ignore"],
+          encoding: "utf8",
+        },
+      ),
+    );
+    return Object.values(lists).some((accounts) => accounts.length > 0);
+  } catch {
+    return false;
+  }
+}
+
 const teamList = (teams) =>
   teams
     .map((team) => `  ${team.id}${team.name ? `  ${team.name}` : ""}`)
     .join("\n");
 
-function locate(options, device, fresh = false) {
-  const found = apps(device.udid)
+const teamChoice = ({ id, name }) => ({
+  name: name ? `${name}  ${id}` : id,
+  short: name ?? id,
+  value: id,
+});
+
+const installHint = '; install it with "swipt sideload install"';
+
+async function sideloadedDevices(devices, hint = "") {
+  const sideloaded = await step(
+    "looking for Swipt on the devices",
+    () =>
+      Promise.all(
+        devices.map((device) =>
+          apps(device.udid).then(
+            (listed) =>
+              listed.some((app) =>
+                sideloadedPattern.test(app.bundleIdentifier),
+              ),
+            () => true,
+          ),
+        ),
+      ),
+    { transient: true },
+  );
+  const found = devices.filter((_, index) => sideloaded[index]);
+  if (found.length === 0) {
+    throw new Error(`Swipt is not sideloaded on any online iOS device${hint}`);
+  }
+  return found;
+}
+
+async function locate(context, device, fresh = false) {
+  const { options } = context;
+  const listed = await step(
+    `reading apps on ${device.name}`,
+    () => apps(device.udid),
+    { transient: true },
+  );
+  const found = listed
     .map((app) => ({
       ...app,
       team: sideloadedPattern.exec(app.bundleIdentifier)?.[1],
@@ -374,98 +529,252 @@ function locate(options, device, fresh = false) {
     };
   }
   if (found.length > 1) {
-    throw new Error(
-      `Swipt is sideloaded on ${device.name} by more than one team; choose one with --team ID:\n${teamList(found.map((app) => ({ id: app.team })))}`,
+    const known = xcodeTeams();
+    const teams = found.map((app) => ({
+      id: app.team,
+      name: known.find((team) => team.id === app.team)?.name,
+    }));
+    const team = await choose(
+      context,
+      "Choose a team",
+      teams.map(teamChoice),
+      new Error(
+        `Swipt is sideloaded on ${device.name} by more than one team; choose one with --team ID:\n${teamList(teams)}`,
+      ),
     );
+    return { team, current: found.find((app) => app.team === team) };
   }
   if (found.length === 0 && fresh) {
     const teams = xcodeTeams();
-    if (teams.length !== 1) {
+    if (teams.length === 0) {
       throw new Error(
-        teams.length === 0
-          ? `Xcode has no development certificate; sign in at ${accountsHint}, or choose a team with --team ID`
-          : `choose a team with --team ID:\n${teamList(teams)}`,
+        xcodeSignedIn()
+          ? `Xcode has no development certificate; add one at ${accountsHint} › Manage Certificates, or choose a team with --team ID`
+          : `Xcode has no account; sign in at ${accountsHint}, or choose a team with --team ID`,
       );
     }
-    return { team: teams[0].id, current: undefined };
+    const team =
+      teams.length === 1
+        ? teams[0].id
+        : await choose(
+            context,
+            "Choose a team",
+            teams.map(teamChoice),
+            new Error(`choose a team with --team ID:\n${teamList(teams)}`),
+          );
+    return { team, current: undefined };
   }
   return { team: found[0]?.team, current: found[0] };
 }
 
 const buildText = (app) => `Swipt ${app.version} (${app.bundleVersion})`;
 
+async function signingPeriod(device, id, team) {
+  const names = [id, "*"].map((it) => `iOS Team Provisioning Profile: ${it}`);
+  const profiles = await step(
+    `reading the signing on ${device.name}`,
+    () => provisioningProfiles(device.udid),
+    { transient: true },
+  );
+  return profiles
+    .filter(
+      (profile) =>
+        profile.teamIdentifier === team && names.includes(profile.name),
+    )
+    .map((profile) => ({
+      creation: Date.parse(profile.creationDate),
+      expiration: Date.parse(profile.expirationDate),
+    }))
+    .reduce((latest, it) => (it.expiration > latest.expiration ? it : latest), {
+      creation: 0,
+      expiration: 0,
+    });
+}
+
+const dateText = (time) => new Date(time).toLocaleString();
+
+async function askPasscode(context) {
+  const type = await select(
+    {
+      message:
+        "Set up auto-unlock? Swipt can then unlock this device by itself",
+      choices: [
+        { name: "4 or 6 digit passcode", short: "4 or 6 digits", value: "pin" },
+        { name: "Custom numeric passcode", short: "numeric", value: "numeric" },
+        {
+          name: "Custom alphanumeric passcode",
+          short: "alphanumeric",
+          value: "alphanumeric",
+        },
+        { name: "No Thanks", value: null },
+      ],
+    },
+    { output: process.stderr, signal: context.signal },
+  );
+  if (type === null) {
+    return undefined;
+  }
+  const options = (passcode) => ({ passcode, "passcode-type": type });
+  return passcodeOf(
+    options(
+      await password(
+        {
+          message: "Device passcode",
+          validate(passcode) {
+            try {
+              passcodeOf(options(passcode));
+              return passcode !== "" || "enter the passcode";
+            } catch (error) {
+              return error.message;
+            }
+          },
+        },
+        { output: process.stderr, signal: context.signal },
+      ),
+    ),
+  );
+}
+
 async function deploy(context, onlyNewer) {
-  const device = coreDevice(context.options.device, { required: true });
-  const { team, current } = locate(context.options, device, !onlyNewer);
+  const device = await coreDevice(
+    context,
+    onlyNewer
+      ? { filter: (devices) => sideloadedDevices(devices, installHint) }
+      : undefined,
+  );
+  const { team, current } = await locate(context, device, !onlyNewer);
   if (current === undefined && onlyNewer) {
     throw new Error(
-      `Swipt is not sideloaded on ${device.name}${team === undefined ? "" : ` by team ${team}`}; install it with "swipt sideload install"`,
+      `Swipt is not sideloaded on ${device.name}${team === undefined ? "" : ` by team ${team}`}${installHint}`,
     );
   }
   const passcode =
-    current === undefined ? passcodeOf(context.options) : undefined;
-  const release = await findRelease(context.options.nightly, context.signal);
-  if (current !== undefined) {
+    current === undefined &&
+    interactive(context) &&
+    context.options.passcode === undefined &&
+    context.options["passcode-type"] === undefined &&
+    !context.options["no-setup"]
+      ? await askPasscode(context)
+      : passcodeOf(context.options);
+  const release = await step(
+    "checking the latest release",
+    () => findRelease(context.options.nightly, context.signal),
+    { transient: true },
+  );
+  const id = `${bundleId}.${team}`;
+  if (onlyNewer) {
     const installed = Number(current.bundleVersion);
-    if (installed === release.build) {
+    const signing = await signingPeriod(device, id, team);
+    if (installed >= release.build && !expiresSoon(signing)) {
       console.log(
-        `${buildText(current)} on ${device.name} is already ${release.tag}`,
+        `${buildText(current)} on ${device.name} is ${installed === release.build ? `already ${release.tag}` : `newer than ${release.tag} (${release.build})`}; its signing expires ${dateText(signing.expiration)}`,
       );
+      if (
+        !context.options["no-setup"] &&
+        !context.options["no-setup-pair"] &&
+        (await pair(device, id))
+      ) {
+        await openConfigured(context, device, id, passcode);
+      }
       return;
     }
-    if (onlyNewer && installed > release.build) {
-      console.log(
-        `${buildText(current)} on ${device.name} is newer than ${release.tag} (${release.build})`,
+    if (installed > release.build) {
+      throw new Error(
+        `${buildText(current)} on ${device.name} needs new signing, but ${release.tag} (${release.build}) is older; use --nightly, or downgrade with "swipt sideload install"`,
       );
-      return;
     }
   }
-  const id = `${bundleId}.${team}`;
   const work = fs.mkdtempSync(path.join(os.tmpdir(), "swipt-sideload-"));
   try {
-    console.error(
-      `downloading Swipt ${release.version} (${release.build}) from ${release.tag}`,
+    const signing = await step(
+      `signing ${id} with team ${team} through Xcode`,
+      (update) => provision(work, id, team, device, update),
     );
     const ipa = path.join(work, "Swipt.ipa");
-    await download(release.ipa, ipa, context.signal);
-    const app = unpack(ipa, work);
-    console.error(`signing ${id} with team ${team} through Xcode`);
-    resign(app, id, provision(work, id, team, device));
-    console.error(`installing on ${device.name}`);
-    devicectl(["device", "install", "app", "--device", device.udid, app]);
-    if (current === undefined) {
-      console.error(`pairing with ${device.name}`);
-      pair(device, id, work);
-      if (passcode !== undefined) {
-        setUpAutoUnlock(device, id, work, passcode);
-      }
+    await step(
+      `downloading Swipt ${release.version} (${release.build}) from ${release.tag}`,
+      (update) => download(release.ipa, ipa, context.signal, update),
+    );
+    const app = await step("re-signing Swipt", async (update) => {
+      const unpacked = await unpack(ipa, work);
+      await resign(unpacked, id, signing, update);
+      return unpacked;
+    });
+    await step(`installing on ${device.name}`, () =>
+      devicectl(["device", "install", "app", "--device", device.udid, app]),
+    );
+    if (current === undefined && passcode !== undefined) {
+      await step("setting up auto-unlock", () =>
+        setUpAutoUnlock(device, id, work, passcode),
+      );
     }
   } finally {
     fs.rmSync(work, { recursive: true, force: true });
   }
-  const result = locate({ team }, device).current;
+  const result = (await locate({ options: { team } }, device)).current;
   if (result === undefined || Number(result.bundleVersion) !== release.build) {
     throw new Error(
       `${device.name} ${result === undefined ? `does not list ${id}` : `has ${buildText(result)}`} after the install`,
     );
   }
+  const action =
+    current === undefined
+      ? "installed"
+      : Number(current.bundleVersion) === release.build
+        ? "re-signed"
+        : "updated";
   console.log(
-    `${buildText(result)} is ${current === undefined ? "installed" : "updated"} on ${device.name}`,
+    `${buildText(result)} is ${action} on ${device.name}; its signing expires ${dateText((await signingPeriod(device, id, team)).expiration)}`,
   );
+  if (context.options["no-setup"]) {
+    await launch(device, id);
+    return;
+  }
+  if (!context.options["no-setup-pair"]) {
+    await pair(device, id);
+  }
+  await openConfigured(context, device, id, passcode);
+}
+
+const launchCommand = (device, id, args = []) => [
+  "device",
+  "process",
+  "launch",
+  "--terminate-existing",
+  "--device",
+  device.udid,
+  id,
+  ...(args.length > 0 ? ["--", ...args] : []),
+];
+
+const publishArgument = "--publish-local-network";
+const setupArgument = "--setup";
+
+async function openConfigured(context, device, id, passcode) {
   try {
-    devicectl([
-      "device",
-      "process",
-      "launch",
-      "--terminate-existing",
-      "--device",
-      device.udid,
+    await trustAndOpen(context, device, id, passcode);
+  } catch (error) {
+    if (error.message !== serverHint) {
+      throw error;
+    }
+    console.error(`${serverHint}; its developer is not trusted automatically`);
+    await launch(
+      device,
       id,
-    ]);
+      context.options["no-setup-api"] ? [] : [publishArgument],
+    );
+  }
+}
+
+async function launch(device, id, args) {
+  try {
+    await step(`opening Swipt on ${device.name}`, () =>
+      devicectl(launchCommand(device, id, args)),
+    );
   } catch (error) {
     if (/trusted by the user/.test(error.message)) {
       console.log(
-        `it opens once the team's developer app is trusted in Settings › General › VPN & Device Management on ${device.name}`,
+        `its developer is not trusted yet; run "swipt sideload install -d ${device.udid} --team ${id.slice(bundleId.length + 1)}" to trust it and open Swipt automatically, or trust it in Settings › General › VPN & Device Management on ${device.name}`,
       );
     } else if (/BSErrorCodeDescription = Locked/.test(error.message)) {
       console.log(`it opens once ${device.name} is unlocked`);
@@ -480,9 +789,14 @@ export const install = (context) => deploy(context, false);
 export const update = (context) => deploy(context, true);
 
 const serverHint =
-  "swipt-server is missing; install @swipt/cli with its optional dependencies";
+  'swipt-server is missing; install it with "npm install -g @swipt/cli --include=optional"';
 
-function serverPath() {
+async function serverPath() {
+  const root = path.dirname(import.meta.dirname);
+  if (fs.existsSync(path.join(root, "cmd/swipt-server"))) {
+    await exec("make", ["server"], { cwd: root });
+    return path.join(root, "build/swipt-server");
+  }
   let packaged;
   try {
     packaged = path.join(
@@ -508,7 +822,7 @@ const schema = [
   "INSERT INTO grdb_migrations VALUES ('0.1.0')",
 ];
 
-function setUpAutoUnlock(device, id, work, passcode) {
+async function setUpAutoUnlock(device, id, work, passcode) {
   const database = path.join(work, "Swipt.sqlite");
   const preferences = {
     serverAutoUnlocks: true,
@@ -528,7 +842,7 @@ function setUpAutoUnlock(device, id, work, passcode) {
       .map((statement) => `${statement};\n`)
       .join(""),
   });
-  devicectl([
+  await devicectl([
     "device",
     "copy",
     "to",
@@ -545,46 +859,94 @@ function setUpAutoUnlock(device, id, work, passcode) {
   ]);
 }
 
-function pair(device, id, work) {
-  const record = path.join(work, "PairingRecord.plist");
-  const result = spawnSync(
-    serverPath(),
-    ["pair", "-d", device.udid, "-o", record],
-    { encoding: "utf8", stdio: ["ignore", "ignore", "pipe"] },
-  );
-  if (result.error?.code === "ENOENT") {
-    console.error(`${serverHint}; Swipt pairs in Settings instead`);
-    return;
+const pairingDirectory = "Library/Application Support";
+const pairingFile = "PairingRecord.plist";
+
+async function hasPairing(device, id) {
+  try {
+    const { result } = await devicectl(
+      [
+        "device",
+        "info",
+        "files",
+        "--device",
+        device.udid,
+        "--domain-type",
+        "appDataContainer",
+        "--domain-identifier",
+        id,
+        "--subdirectory",
+        pairingDirectory,
+      ],
+      { parse: true },
+    );
+    return result.files.some((file) => file.name === pairingFile);
+  } catch {
+    return false;
   }
-  if (result.error) {
-    throw result.error;
+}
+
+async function pair(device, id) {
+  const paired = await step(
+    `checking the pairing of ${device.name}`,
+    () => hasPairing(device, id),
+    { transient: true },
+  );
+  if (paired) {
+    return false;
   }
-  if (result.status !== 0) {
-    console.error(
-      `pairing failed, so Swipt pairs in Settings instead: ${result.stderr.trim()}`,
-    );
-    return;
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "swipt-pairing-"));
+  let warning;
+  try {
+    await step(`pairing with ${device.name}`, async () => {
+      const record = path.join(work, pairingFile);
+      try {
+        await exec(await serverPath(), [
+          "pair",
+          "-d",
+          device.udid,
+          "-o",
+          record,
+        ]);
+      } catch (error) {
+        if (typeof error.code === "number") {
+          warning = `pairing failed, so Swipt pairs in Settings instead: ${error.stderr.trim()}`;
+        } else if (error.code === "ENOENT") {
+          warning = `${serverHint}; Swipt pairs in Settings instead`;
+        }
+        throw error;
+      }
+      await devicectl([
+        "device",
+        "copy",
+        "to",
+        "--device",
+        device.udid,
+        "--source",
+        record,
+        "--destination",
+        `${pairingDirectory}/${pairingFile}`,
+        "--domain-type",
+        "appDataContainer",
+        "--domain-identifier",
+        id,
+      ]);
+    });
+  } catch (error) {
+    if (warning === undefined) {
+      throw error;
+    }
+    console.error(warning);
+    return false;
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
   }
-  devicectl([
-    "device",
-    "copy",
-    "to",
-    "--device",
-    device.udid,
-    "--source",
-    record,
-    "--destination",
-    "Library/Application Support/PairingRecord.plist",
-    "--domain-type",
-    "appDataContainer",
-    "--domain-identifier",
-    id,
-  ]);
+  return true;
 }
 
-function serve(udid, passcode, signal) {
+async function serve(udid, passcode, signal) {
   const server = spawn(
-    serverPath(),
+    await serverPath(),
     [
       "-d",
       udid,
@@ -631,66 +993,118 @@ function serve(udid, passcode, signal) {
   };
 }
 
-export async function start(context) {
-  const passcode = passcodeOf(context.options);
-  const device = coreDevice(context.options.device, { required: true });
-  const { team, current } = locate(context.options, device);
-  if (current === undefined) {
-    throw new Error(
-      `Swipt is not sideloaded on ${device.name}${team === undefined ? "" : ` by team ${team}`}`,
-    );
-  }
-  const server = serve(device.udid, passcode, context.signal);
+async function trustAndOpen(context, device, id, passcode) {
+  const lines = [];
+  let failure;
   try {
-    const client = open({ url: await server.url, token: "" });
-    let failure;
-    for await (const response of client.repl.execute(
-      {
-        code: fs.readFileSync(
-          new URL("sideload/trust.js", import.meta.url),
-          "utf8",
-        ),
-        args: [current.bundleIdentifier],
-        program: true,
-      },
-      { signal: context.signal },
-    )) {
-      switch (response.part.case) {
-        case "console": {
-          const output = response.part.value;
-          (output.level === LogLevel.ERROR || output.level === LogLevel.WARN
-            ? console.error
-            : console.log)(output.text);
-          break;
+    await step(`opening Swipt on ${device.name}`, async (update) => {
+      update("starting swipt-server");
+      const waiting = passcode === undefined && process.stderr.isTTY;
+      let server;
+      let url;
+      while (url === undefined) {
+        server = await serve(device.udid, passcode, context.signal);
+        try {
+          url = await server.url;
+        } catch (error) {
+          if (!/is connected to this Mac/.test(error.message)) {
+            throw error;
+          }
+          if (!waiting) {
+            throw new Error(
+              `${device.name} is not reachable; unlock it or pass --passcode, then run this again`,
+            );
+          }
+          update("unlock the device to continue");
         }
-        case "error":
-          failure = response.part.value;
-          break;
       }
-    }
-    if (failure) {
-      throw printScriptError(failure);
+      try {
+        const client = open({ url, token: "" });
+        const run = async (args) => {
+          for await (const response of client.repl.execute(
+            {
+              code: fs.readFileSync(
+                new URL("sideload/trust.js", import.meta.url),
+                "utf8",
+              ),
+              args,
+              program: true,
+            },
+            { signal: context.signal },
+          )) {
+            switch (response.part.case) {
+              case "console": {
+                const output = response.part.value;
+                if (output.level === LogLevel.DEBUG) {
+                  update(output.text);
+                } else {
+                  lines.push(output);
+                }
+                break;
+              }
+              case "error":
+                failure = response.part.value;
+                break;
+            }
+          }
+          if (failure) {
+            throw new Error(failure.message);
+          }
+        };
+        const runArguments = (mode) => [id, mode, waiting ? "wait" : ""];
+        await run(runArguments("trust"));
+        update("opening Swipt");
+        await devicectl(
+          launchCommand(device, id, [
+            setupArgument,
+            ...(context.options["no-setup-api"] ? [] : [publishArgument]),
+          ]),
+        );
+        await run(runArguments("prompts"));
+      } finally {
+        await server.stop();
+      }
+    });
+  } catch (error) {
+    if (failure === undefined) {
+      throw error;
     }
   } finally {
-    await server.stop();
+    for (const output of lines) {
+      (output.level === LogLevel.ERROR || output.level === LogLevel.WARN
+        ? console.error
+        : console.log)(output.text);
+    }
+  }
+  if (failure) {
+    if (/\bdevice is locked\b/.test(failure.message)) {
+      throw new Error(
+        passcode === undefined
+          ? `${device.name} is locked; unlock it or pass --passcode, then run this again`
+          : `${device.name} did not unlock; check --passcode and --passcode-type, then run this again`,
+      );
+    }
+    throw printScriptError(failure);
   }
 }
 
-export function uninstall(context) {
-  const device = coreDevice(context.options.device, { required: true });
-  const { team, current } = locate(context.options, device);
+export async function uninstall(context) {
+  const device = await coreDevice(context, { filter: sideloadedDevices });
+  const { team, current } = await locate(context, device);
   if (current === undefined) {
     throw new Error(
       `Swipt is not sideloaded on ${device.name}${team === undefined ? "" : ` by team ${team}`}`,
     );
   }
-  devicectl([
-    "device",
-    "uninstall",
-    "app",
-    "--device",
-    device.udid,
-    current.bundleIdentifier,
-  ]);
+  await step(`removing Swipt from ${device.name}`, () =>
+    devicectl([
+      "device",
+      "uninstall",
+      "app",
+      "--device",
+      device.udid,
+      current.bundleIdentifier,
+    ]),
+  );
   console.log(`removed ${buildText(current)} from ${device.name}`);
 }