@yoqa/cli 0.3.16 → 0.3.17

package/README.md

@@ -18,4 +18,4 @@ 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).
+See [CLI docs](https://yoqa.mintlify.app/docs/cli) and [GitHub Actions](https://yoqa.mintlify.app/docs/github-actions).

package/dist/main.js

@@ -2122,7 +2122,7 @@ var require_commander = __commonJS((exports) => {
 });
 
 // src/main.ts
-import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { readFile as readFile2 } from "node:fs/promises";
 
 // ../../node_modules/zod/v3/external.js
 var exports_external = {};
@@ -6293,13 +6293,24 @@ var caseFlowStepSchema = exports_external.object({
   flowId: exports_external.string().min(1).nullable().optional()
 });
 var caseRunStatusSchema = exports_external.union([exports_external.literal("passed"), exports_external.literal("errored")]);
-var caseScriptActionSchema = exports_external.discriminatedUnion("type", [
-  exports_external.object({
-    type: exports_external.literal("tap"),
-    x: exports_external.number().min(0).max(1000),
-    y: exports_external.number().min(0).max(1000),
-    reason: exports_external.string().optional()
-  }),
+var caseScriptTapSchema = exports_external.object({
+  type: exports_external.literal("tap"),
+  x: exports_external.number().min(0).max(1000).optional(),
+  y: exports_external.number().min(0).max(1000).optional(),
+  label: exports_external.string().min(1).optional(),
+  id: exports_external.string().min(1).optional(),
+  reason: exports_external.string().optional()
+}).superRefine((value, ctx) => {
+  const hasCoords = value.x != null && value.y != null;
+  if (!hasCoords && !value.label && !value.id) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "tap requires x/y or label or id"
+    });
+  }
+});
+var caseScriptActionSchema = exports_external.union([
+  caseScriptTapSchema,
   exports_external.object({
     type: exports_external.literal("type"),
     text: exports_external.string(),
@@ -6309,6 +6320,13 @@ var caseScriptActionSchema = exports_external.discriminatedUnion("type", [
     type: exports_external.literal("wait"),
     ms: exports_external.number().min(0).max(1e4),
     reason: exports_external.string().optional()
+  }),
+  exports_external.object({
+    type: exports_external.literal("assert"),
+    assertion: exports_external.union([exports_external.literal("visible"), exports_external.literal("not-visible")]).default("visible"),
+    text: exports_external.string().min(1),
+    timeoutMs: exports_external.number().min(0).max(120000).optional(),
+    reason: exports_external.string().optional()
   })
 ]);
 var caseScriptSchema = exports_external.object({
@@ -6716,18 +6734,103 @@ var createBuildRequestSchema = exports_external.object({
 var listBuildsResponseSchema = exports_external.object({
   builds: exports_external.array(buildSchema)
 });
+
+// ../runner-client/src/wait-for-run.ts
+var DEFAULT_WAIT_FOR_RUN_TIMEOUT_MS = 30 * 60 * 1000;
+var DEFAULT_WAIT_FOR_RUN_INTERVAL_MS = 2000;
+function isTerminalRunStatus(status) {
+  return status === "passed" || status === "errored" || status === "cancelled";
+}
+
+class WaitForRunTimeoutError extends Error {
+  runId;
+  lastRun;
+  timeoutMs;
+  constructor(runId, timeoutMs, lastRun) {
+    const lastStatus = lastRun?.status ?? "unknown";
+    super(`Timed out after ${timeoutMs}ms waiting for run ${runId} (last status: ${lastStatus})`);
+    this.name = "WaitForRunTimeoutError";
+    this.runId = runId;
+    this.lastRun = lastRun;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class WaitForRunAbortedError extends Error {
+  runId;
+  lastRun;
+  constructor(runId, lastRun) {
+    super(`Wait for run ${runId} was aborted`);
+    this.name = "WaitForRunAbortedError";
+    this.runId = runId;
+    this.lastRun = lastRun;
+  }
+}
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForRun(client, runId, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_FOR_RUN_TIMEOUT_MS;
+  const intervalMs = options.intervalMs ?? DEFAULT_WAIT_FOR_RUN_INTERVAL_MS;
+  if (!(timeoutMs > 0)) {
+    throw new Error("timeoutMs must be positive");
+  }
+  if (intervalMs < 0) {
+    throw new Error("intervalMs must be non-negative");
+  }
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  const deadline = now() + timeoutMs;
+  let lastRun = null;
+  while (now() < deadline) {
+    if (options.signal?.aborted) {
+      throw new WaitForRunAbortedError(runId, lastRun);
+    }
+    lastRun = await client.getRun(runId);
+    options.onStatus?.(lastRun);
+    if (isTerminalRunStatus(lastRun.status)) {
+      return lastRun;
+    }
+    const remaining = deadline - now();
+    if (remaining <= 0)
+      break;
+    await sleep(Math.min(intervalMs, remaining));
+  }
+  if (options.signal?.aborted) {
+    throw new WaitForRunAbortedError(runId, lastRun);
+  }
+  if (lastRun && isTerminalRunStatus(lastRun.status)) {
+    return lastRun;
+  }
+  throw new WaitForRunTimeoutError(runId, timeoutMs, lastRun);
+}
+function pickLatestRun(runs) {
+  if (runs.length === 0)
+    return null;
+  return runs.reduce((best, run) => run.createdAt > best.createdAt ? run : best);
+}
 // ../runner-client/src/run-report.ts
 function actionSummary(action) {
   if (!action || typeof action !== "object")
     return "Step";
   const record = action;
   const type = typeof record.type === "string" ? record.type : "step";
-  if (type === "tap")
+  if (type === "tap") {
+    if (typeof record.label === "string" && record.label.trim())
+      return `Tap: ${record.label}`;
+    if (typeof record.id === "string" && record.id.trim())
+      return `Tap #${record.id}`;
     return "Tap";
+  }
   if (type === "type")
     return `Type${typeof record.text === "string" ? `: ${record.text}` : ""}`;
   if (type === "wait")
     return "Wait";
+  if (type === "assert") {
+    const assertion = typeof record.assertion === "string" ? record.assertion : "visible";
+    const text = typeof record.text === "string" ? record.text : "";
+    return text ? `Assert ${assertion}: ${text}` : `Assert ${assertion}`;
+  }
   if (type === "verify")
     return "Verify";
   if (type === "done")
@@ -7012,6 +7115,54 @@ function formatRunReportMarkdown(doc) {
   return lines.join(`
 `);
 }
+function formatRunReportGithubSummary(doc) {
+  const accent = statusAccent(doc.status);
+  const passed = doc.tests.filter((test) => test.status === "passed").length;
+  const failed = doc.tests.filter((test) => test.status === "errored").length;
+  const cancelled = doc.tests.filter((test) => test.status === "cancelled").length;
+  const failedSteps = doc.tests.flatMap((test) => test.steps.filter((step) => !step.ok).map((step) => ({ test, step })));
+  const lines = [
+    `## Yoqa Report — ${doc.title}`,
+    "",
+    `**${accent.label}** · ${doc.tests.length} test${doc.tests.length === 1 ? "" : "s"} · ${passed} passed · ${failed} failed · ${cancelled} cancelled`,
+    "",
+    "| Field | Value |",
+    "| --- | --- |",
+    `| App | ${escapeMd(doc.appLabel ?? "—")} |`,
+    `| Device | ${escapeMd(doc.deviceLabel ?? "—")} |`,
+    `| Platform | ${escapeMd(doc.platform ?? "—")} |`,
+    `| Mode | ${escapeMd(doc.executionMode ?? "—")} |`,
+    `| Duration | ${escapeMd(formatDuration(doc.startedAt ?? doc.createdAt, doc.finishedAt))} |`,
+    `| Run ID | \`${doc.id}\` |`,
+    ""
+  ];
+  if (doc.error) {
+    lines.push(`> **Error:** ${doc.error}`, "");
+  }
+  if (doc.tests.length > 0) {
+    lines.push("### Tests", "", "| # | Test | Status | Steps |", "| --- | --- | --- | --- |");
+    doc.tests.forEach((test, testIndex) => {
+      const testLabel = test.status === "passed" ? "Passed" : test.status === "errored" ? "Failed" : test.status === "cancelled" ? "Cancelled" : test.status;
+      lines.push(`| ${testIndex + 1} | ${escapeMd(test.title)} | ${testLabel} | ${test.steps.length} |`);
+    });
+    lines.push("");
+  }
+  if (failedSteps.length > 0) {
+    lines.push("### Failed steps", "");
+    for (const { test, step } of failedSteps) {
+      lines.push(`- **${escapeMd(test.title)}** · step ${step.index}: ${escapeMd(step.summary)}`);
+      if (step.reason)
+        lines.push(`  - Reason: ${escapeMd(step.reason)}`);
+      if (step.detail && step.detail !== step.reason) {
+        lines.push(`  - Detail: ${escapeMd(step.detail)}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push("Download the `yoqa-report` artifact for the full HTML report with screenshots.", "");
+  return lines.join(`
+`);
+}
 // ../runner-client/src/shell-script.ts
 function shellSingleQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -7719,6 +7870,9 @@ class RunnerClient {
     const json = await this.requestJson(`/runs/${encodeURIComponent(runId)}`, undefined, "Get run failed");
     return runSchema.parse(json);
   }
+  async waitForRun(runId, options) {
+    return waitForRun(this, runId, options);
+  }
   async deleteRun(runId) {
     await this.requestJson(`/runs/${encodeURIComponent(runId)}`, { method: "DELETE" }, "Delete run failed");
   }
@@ -7850,7 +8004,7 @@ var {
 // package.json
 var package_default = {
   name: "@yoqa/cli",
-  version: "0.3.16",
+  version: "0.3.17",
   description: "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
   license: "UNLICENSED",
   type: "module",
@@ -7888,7 +8042,7 @@ var package_default = {
     health: "bun run src/main.ts health"
   },
   dependencies: {
-    "@yoqa/runner": "0.3.16"
+    "@yoqa/runner": "0.3.17"
   },
   devDependencies: {
     "@types/node": "^22.15.30",
@@ -7902,6 +8056,15 @@ var package_default = {
   }
 };
 
+// src/catalog-app.ts
+function findCatalogApp(apps, prefixOrId) {
+  const needle = prefixOrId.trim();
+  if (!needle)
+    return;
+  const lower = needle.toLowerCase();
+  return apps.find((app) => app.prefix === needle) ?? apps.find((app) => app.prefix.toLowerCase() === lower) ?? apps.find((app) => app.id === needle);
+}
+
 // src/doctor-table.ts
 var ANSI = {
   reset: "\x1B[0m",
@@ -8369,6 +8532,206 @@ function commandChainIncludes(command, name) {
   return false;
 }
 
+// src/report.ts
+import { mkdir as mkdir3, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname3 } from "node:path";
+
+// src/github.ts
+import { appendFile, mkdir as mkdir2 } from "node:fs/promises";
+import { dirname as dirname2 } from "node:path";
+function isGithubActions(env = process.env) {
+  return env.GITHUB_ACTIONS === "true";
+}
+function resolveGithubWritePath(flag, filePath, env = process.env) {
+  if (flag === false)
+    return null;
+  const path = filePath?.trim();
+  if (!path)
+    return null;
+  if (flag === true || isGithubActions(env))
+    return path;
+  return null;
+}
+function formatGithubOutputLines(fields) {
+  const lines = [];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value.includes(`
+`) || value.includes("\r")) {
+      throw new Error(`GitHub output ${key} cannot contain newlines`);
+    }
+    lines.push(`${key}=${value}`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+async function appendGithubFile(path, contents) {
+  await mkdir2(dirname2(path), { recursive: true });
+  const body = contents.endsWith(`
+`) ? contents : `${contents}
+`;
+  await appendFile(path, body, "utf8");
+}
+
+// src/report.ts
+var DEFAULT_RUN_WAIT_TIMEOUT_SECONDS = 1800;
+function normalizeReportFormat(raw) {
+  const format = raw === "md" || raw === "markdown" ? "md" : raw ?? "html";
+  if (format !== "html" && format !== "md") {
+    throw new Error("--format must be html or md");
+  }
+  return format;
+}
+function parseFailOn(raw) {
+  const value = (raw ?? "never").trim().toLowerCase();
+  if (value === "errored" || value === "never")
+    return value;
+  throw new Error("--fail-on must be errored or never");
+}
+function parseTimeoutSeconds(raw, fallback = DEFAULT_RUN_WAIT_TIMEOUT_SECONDS) {
+  const n = raw == null || raw.trim() === "" ? fallback : Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error("--timeout must be a positive number of seconds");
+  }
+  return n;
+}
+function shouldFailOnRunStatus(failOn, status) {
+  return failOn === "errored" && status === "errored";
+}
+async function resolveReportRunId(client, runIdArg, latestAppId, latestLabel) {
+  const runId = runIdArg?.trim();
+  if (runId && latestAppId) {
+    throw new Error("Pass either <runId> or --latest <app>, not both");
+  }
+  if (runId)
+    return runId;
+  if (!latestAppId) {
+    throw new Error("Provide a run id or --latest <app>");
+  }
+  const latest = pickLatestRun(await client.listRuns(latestAppId));
+  if (!latest) {
+    throw new Error(`No runs found for app ${latestLabel}`);
+  }
+  return latest.id;
+}
+async function loadFinishedRun(client, runId, options, deps) {
+  const run = await client.getRun(runId);
+  if (isTerminalRunStatus(run.status))
+    return run;
+  if (!options.wait) {
+    throw new Error(`Run is still ${run.status}. Wait until it finishes (passed / errored / cancelled) or pass --wait.`);
+  }
+  const timeoutSeconds = parseTimeoutSeconds(options.timeout);
+  try {
+    return await waitForRun(client, runId, {
+      timeoutMs: timeoutSeconds * 1000,
+      onStatus: deps.onWaitStatus,
+      sleep: deps.sleep,
+      now: deps.now
+    });
+  } catch (error) {
+    if (error instanceof WaitForRunTimeoutError && error.lastRun) {
+      await writeRunGithubOutput(error.lastRun, undefined, deps, options);
+    }
+    throw error;
+  }
+}
+async function writeRunGithubOutput(run, reportPath, deps, options) {
+  const env = deps.env ?? process.env;
+  const outputPath = resolveGithubWritePath(options.githubOutput, env.GITHUB_OUTPUT, env);
+  if (!outputPath)
+    return;
+  const fields = {
+    run_id: run.id,
+    status: run.status
+  };
+  if (reportPath)
+    fields.report_path = reportPath;
+  const append = deps.appendGithubFile ?? appendGithubFile;
+  await append(outputPath, formatGithubOutputLines(fields));
+}
+async function exportCatalogRunReport(client, runId, options, deps = {}) {
+  const format = normalizeReportFormat(options.format);
+  const failOn = parseFailOn(options.failOn);
+  const env = deps.env ?? process.env;
+  const log = deps.log ?? console.log;
+  const write = deps.writeFile ?? writeFile2;
+  const makeDir = deps.mkdir ?? mkdir3;
+  const append = deps.appendGithubFile ?? appendGithubFile;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const run = await loadFinishedRun(client, runId, options, deps);
+  const screenshotsByStepId = {};
+  const steps = run.tests.flatMap((test) => test.steps ?? []);
+  await Promise.all(steps.map(async (step) => {
+    if (!step.screenshotUri)
+      return;
+    const response = await fetchImpl(client.getRunStepScreenshotUrl(run.id, step.id));
+    if (!response.ok)
+      return;
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    screenshotsByStepId[step.id] = Buffer.from(bytes).toString("base64");
+  }));
+  const apps = await client.listApps();
+  const app = apps.find((row) => row.id === run.appId);
+  const cases = await client.listCases(run.appId);
+  const caseTitles = {};
+  for (const item of cases) {
+    caseTitles[item.id] = `#${item.number} ${item.name}`;
+  }
+  let deviceLabel = run.deviceId;
+  try {
+    const devices = await client.listDevices(run.platform, { includeUnavailable: true });
+    const device = devices.devices.find((row) => row.id === run.deviceId);
+    if (device) {
+      deviceLabel = `${device.name} · ${run.platform} ${device.osVersion}`;
+    }
+  } catch {}
+  const doc = buildRunReportFromCatalogRun(run, {
+    appLabel: app ? `${app.prefix} — ${app.name}` : run.appId,
+    deviceLabel,
+    caseTitles
+  }, screenshotsByStepId);
+  const contents = format === "html" ? formatRunReportHtml(doc) : formatRunReportMarkdown(doc);
+  const extension = format === "html" ? "html" : "md";
+  const outputPath = options.output?.trim() || `${suggestedRunReportBasename(doc)}.${extension}`;
+  await makeDir(dirname3(outputPath), { recursive: true });
+  await write(outputPath, contents, "utf8");
+  log(`wrote ${outputPath} (${doc.status}, ${steps.length} steps)`);
+  const summaryPath = resolveGithubWritePath(options.githubSummary, env.GITHUB_STEP_SUMMARY, env);
+  if (summaryPath) {
+    await append(summaryPath, formatRunReportGithubSummary(doc));
+  }
+  await writeRunGithubOutput(run, outputPath, { ...deps, env, appendGithubFile: append }, options);
+  return {
+    outputPath,
+    status: doc.status,
+    runId: run.id,
+    stepCount: steps.length,
+    shouldFail: shouldFailOnRunStatus(failOn, doc.status)
+  };
+}
+function attachReportCommandOptions(cmd) {
+  return cmd.argument("[runId]", "Run id").option("--latest <app>", "Export the newest run for this app prefix or id").option("--format <format>", "html | md (default: html)", "html").option("-o, --output <path>", "Output file path (default: yoqa-run-<id>-<status>.html|md)").option("--wait", "Wait until the run finishes before exporting").option("--timeout <seconds>", "Wait timeout in seconds (default: 1800)", String(DEFAULT_RUN_WAIT_TIMEOUT_SECONDS)).option("--github-summary", "Append compact markdown to $GITHUB_STEP_SUMMARY").option("--no-github-summary", "Do not write a GitHub job summary").option("--github-output", "Write run_id, status, report_path to $GITHUB_OUTPUT").option("--no-github-output", "Do not write GitHub step outputs").option("--fail-on <when>", "errored | never (default: never)", "never");
+}
+function createWaitStatusLogger(write = console.error) {
+  let last = "";
+  return (run) => {
+    if (run.status === last)
+      return;
+    last = run.status;
+    write(`run ${run.id} ${run.status}`);
+  };
+}
+async function maybeWriteGithubRunOutput(run, flag, env = process.env, append = appendGithubFile) {
+  const outputPath = resolveGithubWritePath(flag, env.GITHUB_OUTPUT, env);
+  if (!outputPath)
+    return;
+  await append(outputPath, formatGithubOutputLines({ run_id: run.id, status: run.status }));
+}
+function attachGithubOutputOptions(cmd) {
+  return cmd.option("--github-output", "Write run_id and status to $GITHUB_OUTPUT").option("--no-github-output", "Do not write GitHub step outputs");
+}
+
 // src/main.ts
 function runnerBaseUrl() {
   return runnerBaseUrlFromEnv();
@@ -8423,12 +8786,37 @@ program2.hook("preAction", async (_thisCommand, actionCommand) => {
 });
 async function resolveAppId(c, prefixOrId) {
   const apps = await c.listApps();
-  const match = apps.find((a) => a.prefix === prefixOrId) ?? apps.find((a) => a.id === prefixOrId);
+  const match = findCatalogApp(apps, prefixOrId);
   if (!match) {
     throw new Error(`App not found: ${prefixOrId}. Run: yoqa apps list`);
   }
   return { id: match.id, prefix: match.prefix, name: match.name };
 }
+async function loadCaseScriptFile(file) {
+  const raw = await readFile2(file, "utf8");
+  const parsed = caseScriptSchema.safeParse(JSON.parse(raw));
+  if (!parsed.success) {
+    throw new Error(`Invalid CaseScript: ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+async function handleReportCommand(commandLabel, runIdArg, options) {
+  try {
+    const c = client(options.baseUrl);
+    let latestAppId;
+    if (options.latest) {
+      latestAppId = (await resolveAppId(c, options.latest)).id;
+    }
+    const runId = await resolveReportRunId(c, runIdArg, latestAppId, options.latest ?? "");
+    const result = await exportCatalogRunReport(c, runId, options, {
+      onWaitStatus: createWaitStatusLogger()
+    });
+    if (result.shouldFail)
+      process.exitCode = 1;
+  } catch (error) {
+    fail(commandLabel, error);
+  }
+}
 program2.command("health").description("Check that the local runner is reachable").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).action(async (options) => {
   try {
     const health = await client(options.baseUrl).health();
@@ -8877,6 +9265,25 @@ appsCmd.command("list").option("--base-url <url>", "Runner base URL", runnerBase
     fail("apps list", error);
   }
 });
+appsCmd.command("create").description("Create a local catalog app").requiredOption("--name <name>", "Display name").option("--prefix <prefix>", "CLI prefix (allocated from name when omitted)").option("--ios-bundle-id <id>", "iOS bundle id").option("--android-application-id <id>", "Android application id").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (options) => {
+  try {
+    const c = client(options.baseUrl);
+    let app = await c.createApp({ name: options.name, prefix: options.prefix });
+    if (options.iosBundleId || options.androidApplicationId) {
+      app = await c.updateApp(app.id, {
+        iosBundleId: options.iosBundleId,
+        androidApplicationId: options.androidApplicationId
+      });
+    }
+    if (options.json) {
+      console.log(JSON.stringify(app, null, 2));
+      return;
+    }
+    console.log(`created ${app.prefix}`);
+  } catch (error) {
+    fail("apps create", error);
+  }
+});
 appsCmd.command("get").argument("<app>", "App prefix or id").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (appArg, options) => {
   try {
     const c = client(options.baseUrl);
@@ -8960,15 +9367,20 @@ casesCmd.command("get").argument("<app>", "App prefix or id").argument("<number>
     fail("cases get", error);
   }
 });
-casesCmd.command("create").argument("<app>", "App prefix or id").requiredOption("--title <title>", "Case title").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (appArg, options) => {
+casesCmd.command("create").argument("<app>", "App prefix or id").requiredOption("--title <title>", "Case title").option("--script-file <path>", "Path to a .yoqa.json CaseScript to attach").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (appArg, options) => {
   try {
     const c = client(options.baseUrl);
     const resolved = await resolveAppId(c, appArg);
-    const created = await c.createCase(resolved.id, {
+    let created = await c.createCase(resolved.id, {
       name: options.title,
       flows: [],
       tags: []
     });
+    if (options.scriptFile) {
+      created = await c.updateCase(created.id, {
+        script: await loadCaseScriptFile(options.scriptFile)
+      });
+    }
     if (options.json) {
       console.log(JSON.stringify(created, null, 2));
       return;
@@ -8978,7 +9390,7 @@ casesCmd.command("create").argument("<app>", "App prefix or id").requiredOption(
     fail("cases create", error);
   }
 });
-casesCmd.command("update").argument("<app>", "App prefix or id").argument("<number>", "Case number", (v) => Number(v)).option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--title <title>", "New title").option("--json", "Print raw JSON").action(async (appArg, number, options) => {
+casesCmd.command("update").argument("<app>", "App prefix or id").argument("<number>", "Case number", (v) => Number(v)).option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--title <title>", "New title").option("--script-file <path>", "Path to a .yoqa.json CaseScript to attach").option("--json", "Print raw JSON").action(async (appArg, number, options) => {
   try {
     const c = client(options.baseUrl);
     const resolved = await resolveAppId(c, appArg);
@@ -8986,7 +9398,10 @@ casesCmd.command("update").argument("<app>", "App prefix or id").argument("<numb
     const found = cases.find((item) => item.number === number);
     if (!found)
       throw new Error(`Case #${number} not found`);
-    const updated = await c.updateCase(found.id, { name: options.title });
+    const updated = await c.updateCase(found.id, {
+      name: options.title,
+      script: options.scriptFile ? await loadCaseScriptFile(options.scriptFile) : undefined
+    });
     if (options.json) {
       console.log(JSON.stringify(updated, null, 2));
       return;
@@ -9151,6 +9566,9 @@ buildsCmd.command("delete").argument("<buildId>", "Build id").option("--base-url
     fail("builds delete", error);
   }
 });
+attachReportCommandOptions(program2.command("report").description("Export a detailed HTML or Markdown report with step screenshots")).option("--base-url <url>", "Runner base URL", runnerBaseUrl()).action(async (runId, options) => {
+  await handleReportCommand("report", runId, options);
+});
 var runsCmd = program2.command("runs").description("Create and inspect local agent runs");
 runsCmd.command("list").argument("<app>", "App prefix or id").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (appArg, options) => {
   try {
@@ -9183,55 +9601,28 @@ runsCmd.command("get").argument("<runId>", "Run id").option("--base-url <url>",
     fail("runs get", error);
   }
 });
-runsCmd.command("report").description("Export a detailed HTML or Markdown report with step screenshots").argument("<runId>", "Run id").option("--format <format>", "html | md (default: html)", "html").option("-o, --output <path>", "Output file path (default: yoqa-run-<id>-<status>.html|md)").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).action(async (runId, options) => {
+attachReportCommandOptions(runsCmd.command("report").description("Export a detailed HTML or Markdown report with step screenshots")).option("--base-url <url>", "Runner base URL", runnerBaseUrl()).action(async (runId, options) => {
+  await handleReportCommand("runs report", runId, options);
+});
+attachGithubOutputOptions(runsCmd.command("wait").description("Wait until a catalog run finishes").argument("<runId>", "Run id").option("--timeout <seconds>", "Wait timeout in seconds (default: 1800)", String(DEFAULT_RUN_WAIT_TIMEOUT_SECONDS))).option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (runId, options) => {
   try {
-    const format = options.format === "md" || options.format === "markdown" ? "md" : options.format;
-    if (format !== "html" && format !== "md") {
-      throw new Error("--format must be html or md");
-    }
-    const c = client(options.baseUrl);
-    const run = await c.getRun(runId);
-    if (run.status === "queued" || run.status === "running") {
-      throw new Error(`Run is still ${run.status}. Wait until it finishes (passed / errored / cancelled).`);
-    }
-    const screenshotsByStepId = {};
-    const steps = run.tests.flatMap((test) => test.steps ?? []);
-    await Promise.all(steps.map(async (step) => {
-      if (!step.screenshotUri)
-        return;
-      const response = await fetch(c.getRunStepScreenshotUrl(run.id, step.id));
-      if (!response.ok)
-        return;
-      const bytes = new Uint8Array(await response.arrayBuffer());
-      screenshotsByStepId[step.id] = Buffer.from(bytes).toString("base64");
-    }));
-    const apps = await c.listApps();
-    const app = apps.find((row) => row.id === run.appId);
-    const cases = await c.listCases(run.appId);
-    const caseTitles = {};
-    for (const item of cases) {
-      caseTitles[item.id] = `#${item.number} ${item.name}`;
+    const finished = await waitForRun(client(options.baseUrl), runId, {
+      timeoutMs: parseTimeoutSeconds(options.timeout) * 1000,
+      onStatus: createWaitStatusLogger()
+    });
+    await maybeWriteGithubRunOutput(finished, options.githubOutput);
+    if (options.json) {
+      console.log(JSON.stringify(finished, null, 2));
+    } else {
+      console.log(`${finished.id} ${finished.status}`);
     }
-    let deviceLabel = run.deviceId;
-    try {
-      const devices2 = await c.listDevices(run.platform, { includeUnavailable: true });
-      const device = devices2.devices.find((row) => row.id === run.deviceId);
-      if (device) {
-        deviceLabel = `${device.name} · ${run.platform} ${device.osVersion}`;
-      }
-    } catch {}
-    const doc = buildRunReportFromCatalogRun(run, {
-      appLabel: app ? `${app.prefix} — ${app.name}` : run.appId,
-      deviceLabel,
-      caseTitles
-    }, screenshotsByStepId);
-    const contents = format === "html" ? formatRunReportHtml(doc) : formatRunReportMarkdown(doc);
-    const extension = format === "html" ? "html" : "md";
-    const outputPath = options.output?.trim() || `${suggestedRunReportBasename(doc)}.${extension}`;
-    await writeFile2(outputPath, contents, "utf8");
-    console.log(`wrote ${outputPath} (${doc.status}, ${steps.length} steps)`);
+    if (shouldFailOnRunStatus("errored", finished.status))
+      process.exitCode = 1;
   } catch (error) {
-    fail("runs report", error);
+    if (error instanceof WaitForRunTimeoutError && error.lastRun) {
+      await maybeWriteGithubRunOutput(error.lastRun, options.githubOutput);
+    }
+    fail("runs wait", error);
   }
 });
 runsCmd.command("delete").argument("<runId>", "Run id").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).action(async (runId, options) => {
@@ -9242,7 +9633,7 @@ runsCmd.command("delete").argument("<runId>", "Run id").option("--base-url <url>
     fail("runs delete", error);
   }
 });
-runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("--cases <numbers>", "Comma-separated case numbers, e.g. 1,2,5").option("--device <id>", "Device id (defaults to active session)").option("--platform <platform>", "ios | android (defaults to active session)").option("--build-id <id>", "Registered build id to install before run").option("--build-path <path>", "Absolute build path to register + install").option("--mode <mode>", "auto | script | agent (default: auto)").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").action(async (appArg, options) => {
+runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("--cases <numbers>", "Comma-separated case numbers, e.g. 1,2,5").option("--device <id>", "Device id (defaults to active session)").option("--platform <platform>", "ios | android (defaults to active session)").option("--build-id <id>", "Registered build id to install before run").option("--build-path <path>", "Absolute build path to register + install").option("--mode <mode>", "auto | script | agent (default: auto)").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("--wait", "Wait until the run finishes (passed / errored / cancelled)").option("--timeout <seconds>", "Wait timeout in seconds (default: 1800)", String(DEFAULT_RUN_WAIT_TIMEOUT_SECONDS)).option("--github-output", "Write run_id and status to $GITHUB_OUTPUT").option("--no-github-output", "Do not write GitHub step outputs").action(async (appArg, options) => {
   try {
     const c = client(options.baseUrl);
     const resolved = await resolveAppId(c, appArg);
@@ -9274,7 +9665,7 @@ runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("
     if (options.mode && !executionMode) {
       throw new Error("--mode must be auto, script, or agent");
     }
-    const run = await c.createRun({
+    let run = await c.createRun({
       appId: resolved.id,
       caseIds,
       deviceId,
@@ -9283,11 +9674,28 @@ runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("
       buildPath: options.buildPath,
       executionMode
     });
+    if (options.wait) {
+      try {
+        run = await waitForRun(c, run.id, {
+          timeoutMs: parseTimeoutSeconds(options.timeout) * 1000,
+          onStatus: createWaitStatusLogger()
+        });
+      } catch (error) {
+        if (error instanceof WaitForRunTimeoutError && error.lastRun) {
+          await maybeWriteGithubRunOutput(error.lastRun, options.githubOutput);
+        }
+        throw error;
+      }
+    }
+    await maybeWriteGithubRunOutput(run, options.githubOutput);
     if (options.json) {
       console.log(JSON.stringify(run, null, 2));
-      return;
+    } else {
+      console.log(`created ${run.id} (${run.status})`);
+    }
+    if (options.wait && shouldFailOnRunStatus("errored", run.status)) {
+      process.exitCode = 1;
     }
-    console.log(`created ${run.id} (${run.status})`);
   } catch (error) {
     fail("runs create", error);
   }
@@ -9295,17 +9703,12 @@ 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 readFile2(file, "utf8");
-    const parsed = caseScriptSchema.safeParse(JSON.parse(raw));
-    if (!parsed.success) {
-      throw new Error(`Invalid CaseScript: ${parsed.error.message}`);
-    }
+    const script = await loadCaseScriptFile(file);
     const c = client(options.baseUrl);
     const active = await c.getActiveDevice();
     if (!active) {
       throw new Error("No active device session. Connect first: yoqa devices connect <id>");
     }
-    const script = parsed.data;
     let idx = 0;
     for (const action2 of script.actions) {
       idx += 1;
@@ -9319,7 +9722,46 @@ scriptCmd.command("run").argument("<file>", "Path to a .yoqa.json / CaseScript J
         await sleep(ms);
         continue;
       }
-      const body = action2.type === "tap" ? await c.performAction({ kind: "tap", x: action2.x, y: action2.y }) : await c.performAction({ kind: "input", text: action2.text });
+      if (action2.type === "assert") {
+        const timeoutMs = action2.timeoutMs ?? 5000;
+        const deadline = Date.now() + timeoutMs;
+        for (;; ) {
+          const screen = await c.getScreen();
+          const found = screenHasText(screen.elements, action2.text);
+          if (action2.assertion === "visible" && found)
+            break;
+          if (action2.assertion === "not-visible" && !found)
+            break;
+          if (Date.now() >= deadline) {
+            throw new Error(action2.assertion === "visible" ? `Expected visible text not found within ${Math.round(timeoutMs / 1000)}s: ${action2.text}` : `Unexpected text still visible after ${Math.round(timeoutMs / 1000)}s: ${action2.text}`);
+          }
+          await sleep(400);
+        }
+        if (options.json) {
+          console.log(JSON.stringify({
+            ok: true,
+            kind: "assert",
+            assertion: action2.assertion,
+            text: action2.text,
+            step: idx
+          }, null, 2));
+        } else {
+          console.log(`ok assert ${action2.assertion} (${idx}/${script.actions.length})`);
+        }
+        continue;
+      }
+      const tapBody = { kind: "tap" };
+      if (action2.type === "tap") {
+        if (action2.label)
+          tapBody.label = action2.label;
+        if (action2.id)
+          tapBody.id = action2.id;
+        if (action2.x != null)
+          tapBody.x = action2.x;
+        if (action2.y != null)
+          tapBody.y = action2.y;
+      }
+      const body = action2.type === "tap" ? await c.performAction(tapBody) : await c.performAction({ kind: "input", text: action2.text });
       if (options.json) {
         console.log(JSON.stringify({ ...body, step: idx }, null, 2));
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yoqa/cli",
-	"version": "0.3.16",
+	"version": "0.3.17",
 	"description": "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
 	"license": "UNLICENSED",
 	"type": "module",
@@ -38,7 +38,7 @@
 		"health": "bun run src/main.ts health"
 	},
 	"dependencies": {
-		"@yoqa/runner": "0.3.16"
+		"@yoqa/runner": "0.3.17"
 	},
 	"devDependencies": {
 		"@types/node": "^22.15.30",