@yoqa/cli 0.3.10 → 0.3.12

package/README.md

@@ -10,6 +10,12 @@ npx @yoqa/cli health
 
 After a global install, the `yoqa` command is on your PATH.
 
-Requires a running Yoqa runner (desktop app, or `bun run runner` from a monorepo checkout) at `http://127.0.0.1:7420` by default.
+The CLI talks to the local runner at `http://127.0.0.1:7420` by default. If nothing is listening, `yoqa` auto-starts `@yoqa/runner` (requires [Bun](https://bun.sh)). You can also run it in the foreground:
+
+```bash
+yoqa serve
+```
+
+Disable auto-start with `YOQA_NO_AUTOSTART=1`. Override the URL with `YOQA_RUNNER_HOST` / `YOQA_RUNNER_PORT` / `YOQA_RUNNER_URL`.
 
 See [CLI docs](https://yoqa.mintlify.app/docs/cli).

package/dist/main.js

@@ -2122,7 +2122,7 @@ var require_commander = __commonJS((exports) => {
 });
 
 // src/main.ts
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 
 // ../../node_modules/zod/v3/external.js
 var exports_external = {};
@@ -7850,14 +7850,16 @@ var {
 // package.json
 var package_default = {
   name: "@yoqa/cli",
-  version: "0.3.10",
+  version: "0.3.12",
   description: "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
   license: "UNLICENSED",
   type: "module",
   bin: {
     yoqa: "dist/main.js"
   },
-  files: ["dist"],
+  files: [
+    "dist"
+  ],
   engines: {
     node: ">=20"
   },
@@ -7870,7 +7872,14 @@ var package_default = {
   bugs: {
     url: "https://github.com/Aris-ngoy/qa-agent/issues"
   },
-  keywords: ["yoqa", "cli", "mobile", "qa", "appium", "testing"],
+  keywords: [
+    "yoqa",
+    "cli",
+    "mobile",
+    "qa",
+    "appium",
+    "testing"
+  ],
   scripts: {
     yoqa: "bun run src/main.ts",
     build: "bun run build.ts",
@@ -7878,6 +7887,9 @@ var package_default = {
     check: "tsc --noEmit",
     health: "bun run src/main.ts health"
   },
+  dependencies: {
+    "@yoqa/runner": "0.3.12"
+  },
   devDependencies: {
     "@types/node": "^22.15.30",
     "@yoqa/runner-client": "workspace:*",
@@ -7890,15 +7902,402 @@ var package_default = {
   }
 };
 
-// src/main.ts
-function runnerBaseUrl() {
-  const host = process.env.YOQA_RUNNER_HOST ?? "127.0.0.1";
-  const port = Number(process.env.YOQA_RUNNER_PORT ?? "7420");
+// src/ensure-runner.ts
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { createRequire as createRequire2 } from "node:module";
+import { homedir as osHomedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var DEFAULT_RUNNER_HOST = "127.0.0.1";
+var DEFAULT_RUNNER_PORT = 7420;
+var HEALTH_POLL_MS = 400;
+var HEALTH_TIMEOUT_MS = 20000;
+
+class RunnerStartError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RunnerStartError";
+  }
+}
+function runnerBaseUrlFromEnv(env = process.env) {
+  const fromUrl = env.YOQA_RUNNER_URL?.trim();
+  if (fromUrl)
+    return fromUrl.replace(/\/$/, "");
+  const host = env.YOQA_RUNNER_HOST ?? DEFAULT_RUNNER_HOST;
+  const port = Number(env.YOQA_RUNNER_PORT ?? String(DEFAULT_RUNNER_PORT));
   if (!Number.isFinite(port) || port <= 0) {
     throw new Error("YOQA_RUNNER_PORT must be a positive number");
   }
   return `http://${host}:${port}`;
 }
+function shouldSkipAutostart(env = process.env) {
+  const raw = env.YOQA_NO_AUTOSTART?.trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
+}
+function isRunnerHealth(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const record = value;
+  return record.ok === true && record.service === "yoqa-runner" && typeof record.version === "string" && record.version.length > 0;
+}
+function execRootsFrom(execPath, argv0) {
+  const roots = [];
+  for (const candidate of [execPath, argv0]) {
+    if (!candidate)
+      continue;
+    const dir = dirname(candidate);
+    if (!roots.includes(dir))
+      roots.push(dir);
+  }
+  return roots;
+}
+function packagedYoqaRunnerCandidates(roots) {
+  const fileName = "yoqa-runner";
+  const paths = [];
+  for (const root of roots) {
+    paths.push(join(root, fileName), join(root, "../Resources/app.asar.unpacked/runner", fileName), join(root, "../Resources/runner", fileName), join(root, "Resources/app.asar.unpacked/runner", fileName), join(root, "Resources/runner", fileName));
+  }
+  return paths;
+}
+function yoqaRoot(homedir) {
+  return join(homedir, ".yoqa");
+}
+function runnerPidPath(homedir) {
+  return join(yoqaRoot(homedir), "runner.pid");
+}
+var BUN_MISSING_MESSAGE = `Could not find Bun, which is required to start the Yoqa runner.
+Install: https://bun.sh  (curl -fsSL https://bun.sh/install | bash)
+Or set YOQA_RUNNER_BIN to a yoqa-runner binary.`;
+var RUNNER_NOT_FOUND_MESSAGE = "Could not locate the Yoqa runner. Install @yoqa/cli (includes @yoqa/runner) and Bun, or set YOQA_RUNNER_BIN.";
+var REPO_MARKER = join("services", "runner", "src", "index.ts");
+async function findRepoRoot(starts, pathExists) {
+  for (const start of starts) {
+    if (!start)
+      continue;
+    let dir = start;
+    for (let i = 0;i < 14; i++) {
+      if (await pathExists(join(dir, REPO_MARKER)))
+        return dir;
+      const parent = dirname(dir);
+      if (parent === dir)
+        break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+async function resolvePublishedRunnerEntry(fromUrl) {
+  try {
+    const require2 = createRequire2(fromUrl);
+    const pkgJson = require2.resolve("@yoqa/runner/package.json");
+    return join(dirname(pkgJson), "dist", "index.js");
+  } catch {
+    return null;
+  }
+}
+async function resolveRunnerLaunch(deps) {
+  const binEnv = deps.env.YOQA_RUNNER_BIN?.trim();
+  if (binEnv && await deps.pathExists(binEnv)) {
+    return { command: [binEnv], source: "env" };
+  }
+  const onPath = await deps.which("yoqa-runner");
+  if (onPath) {
+    return { command: [onPath], source: "path" };
+  }
+  const packagedCandidates = packagedYoqaRunnerCandidates(execRootsFrom(deps.execPath, deps.argv0));
+  for (const candidate of packagedCandidates) {
+    if (await deps.pathExists(candidate)) {
+      return { command: [candidate], source: "packaged" };
+    }
+  }
+  const fromPath = fileURLToPath(deps.fromUrl);
+  const repoRoot = await findRepoRoot([deps.env.YOQA_REPO_ROOT?.trim() ?? "", deps.cwd, dirname(fromPath)], deps.pathExists);
+  if (repoRoot) {
+    const bun = await deps.findBun();
+    if (!bun)
+      throw new RunnerStartError(BUN_MISSING_MESSAGE);
+    const entry = join(repoRoot, REPO_MARKER);
+    return {
+      command: [bun, "run", entry],
+      cwd: join(repoRoot, "services", "runner"),
+      source: "monorepo"
+    };
+  }
+  const pkgEntry = await deps.resolvePackageEntry();
+  if (pkgEntry && await deps.pathExists(pkgEntry)) {
+    const bun = await deps.findBun();
+    if (!bun)
+      throw new RunnerStartError(BUN_MISSING_MESSAGE);
+    return { command: [bun, pkgEntry], source: "package" };
+  }
+  throw new RunnerStartError(RUNNER_NOT_FOUND_MESSAGE);
+}
+async function fetchRunnerHealth(baseUrl, timeoutMs = 1500) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/$/, "")}/health`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok)
+      return null;
+    const json = await response.json();
+    return isRunnerHealth(json) ? json : null;
+  } catch {
+    return null;
+  }
+}
+async function waitForRunnerHealth(fetchHealth, options) {
+  const deadline = options.now() + options.timeoutMs;
+  while (options.now() < deadline) {
+    const health = await fetchHealth();
+    if (health)
+      return health;
+    if (options.isAlive && !options.isAlive())
+      return null;
+    await options.sleep(options.intervalMs);
+  }
+  return fetchHealth();
+}
+function pathWithHostTools(env, homedir) {
+  const extras = [
+    "/opt/homebrew/bin",
+    "/opt/homebrew/sbin",
+    "/usr/local/bin",
+    join(homedir, ".local", "bin"),
+    join(homedir, ".bun", "bin")
+  ];
+  const existing = (env.PATH ?? "").split(":").filter(Boolean);
+  const prepend = extras.filter((dir) => !existing.includes(dir));
+  return [...prepend, ...existing].join(":");
+}
+async function defaultPathExists(path) {
+  return existsSync(path);
+}
+async function defaultWhich(bin) {
+  const { execFile } = await import("node:child_process");
+  return new Promise((resolve) => {
+    execFile("which", [bin], (error, stdout) => {
+      if (error) {
+        resolve(null);
+        return;
+      }
+      const path = stdout.trim().split(`
+`)[0]?.trim();
+      resolve(path || null);
+    });
+  });
+}
+async function defaultFindBun(pathExists, which, homedir, env) {
+  const fromEnv = env.BUN_INSTALL ? join(env.BUN_INSTALL, "bin", "bun") : null;
+  const candidates = [
+    fromEnv,
+    join(homedir, ".bun", "bin", "bun"),
+    "/opt/homebrew/bin/bun",
+    "/usr/local/bin/bun"
+  ].filter((path) => Boolean(path));
+  for (const candidate of candidates) {
+    if (await pathExists(candidate))
+      return candidate;
+  }
+  return which("bun");
+}
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function spawnEnv(env, homedir) {
+  return {
+    ...env,
+    PATH: pathWithHostTools(env, homedir),
+    YOQA_RUNNER_HOST: env.YOQA_RUNNER_HOST ?? DEFAULT_RUNNER_HOST,
+    YOQA_RUNNER_PORT: env.YOQA_RUNNER_PORT ?? String(DEFAULT_RUNNER_PORT)
+  };
+}
+function defaultSpawnDetached(launch, env, homedir) {
+  const [bin, ...args] = launch.command;
+  if (!bin)
+    throw new RunnerStartError("Runner launch command is empty");
+  const child = spawn(bin, args, {
+    cwd: launch.cwd,
+    detached: true,
+    stdio: "ignore",
+    env: spawnEnv(env, homedir)
+  });
+  if (child.pid == null) {
+    throw new RunnerStartError("Failed to spawn the Yoqa runner");
+  }
+  child.unref();
+  return { pid: child.pid };
+}
+function defaultSpawnForeground(launch, env, homedir) {
+  const [bin, ...args] = launch.command;
+  if (!bin)
+    throw new RunnerStartError("Runner launch command is empty");
+  const child = spawn(bin, args, {
+    cwd: launch.cwd,
+    stdio: "inherit",
+    env: spawnEnv(env, homedir)
+  });
+  if (child.pid == null) {
+    throw new RunnerStartError("Failed to spawn the Yoqa runner");
+  }
+  const forward = (signal) => {
+    try {
+      child.kill(signal);
+    } catch {}
+  };
+  process.on("SIGINT", forward);
+  process.on("SIGTERM", forward);
+  const exited = new Promise((resolve, reject) => {
+    child.on("error", (error) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      if ("code" in error && error.code === "ENOENT") {
+        reject(new RunnerStartError(BUN_MISSING_MESSAGE));
+        return;
+      }
+      reject(error);
+    });
+    child.on("exit", (code, signal) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      if (signal) {
+        resolve(1);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+  return { pid: child.pid, exited };
+}
+async function defaultWritePid(homedir, pid) {
+  const dir = yoqaRoot(homedir);
+  await mkdir(dir, { recursive: true });
+  await writeFile(runnerPidPath(homedir), `${pid}
+`, "utf8");
+}
+async function defaultReadPid(homedir) {
+  try {
+    const raw = (await readFile(runnerPidPath(homedir), "utf8")).trim();
+    const pid = Number(raw);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+async function defaultRemovePid(homedir) {
+  try {
+    await unlink(runnerPidPath(homedir));
+  } catch {}
+}
+function createDefaultEnsureDeps(overrides = {}) {
+  const env = overrides.env ?? process.env;
+  const homedir = overrides.homedir ?? osHomedir();
+  const pathExists = overrides.pathExists ?? defaultPathExists;
+  const which = overrides.which ?? defaultWhich;
+  const fromUrl = overrides.fromUrl ?? import.meta.url;
+  return {
+    env,
+    cwd: overrides.cwd ?? process.cwd(),
+    execPath: overrides.execPath ?? process.execPath,
+    argv0: overrides.argv0 ?? process.argv0,
+    homedir,
+    fromUrl,
+    pathExists,
+    which,
+    findBun: overrides.findBun ?? (() => defaultFindBun(pathExists, which, homedir, env)),
+    resolvePackageEntry: overrides.resolvePackageEntry ?? (() => resolvePublishedRunnerEntry(fromUrl)),
+    fetchHealth: overrides.fetchHealth ?? ((baseUrl) => fetchRunnerHealth(baseUrl)),
+    spawnDetached: overrides.spawnDetached ?? ((launch, spawnProcessEnv) => defaultSpawnDetached(launch, spawnProcessEnv, homedir)),
+    spawnForeground: overrides.spawnForeground ?? ((launch, spawnProcessEnv) => defaultSpawnForeground(launch, spawnProcessEnv, homedir)),
+    writePid: overrides.writePid ?? ((pid) => defaultWritePid(homedir, pid)),
+    readPid: overrides.readPid ?? (() => defaultReadPid(homedir)),
+    removePid: overrides.removePid ?? (() => defaultRemovePid(homedir)),
+    isPidAlive: overrides.isPidAlive ?? defaultIsPidAlive,
+    killPid: overrides.killPid ?? ((pid, signal = "SIGTERM") => {
+      process.kill(pid, signal);
+    }),
+    sleep: overrides.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    now: overrides.now ?? (() => Date.now()),
+    log: overrides.log ?? ((message) => console.error(message))
+  };
+}
+async function ensureRunner(options) {
+  const mode = options?.mode ?? "detached";
+  const deps = createDefaultEnsureDeps(options?.deps);
+  const baseUrl = options?.baseUrl ?? runnerBaseUrlFromEnv(deps.env);
+  const existing = await deps.fetchHealth(baseUrl);
+  if (existing) {
+    return { baseUrl, started: false };
+  }
+  const launch = await resolveRunnerLaunch(deps);
+  deps.log(`yoqa: starting runner (${launch.source}) → ${baseUrl}`);
+  if (mode === "foreground") {
+    const child = deps.spawnForeground(launch, deps.env);
+    await deps.writePid(child.pid);
+    const code = await child.exited;
+    await deps.removePid();
+    if (code !== 0) {
+      throw new RunnerStartError(`Runner exited with code ${code}`);
+    }
+    return { baseUrl, started: true, source: launch.source, pid: child.pid };
+  }
+  const spawned = deps.spawnDetached(launch, deps.env);
+  await deps.writePid(spawned.pid);
+  const health = await waitForRunnerHealth(() => deps.fetchHealth(baseUrl), {
+    timeoutMs: HEALTH_TIMEOUT_MS,
+    intervalMs: HEALTH_POLL_MS,
+    sleep: deps.sleep,
+    now: deps.now,
+    isAlive: () => deps.isPidAlive(spawned.pid)
+  });
+  if (!health) {
+    try {
+      deps.killPid(spawned.pid);
+    } catch {}
+    await deps.removePid();
+    throw new RunnerStartError(`Local runner failed to start at ${baseUrl}. Try: yoqa serve`);
+  }
+  return { baseUrl, started: true, source: launch.source, pid: spawned.pid };
+}
+async function stopOwnedRunner(depsPartial = {}) {
+  const deps = createDefaultEnsureDeps(depsPartial);
+  const pid = await deps.readPid();
+  if (pid == null) {
+    return { ok: true, message: "No yoqa-owned runner pid file" };
+  }
+  if (!deps.isPidAlive(pid)) {
+    await deps.removePid();
+    return { ok: true, message: `Stale pid ${pid} removed` };
+  }
+  try {
+    deps.killPid(pid, "SIGTERM");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, message: `Failed to stop pid ${pid}: ${message}` };
+  }
+  await deps.removePid();
+  return { ok: true, message: `Stopped runner pid ${pid}` };
+}
+function commandChainIncludes(command, name) {
+  let current = command;
+  while (current && typeof current.name === "function") {
+    if (current.name() === name)
+      return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+// src/main.ts
+function runnerBaseUrl() {
+  return runnerBaseUrlFromEnv();
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -7910,9 +8309,43 @@ function client(baseUrl) {
 function fail(command, error) {
   const message = error instanceof Error ? error.message : String(error);
   console.error(`yoqa ${command} failed: ${message}`);
-  console.error("Is the runner up? Try: bun run runner");
+  if (!message.includes("yoqa serve") && !message.includes("Bun")) {
+    console.error("Is the runner up? Try: yoqa serve");
+  }
   process.exitCode = 1;
 }
+program2.command("serve").description("Start the local Yoqa runner in the foreground (no desktop app required)").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--stop", "Stop a runner previously started by yoqa (pid file)").action(async (options) => {
+  try {
+    if (options.stop) {
+      const result = await stopOwnedRunner();
+      console.log(result.message);
+      if (!result.ok)
+        process.exitCode = 1;
+      return;
+    }
+    const baseUrl = options.baseUrl;
+    const health = await fetchRunnerHealth(baseUrl);
+    if (health) {
+      console.log(`already running at ${baseUrl} (${health.version})`);
+      return;
+    }
+    await ensureRunner({ mode: "foreground", baseUrl });
+  } catch (error) {
+    fail("serve", error);
+  }
+});
+program2.hook("preAction", async (_thisCommand, actionCommand) => {
+  if (commandChainIncludes(actionCommand, "serve"))
+    return;
+  if (shouldSkipAutostart())
+    return;
+  try {
+    await ensureRunner({ mode: "detached" });
+  } catch (error) {
+    fail("autostart", error);
+    throw error;
+  }
+});
 async function resolveAppId(c, prefixOrId) {
   const apps = await c.listApps();
   const match = apps.find((a) => a.prefix === prefixOrId) ?? apps.find((a) => a.id === prefixOrId);
@@ -8735,7 +9168,7 @@ runsCmd.command("report").description("Export a detailed HTML or Markdown report
     const contents = format === "html" ? formatRunReportHtml(doc) : formatRunReportMarkdown(doc);
     const extension = format === "html" ? "html" : "md";
     const outputPath = options.output?.trim() || `${suggestedRunReportBasename(doc)}.${extension}`;
-    await writeFile(outputPath, contents, "utf8");
+    await writeFile2(outputPath, contents, "utf8");
     console.log(`wrote ${outputPath} (${doc.status}, ${steps.length} steps)`);
   } catch (error) {
     fail("runs report", error);
@@ -8802,7 +9235,7 @@ runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("
 var scriptCmd = program2.command("script").description("Replay exported CaseScript files");
 scriptCmd.command("run").argument("<file>", "Path to a .yoqa.json / CaseScript JSON file").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON per step").action(async (file, options) => {
   try {
-    const raw = await readFile(file, "utf8");
+    const raw = await readFile2(file, "utf8");
     const parsed = caseScriptSchema.safeParse(JSON.parse(raw));
     if (!parsed.success) {
       throw new Error(`Invalid CaseScript: ${parsed.error.message}`);

package/package.json

@@ -1,13 +1,15 @@
 {
 	"name": "@yoqa/cli",
-	"version": "0.3.10",
+	"version": "0.3.12",
 	"description": "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
 	"license": "UNLICENSED",
 	"type": "module",
 	"bin": {
 		"yoqa": "dist/main.js"
 	},
-	"files": ["dist"],
+	"files": [
+		"dist"
+	],
 	"engines": {
 		"node": ">=20"
 	},
@@ -20,7 +22,14 @@
 	"bugs": {
 		"url": "https://github.com/Aris-ngoy/qa-agent/issues"
 	},
-	"keywords": ["yoqa", "cli", "mobile", "qa", "appium", "testing"],
+	"keywords": [
+		"yoqa",
+		"cli",
+		"mobile",
+		"qa",
+		"appium",
+		"testing"
+	],
 	"scripts": {
 		"yoqa": "bun run src/main.ts",
 		"build": "bun run build.ts",
@@ -28,6 +37,9 @@
 		"check": "tsc --noEmit",
 		"health": "bun run src/main.ts health"
 	},
+	"dependencies": {
+		"@yoqa/runner": "0.3.12"
+	},
 	"devDependencies": {
 		"@types/node": "^22.15.30",
 		"@yoqa/runner-client": "workspace:*",