mobile-wdio-kit 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# mobile-wdio-kit
+
+CLI to **scaffold** a WebdriverIO + Appium mobile test project (Android/iOS, optional Cursor MCP wiring, Vitest, `patch-package`) and run **`doctor`** for an environment preflight.
+
+- **License:** [LICENSE](./LICENSE) (ISC).
+- **Third-party & trademarks:** each scaffolded project includes `THIRD_PARTY.md` (vendored from the monorepo root when maintainers run `npm run kit:sync`). Read it before redistributing the demo APK or publishing derivative work.
+
+> Before `npm publish`, confirm `package.json` `repository` / `bugs` / `homepage` match your public repo. See [RELEASING.md](../../RELEASING.md).
+
+## Install
+
+```bash
+npm install -g mobile-wdio-kit
+```
+
+Or use **npx** (no global install):
+
+```bash
+npx mobile-wdio-kit@latest create ./my-mobile-tests
+```
+
+## `create <directory>`
+
+Copies the embedded template, sets `package.json` `name` from the folder (or `--name`), copies `.env.example` → `.env`, runs **`npm install`** (runs **`patch-package`**), then downloads the **WebdriverIO demo Android APK** unless `--no-demo-apk`.
+
+**Path rules:** the directory is resolved with `path.resolve()` from your **current working directory** (where you run the command), not from the global npm package path. Relative paths (`./foo`), absolute paths (`/tmp/foo`), and `~/foo` (tilde expanded by your shell or by the CLI) are supported.
+
+| Option | Meaning |
+|--------|---------|
+| `--force` | Overwrite a non-empty directory. |
+| `--no-install` | Skip `npm install`. |
+| `--no-demo-apk` | Skip demo APK download. |
+| `--name <name>` | Override `package.json` `name`. |
+
+## `doctor`
+
+Checks Node (≥ 18), npm, Android SDK / `adb`, `JAVA_HOME`, demo APK, `.env`, local Appium + drivers, Xcode/simctl (macOS), and Appium `/status`. Exit code **1** only if a **required** check fails (Node version). Warnings are **!** and still exit **0**.
+
+| Option | Meaning |
+|--------|---------|
+| `--cwd <path>` | Project root (default: `process.cwd()`). |
+| `--json` | JSON on stdout. |
+| `--appium-url <url>` | Override `/status` URL. |
+
+In generated projects, **`npm run doctor`** uses a **vendored** script (no registry dependency on this package).
+
+## Maintainers (monorepo)
+
+```bash
+npm run kit:sync    # repo root: refresh template/
+cd packages/mobile-wdio-kit && npm publish --access public
+```
+
+`prepack` fails if `template/` is missing—run `kit:sync` first.

package/bin/cli.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { createProject } from "../lib/create.mjs";
+import { createDoctorMain } from "../lib/doctor-cli.mjs";
+import { printDoctorResult, runDoctor } from "../lib/doctor.mjs";
+
+const runDoctorMain = createDoctorMain({ runDoctor, printDoctorResult });
+
+function help() {
+  process.stdout.write(`
+mobile-wdio-kit — scaffold + environment checks for WebdriverIO + Appium mobile projects
+
+Usage:
+  mobile-wdio-kit create <directory> [options]
+  mobile-wdio-kit doctor [options]
+  mobile-wdio-kit --help
+
+Commands:
+  create    Copy the framework template, run npm install, fetch the demo Android APK.
+  doctor    Verify Node, Android SDK, adb, Appium drivers, demo APK, .env, Appium server.
+
+Where create writes:
+  The target path is resolved with Node path.resolve() from your current working directory
+  (the shell’s cwd—not the global npm install location). Examples:
+    create ./my-app           →  <cwd>/my-app
+    create /tmp/foo           →  /tmp/foo
+    create ~/Desktop/foo      →  your home/Desktop/foo (tilde expanded by shell or by the CLI)
+
+Create options:
+  --force              Overwrite a non-empty directory (dangerous).
+  --no-install         Skip npm install (you must install dependencies yourself).
+  --no-demo-apk        Skip downloading the WebdriverIO demo APK.
+  --name <pkg-name>    package.json name (default: folder name).
+
+Doctor options:
+  --cwd <path>         Project root to inspect (default: process.cwd()).
+  --json               Machine-readable JSON on stdout.
+  --appium-url <url>   Override status URL (default: from .env or http://127.0.0.1:4723/status).
+
+Examples:
+  npx mobile-wdio-kit@latest create ./my-mobile-tests
+  cd my-mobile-tests && npm run doctor
+  mobile-wdio-kit doctor --cwd ./my-mobile-tests
+
+`);
+}
+
+function parseCreateArgs(argv) {
+  const out = {
+    target: null,
+    force: false,
+    skipInstall: false,
+    skipDemoApk: false,
+    name: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--force") out.force = true;
+    else if (a === "--no-install") out.skipInstall = true;
+    else if (a === "--no-demo-apk") out.skipDemoApk = true;
+    else if (a === "--name") {
+      out.name = argv[i + 1];
+      i += 1;
+    } else if (!a.startsWith("-") && !out.target) out.target = a;
+    else {
+      throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+    help();
+    process.exit(0);
+  }
+
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+
+  if (cmd === "create") {
+    const args = parseCreateArgs(rest);
+    if (!args.target) {
+      console.error("Error: create requires a target directory.\n");
+      help();
+      process.exit(1);
+    }
+    try {
+      const { targetAbs, name } = createProject({
+        targetDir: args.target,
+        force: args.force,
+        skipInstall: args.skipInstall,
+        skipDemoApk: args.skipDemoApk,
+        projectName: args.name,
+      });
+      process.stdout.write(
+        `\nCreated project "${name}" at:\n  ${targetAbs}\n\nNext:\n  cd ${args.target}\n  npm run doctor\n  npm run test:android   # with emulator + Appium\n`,
+      );
+      process.exit(0);
+    } catch (e) {
+      console.error(String(/** @type {Error} */ (e).message || e));
+      process.exit(1);
+    }
+  }
+
+  if (cmd === "doctor") {
+    try {
+      process.exit(await runDoctorMain(rest));
+    } catch (e) {
+      console.error(String(/** @type {Error} */ (e).message || e));
+      process.exit(1);
+    }
+  }
+
+  console.error(`Unknown command: ${cmd}\n`);
+  help();
+  process.exit(1);
+}
+
+main();

package/lib/create.mjs

@@ -0,0 +1,128 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  copyFileSync,
+  rmSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function templateRoot() {
+  return resolve(__dirname, "..", "template");
+}
+
+/** Resolve `~/...` even when the shell did not expand it (e.g. quoted path). */
+function expandUserDir(targetDir) {
+  const t = String(targetDir).trim();
+  if (t === "~") return homedir();
+  if (t.startsWith("~/") || t.startsWith("~\\")) {
+    return join(homedir(), t.slice(2));
+  }
+  return t;
+}
+
+function kebabName(raw) {
+  return String(raw || "mobile-wdio-project")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "mobile-wdio-project";
+}
+
+/**
+ * @param {{ targetDir: string; force?: boolean; skipInstall?: boolean; skipDemoApk?: boolean; projectName?: string }} opts
+ */
+export function createProject(opts) {
+  const template = templateRoot();
+  if (!existsSync(join(template, "package.json"))) {
+    throw new Error(
+      "Template missing in mobile-wdio-kit. If you develop the kit from git, run: npm run kit:sync (repo root).",
+    );
+  }
+
+  const targetAbs = resolve(expandUserDir(opts.targetDir));
+  const name = kebabName(opts.projectName ?? basename(targetAbs));
+
+  if (existsSync(targetAbs)) {
+    const entries = readDirSafe(targetAbs);
+    if (entries.length > 0 && !opts.force) {
+      throw new Error(
+        `Target directory is not empty: ${targetAbs}\nUse --force to overwrite.`,
+      );
+    }
+    if (entries.length > 0 && opts.force) {
+      rmSync(targetAbs, { recursive: true, force: true });
+    }
+  }
+
+  mkdirSync(targetAbs, { recursive: true });
+  cpSync(template, targetAbs, { recursive: true });
+
+  const pkgPath = join(targetAbs, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.name = name;
+  delete pkg.private;
+  if (!pkg.description) {
+    pkg.description = "WebdriverIO mobile tests + Appium + Cursor MCP (scaffolded).";
+  }
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+  const envExample = join(targetAbs, ".env.example");
+  const envDest = join(targetAbs, ".env");
+  if (existsSync(envExample) && !existsSync(envDest)) {
+    copyFileSync(envExample, envDest);
+  }
+
+  if (!opts.skipInstall) {
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    const install = spawnSync(npm, ["install"], {
+      cwd: targetAbs,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: process.env,
+    });
+    if (install.status !== 0) {
+      throw new Error("`npm install` failed in the new project.");
+    }
+  }
+
+  if (!opts.skipDemoApk && !opts.skipInstall) {
+    const dl = join(targetAbs, "scripts", "download-demo-android.mjs");
+    if (existsSync(dl)) {
+      const r = spawnSync(process.execPath, [dl], {
+        cwd: targetAbs,
+        stdio: "inherit",
+        env: process.env,
+      });
+      if (r.status !== 0) {
+        console.warn(
+          "[mobile-wdio-kit] Demo APK download failed — run `npm run setup:demo-android` inside the project.",
+        );
+      }
+    }
+  }
+
+  return { targetAbs, name };
+}
+
+function basename(p) {
+  const s = p.replace(/[/\\]+$/, "");
+  const i = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  return i >= 0 ? s.slice(i + 1) : s;
+}
+
+function readDirSafe(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}

package/lib/doctor-cli.mjs

@@ -0,0 +1,38 @@
+/** Shared doctor argv + runner factory (used by global CLI and vendored template). */
+
+export function parseDoctorArgs(argv) {
+  const out = { cwd: process.cwd(), json: false, appiumUrl: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--cwd") {
+      out.cwd = argv[i + 1];
+      i += 1;
+    } else if (a === "--appium-url") {
+      out.appiumUrl = argv[i + 1];
+      i += 1;
+    } else {
+      throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+/** @param {{ runDoctor: Function; printDoctorResult: Function }} deps */
+export function createDoctorMain(deps) {
+  const { runDoctor, printDoctorResult } = deps;
+  return async function runDoctorMain(argv) {
+    const args = parseDoctorArgs(argv);
+    const result = await runDoctor({
+      cwd: args.cwd,
+      json: args.json,
+      appiumUrl: args.appiumUrl ?? undefined,
+    });
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      printDoctorResult(result);
+    }
+    return result.ok ? 0 : 1;
+  };
+}

package/lib/doctor.mjs

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const MIN_NODE = 18;
+
+/** @typedef {{ ok: boolean; level: "ok" | "warn" | "fail"; title: string; detail?: string; fix?: string }} Check */
+
+function nodeMajor(version) {
+  const m = /^v?(\d+)/.exec(version.trim());
+  return m ? Number(m[1]) : 0;
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+    ...opts,
+  });
+  return {
+    code: r.status ?? 1,
+    out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim(),
+  };
+}
+
+function which(name) {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  const r = run(cmd, [name]);
+  return r.code === 0 ? r.out.split("\n")[0].trim() : "";
+}
+
+/**
+ * @param {{ cwd?: string; json?: boolean; appiumUrl?: string }} opts
+ */
+export async function runDoctor(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const checks = /** @type {Check[]} */ ([]);
+
+  const add = (c) => checks.push(c);
+
+  const nodeVer = process.version;
+  const major = nodeMajor(nodeVer);
+  add({
+    ok: major >= MIN_NODE,
+    level: major >= MIN_NODE ? "ok" : "fail",
+    title: `Node.js ${nodeVer}`,
+    detail: `Required: >= ${MIN_NODE}`,
+    fix:
+      major < MIN_NODE
+        ? "Install Node.js 18+ (LTS recommended) from https://nodejs.org/"
+        : undefined,
+  });
+
+  const npmWhich = which("npm");
+  add({
+    ok: Boolean(npmWhich),
+    level: npmWhich ? "ok" : "warn",
+    title: "npm on PATH",
+    detail: npmWhich || "not found",
+    fix: npmWhich ? undefined : "Install Node.js with npm, or use a version manager (nvm, fnm).",
+  });
+
+  const androidHome =
+    process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || "";
+  const sdkOk = Boolean(androidHome && existsSync(androidHome));
+  add({
+    ok: sdkOk,
+    level: sdkOk ? "ok" : "warn",
+    title: "Android SDK (ANDROID_HOME or ANDROID_SDK_ROOT)",
+    detail: sdkOk ? androidHome : "not set or path missing",
+    fix: sdkOk
+      ? undefined
+      : "Install Android Studio / cmdline-tools, then export ANDROID_HOME (e.g. ~/Library/Android/sdk on macOS).",
+  });
+
+  const adbPath = which("adb");
+  const adbOk = Boolean(adbPath);
+  add({
+    ok: adbOk,
+    level: adbOk ? "ok" : "warn",
+    title: "adb on PATH",
+    detail: adbOk ? adbPath : "not found",
+    fix: adbOk
+      ? undefined
+      : "Add platform-tools to PATH (inside your Android SDK).",
+  });
+
+  if (adbOk) {
+    const dev = run("adb", ["devices"]);
+    const lines = dev.out.split("\n").filter(Boolean);
+    const deviceLines = lines.filter(
+      (l) => l.includes("\tdevice") || l.includes("\temulator"),
+    );
+    add({
+      ok: deviceLines.length > 0,
+      level: deviceLines.length > 0 ? "ok" : "warn",
+      title: "ADB device / emulator",
+      detail:
+        deviceLines.length > 0
+          ? `${deviceLines.length} online`
+          : "no devices in `adb devices`",
+      fix:
+        deviceLines.length > 0
+          ? undefined
+          : "Start an emulator (`emulator -avd …`) or plug in a device with USB debugging.",
+    });
+  }
+
+  const javaHome = process.env.JAVA_HOME || "";
+  const javaOk = Boolean(javaHome && existsSync(javaHome));
+  add({
+    ok: javaOk,
+    level: javaOk ? "ok" : "warn",
+    title: "JAVA_HOME (recommended for Android toolchain)",
+    detail: javaOk ? javaHome : "not set or path missing",
+    fix: javaOk
+      ? undefined
+      : "Point JAVA_HOME at a JDK 17+ install (Android Studio bundled JBR works).",
+  });
+
+  const demoApk = join(cwd, "apps", "android.wdio.native.app.v2.0.0.apk");
+  const apkOk = existsSync(demoApk);
+  add({
+    ok: apkOk,
+    level: apkOk ? "ok" : "warn",
+    title: "Demo Android APK (apps/android.wdio.native.app.v2.0.0.apk)",
+    detail: apkOk ? demoApk : "missing",
+    fix: apkOk
+      ? undefined
+      : "Run `npm run setup:demo-android` in this project (or set ANDROID_APP_PATH to your app).",
+  });
+
+  const envFile = join(cwd, ".env");
+  add({
+    ok: existsSync(envFile),
+    level: existsSync(envFile) ? "ok" : "warn",
+    title: ".env present",
+    detail: existsSync(envFile) ? envFile : "missing",
+    fix: existsSync(envFile)
+      ? undefined
+      : "Copy `.env.example` to `.env` and adjust device names / paths.",
+  });
+
+  let pkg = null;
+  try {
+    pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+  } catch {
+    add({
+      ok: false,
+      level: "warn",
+      title: "package.json in cwd",
+      detail: "not readable — run doctor from the scaffolded project root",
+    });
+  }
+
+  if (pkg) {
+    const appiumBin = join(cwd, "node_modules", ".bin", "appium");
+    const appiumLocal = existsSync(appiumBin);
+    add({
+      ok: appiumLocal,
+      level: appiumLocal ? "ok" : "warn",
+      title: "Appium (local devDependency)",
+      detail: appiumLocal ? appiumBin : "run npm install in this project",
+      fix: appiumLocal ? undefined : "From project root: npm install",
+    });
+
+    if (appiumLocal) {
+      const appiumCli =
+        process.platform === "win32"
+          ? join(cwd, "node_modules", ".bin", "appium.cmd")
+          : appiumBin;
+      const exe = existsSync(appiumCli) ? appiumCli : appiumBin;
+      const drivers = spawnSync(exe, ["driver", "list", "--installed"], {
+        cwd,
+        encoding: "utf8",
+        env: process.env,
+        shell: false,
+      });
+      const driverText = `${drivers.stdout ?? ""}${drivers.stderr ?? ""}`;
+      const hasU2 = /uiautomator2/i.test(driverText);
+      const hasXc = /xcuitest/i.test(driverText);
+      add({
+        ok: hasU2,
+        level: hasU2 ? "ok" : "warn",
+        title: "Appium UiAutomator2 driver",
+        detail: hasU2 ? "installed" : "not detected",
+        fix: hasU2 ? undefined : "npm run appium:driver:android",
+      });
+      if (process.platform === "darwin") {
+        add({
+          ok: hasXc,
+          level: hasXc ? "ok" : "warn",
+          title: "Appium XCUITest driver (iOS)",
+          detail: hasXc ? "installed" : "not detected",
+          fix: hasXc ? undefined : "npm run appium:driver:ios",
+        });
+      }
+    }
+  }
+
+  if (process.platform === "darwin") {
+    const xc = run("xcodebuild", ["-version"]);
+    add({
+      ok: xc.code === 0,
+      level: xc.code === 0 ? "ok" : "warn",
+      title: "Xcode (xcodebuild)",
+      detail: xc.code === 0 ? xc.out.split("\n")[0] : xc.out || "not found",
+      fix:
+        xc.code === 0
+          ? undefined
+          : "Install Xcode from the App Store and run `xcode-select --install` if needed.",
+    });
+
+    const sim = run("xcrun", ["simctl", "list", "devices", "available"]);
+    const simOk = sim.code === 0 && /iPhone|iPad/.test(sim.out);
+    add({
+      ok: simOk,
+      level: simOk ? "ok" : "warn",
+      title: "iOS Simulator (simctl)",
+      detail: simOk ? "at least one iPhone/iPad device listing present" : sim.out || "failed",
+      fix: simOk
+        ? undefined
+        : "Open Xcode → Settings → Platforms and install a simulator runtime.",
+    });
+  } else {
+    add({
+      ok: true,
+      level: "ok",
+      title: "iOS tooling",
+      detail: "skipped (not macOS)",
+    });
+  }
+
+  const appiumUrl =
+    opts.appiumUrl ??
+    (() => {
+      try {
+        if (existsSync(join(cwd, ".env"))) {
+          const raw = readFileSync(join(cwd, ".env"), "utf8");
+          const host =
+            raw.match(/^\s*APPIUM_HOST\s*=\s*(.+)$/m)?.[1]?.trim() ??
+            "127.0.0.1";
+          const port =
+            raw.match(/^\s*APPIUM_PORT\s*=\s*(.+)$/m)?.[1]?.trim() ?? "4723";
+          return `http://${host}:${port}/status`;
+        }
+      } catch {
+        /* ignore */
+      }
+      return "http://127.0.0.1:4723/status";
+    })();
+
+  try {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), 2500);
+    const res = await fetch(appiumUrl, { signal: ac.signal });
+    clearTimeout(t);
+    const body = res.ok ? await res.json().catch(() => ({})) : {};
+    const ready = body?.value?.ready === true;
+    add({
+      ok: ready,
+      level: ready ? "ok" : "warn",
+      title: "Appium server reachable",
+      detail: `${appiumUrl} → HTTP ${res.status}${ready ? ", ready" : ""}`,
+      fix: ready
+        ? undefined
+        : "Start Appium: npm run appium:start (or your own 127.0.0.1:4723 server).",
+    });
+  } catch (e) {
+    add({
+      ok: false,
+      level: "warn",
+      title: "Appium server reachable",
+      detail: String(/** @type {Error} */ (e).message || e),
+      fix: "Start Appium on APPIUM_HOST:APPIUM_PORT (see .env).",
+    });
+  }
+
+  const failed = checks.filter((c) => c.level === "fail");
+  const warns = checks.filter((c) => c.level === "warn");
+
+  if (opts.json) {
+    return {
+      ok: failed.length === 0,
+      summary: {
+        fail: failed.length,
+        warn: warns.length,
+        ok: checks.filter((c) => c.level === "ok").length,
+      },
+      checks,
+    };
+  }
+
+  const icon = (c) =>
+    c.level === "ok" ? "✓" : c.level === "warn" ? "!" : "✗";
+
+  const lines = [
+    "",
+    "mobile-wdio-kit — doctor",
+    "========================",
+    "",
+    ...checks.map(
+      (c) =>
+        `${icon(c)} ${c.title}${c.detail ? `\n    ${c.detail.split("\n").join("\n    ")}` : ""}${c.fix ? `\n    → ${c.fix}` : ""}`,
+    ),
+    "",
+    failed.length
+      ? `Result: ${failed.length} required check(s) failed.`
+      : warns.length
+        ? `Result: OK (with ${warns.length} warning(s)).`
+        : "Result: all checks passed.",
+    "",
+  ];
+
+  return {
+    ok: failed.length === 0,
+    text: lines.join("\n"),
+    checks,
+  };
+}
+
+export function printDoctorResult(result) {
+  if (typeof result.text === "string") process.stdout.write(result.text);
+}