@yoqa/cli 0.3.27 → 0.3.28

package/README.md

@@ -1,6 +1,6 @@
 # @yoqa/cli
 
-CLI for [Yoqa](https://yoqa.mintlify.app/docs/overview) — drive a local runner over HTTP from your terminal or CI.
+CLI for [Yoqa](https://yoqa.arisn.dev/docs/overview) — drive a local runner over HTTP from your terminal or CI.
 
 ```bash
 npm install -g @yoqa/cli
@@ -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) and [GitHub Actions](https://yoqa.mintlify.app/docs/github-actions).
+See [CLI docs](https://yoqa.arisn.dev/docs/cli) and [GitHub Actions](https://yoqa.arisn.dev/docs/github-actions).

package/dist/main.js

@@ -6263,6 +6263,7 @@ var catalogAppSchema = exports_external.object({
   name: exports_external.string().min(1),
   prefix: exports_external.string().min(1),
   context: exports_external.string(),
+  knowledge: exports_external.string(),
   iosBundleId: exports_external.string(),
   iosAppStoreId: exports_external.string(),
   androidApplicationId: exports_external.string(),
@@ -6278,6 +6279,7 @@ var updateAppRequestSchema = exports_external.object({
   name: exports_external.string().min(1).optional(),
   prefix: exports_external.string().min(1).optional(),
   context: exports_external.string().optional(),
+  knowledge: exports_external.string().optional(),
   iosBundleId: exports_external.string().optional(),
   iosAppStoreId: exports_external.string().optional(),
   androidApplicationId: exports_external.string().optional(),
@@ -6591,7 +6593,8 @@ var probeProviderResponseSchema = exports_external.object({
 var providerModelSchema = exports_external.object({
   id: exports_external.string().min(1),
   name: exports_external.string().min(1),
-  provider: exports_external.string().min(1).optional()
+  provider: exports_external.string().min(1).optional(),
+  vision: exports_external.boolean().optional()
 });
 var listProviderModelsResponseSchema = exports_external.object({
   models: exports_external.array(providerModelSchema),
@@ -6620,6 +6623,7 @@ var runExecutionModeSchema = exports_external.union([
   exports_external.literal("script"),
   exports_external.literal("agent")
 ]);
+var runScreenModeSchema = exports_external.union([exports_external.literal("vision"), exports_external.literal("tree")]);
 var createRunRequestSchema = exports_external.object({
   appId: exports_external.string().min(1),
   caseIds: exports_external.array(exports_external.string().min(1)).min(1),
@@ -6627,7 +6631,17 @@ var createRunRequestSchema = exports_external.object({
   platform: devicePlatformSchema,
   buildId: exports_external.string().min(1).optional(),
   buildPath: exports_external.string().min(1).optional(),
-  executionMode: runExecutionModeSchema.optional()
+  executionMode: runExecutionModeSchema.optional(),
+  screenMode: runScreenModeSchema.optional()
+});
+var stepPhasesSchema = exports_external.object({
+  captureMs: exports_external.number().nonnegative(),
+  screenMs: exports_external.number().nonnegative(),
+  prepareMs: exports_external.number().nonnegative(),
+  decideMs: exports_external.number().nonnegative(),
+  actionMs: exports_external.number().nonnegative(),
+  settleMs: exports_external.number().nonnegative(),
+  decideRetries: exports_external.number().int().nonnegative()
 });
 var runStepSchema = exports_external.object({
   id: exports_external.string().min(1),
@@ -6637,6 +6651,7 @@ var runStepSchema = exports_external.object({
   screenshotUri: exports_external.string().nullable(),
   ok: exports_external.boolean(),
   latencyMs: exports_external.number().nonnegative(),
+  phases: stepPhasesSchema.nullable().optional(),
   detail: exports_external.string().nullable(),
   command: exports_external.string().nullable().optional(),
   createdAt: exports_external.number().int().nonnegative()
@@ -6661,6 +6676,7 @@ var runSchema = exports_external.object({
   buildId: exports_external.string().nullable(),
   status: runStatusSchema,
   executionMode: runExecutionModeSchema,
+  screenMode: runScreenModeSchema.optional(),
   error: exports_external.string().nullable(),
   createdAt: exports_external.number().int().nonnegative(),
   startedAt: exports_external.number().int().nonnegative().nullable(),
@@ -6746,7 +6762,16 @@ var actionRequestSchema = exports_external.object({
   appId: exports_external.string().optional(),
   url: exports_external.string().optional(),
   alertAction: exports_external.union([exports_external.literal("accept"), exports_external.literal("dismiss")]).optional(),
-  seconds: exports_external.number().optional()
+  seconds: exports_external.number().optional(),
+  screenshot: exports_external.boolean().optional(),
+  settleMs: exports_external.number().int().min(0).max(1e4).optional()
+});
+var actionResultScreenshotSchema = exports_external.object({
+  path: exports_external.string().min(1),
+  annotatedPath: exports_external.string().min(1).optional(),
+  settled: exports_external.boolean(),
+  waitedMs: exports_external.number(),
+  changed: exports_external.boolean().nullable()
 });
 var actionResponseSchema = exports_external.object({
   ok: exports_external.literal(true),
@@ -6754,7 +6779,8 @@ var actionResponseSchema = exports_external.object({
   resolved: exports_external.object({
     x: exports_external.number().optional(),
     y: exports_external.number().optional()
-  }).optional()
+  }).optional(),
+  screenshot: actionResultScreenshotSchema.optional()
 });
 var yoqaStatusResponseSchema = exports_external.object({
   runner: exports_external.object({
@@ -7309,10 +7335,28 @@ async function runYoqaShellScript(client, text, options = {}) {
 }
 
 // ../runner-client/src/run-report.ts
-function actionSummary(action) {
-  if (!action || typeof action !== "object")
-    return "Step";
-  const record = action;
+function readStepCycle(action) {
+  if (!action || typeof action !== "object" || !("cycle" in action))
+    return null;
+  const cycle = action.cycle;
+  if (!cycle || typeof cycle !== "object")
+    return null;
+  const record = cycle;
+  const asRecord = (value) => value && typeof value === "object" ? value : null;
+  const verify = asRecord(record.verify);
+  if (!verify || typeof verify.type !== "string" || !verify.type)
+    return null;
+  return {
+    action: asRecord(record.action),
+    decision: asRecord(record.decision),
+    verify: {
+      type: verify.type,
+      reason: typeof verify.reason === "string" ? verify.reason : null,
+      thoughts: typeof verify.thoughts === "string" ? verify.thoughts : null
+    }
+  };
+}
+function summarizeActionRecord(record) {
   const type = typeof record.type === "string" ? record.type : "step";
   if (type === "tap") {
     if (typeof record.label === "string" && record.label.trim())
@@ -7382,6 +7426,16 @@ function actionSummary(action) {
   }
   return type.charAt(0).toUpperCase() + type.slice(1);
 }
+function actionSummary(action) {
+  if (!action || typeof action !== "object")
+    return "Step";
+  const cycle = readStepCycle(action);
+  if (cycle?.action)
+    return summarizeActionRecord(cycle.action);
+  if (cycle?.decision)
+    return summarizeActionRecord(cycle.decision);
+  return summarizeActionRecord(action);
+}
 function optionalTrimmedString(value) {
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
@@ -7489,6 +7543,20 @@ function toReportStatus(status) {
     return status;
   return null;
 }
+function formatStepPhases(phases) {
+  const parts = [
+    `capture ${Math.round(phases.captureMs)}ms`,
+    `screen ${Math.round(phases.screenMs)}ms`,
+    `image ${Math.round(phases.prepareMs)}ms`,
+    `decide ${Math.round(phases.decideMs)}ms`,
+    `action ${Math.round(phases.actionMs)}ms`,
+    `settle ${Math.round(phases.settleMs)}ms`
+  ];
+  if (phases.decideRetries > 0) {
+    parts.push(`retries ${phases.decideRetries}`);
+  }
+  return parts.join(" · ");
+}
 function mapCatalogStep(step, screenshotsByStepId) {
   const { reason, thoughts } = stepReasoning(step);
   return {
@@ -7497,6 +7565,7 @@ function mapCatalogStep(step, screenshotsByStepId) {
     summary: actionSummary(step.action),
     ok: step.ok,
     latencyMs: step.latencyMs,
+    phases: step.phases ?? null,
     detail: step.detail,
     reason,
     thoughts,
@@ -7530,6 +7599,7 @@ function buildRunReportFromCatalogRun(run, meta = {}, screenshotsByStepId = {})
     deviceLabel: meta.deviceLabel ?? null,
     platform: run.platform,
     executionMode: run.executionMode,
+    screenMode: run.screenMode ?? null,
     error: run.error,
     createdAt: run.createdAt,
     startedAt: run.startedAt,
@@ -7577,6 +7647,7 @@ function pngDataUri(base64) {
 }
 function formatRunReportHtml(doc) {
   const accent = statusAccent(doc.status);
+  const screenRows = doc.screenMode ? [["Screen", doc.screenMode]] : [];
   const metaRows = [
     ["Status", accent.label],
     ["Source", doc.source === "catalog" ? "Catalog run" : "Manual Inspector"],
@@ -7584,6 +7655,7 @@ function formatRunReportHtml(doc) {
     ["Device", doc.deviceLabel ?? "—"],
     ["Platform", doc.platform ?? "—"],
     ["Mode", doc.executionMode ?? "—"],
+    ...screenRows,
     ["Started", formatWhen(doc.startedAt ?? doc.createdAt)],
     ["Finished", formatWhen(doc.finishedAt)],
     ["Duration", formatDuration(doc.startedAt ?? doc.createdAt, doc.finishedAt)],
@@ -7599,6 +7671,7 @@ function formatRunReportHtml(doc) {
       const detailBlock = step.detail && step.detail !== step.reason ? `<p class="detail">${escapeHtml(step.detail)}</p>` : "";
       const shot = step.screenshotBase64 ? `<img class="shot" alt="Step ${step.index} screenshot" src="${pngDataUri(step.screenshotBase64)}" />` : `<p class="muted">No screenshot</p>`;
       const latency = step.latencyMs != null ? `<span class="muted">${step.latencyMs}ms</span>` : "";
+      const phases = step.phases ? `<p class="muted phases">Phases: ${escapeHtml(formatStepPhases(step.phases))}</p>` : "";
       const commandBlock = step.command ? `<pre class="command"><code>${escapeHtml(step.command)}</code></pre>` : "";
       return `
 <article class="step ${step.ok ? "ok" : "fail"}">
@@ -7610,6 +7683,7 @@ function formatRunReportHtml(doc) {
     </div>
   </header>
   ${commandBlock}
+  ${phases}
   ${reasonBlock}
   ${detailBlock}
   ${thoughtsBlock}
@@ -7707,6 +7781,7 @@ function formatRunReportMarkdown(doc) {
     `| Device | ${escapeMd(doc.deviceLabel ?? "—")} |`,
     `| Platform | ${escapeMd(doc.platform ?? "—")} |`,
     `| Mode | ${escapeMd(doc.executionMode ?? "—")} |`,
+    ...doc.screenMode ? [`| Screen | ${escapeMd(doc.screenMode)} |`] : [],
     `| Started | ${escapeMd(formatWhen(doc.startedAt ?? doc.createdAt))} |`,
     `| Finished | ${escapeMd(formatWhen(doc.finishedAt))} |`,
     `| Duration | ${escapeMd(formatDuration(doc.startedAt ?? doc.createdAt, doc.finishedAt))} |`,
@@ -7735,6 +7810,8 @@ function formatRunReportMarkdown(doc) {
         lines.push(`- Command: \`${step.command.replace(/`/g, "'")}\``);
       if (step.latencyMs != null)
         lines.push(`- Latency: ${step.latencyMs}ms`);
+      if (step.phases)
+        lines.push(`- Phases: ${formatStepPhases(step.phases)}`);
       if (step.reason)
         lines.push(`- Reason: ${step.reason}`);
       if (step.detail && step.detail !== step.reason)
@@ -7771,6 +7848,7 @@ function formatRunReportGithubSummary(doc) {
     `| Device | ${escapeMd(doc.deviceLabel ?? "—")} |`,
     `| Platform | ${escapeMd(doc.platform ?? "—")} |`,
     `| Mode | ${escapeMd(doc.executionMode ?? "—")} |`,
+    ...doc.screenMode ? [`| Screen | ${escapeMd(doc.screenMode)} |`] : [],
     `| Duration | ${escapeMd(formatDuration(doc.startedAt ?? doc.createdAt, doc.finishedAt))} |`,
     `| Run ID | \`${doc.id}\` |`,
     ""
@@ -8277,7 +8355,7 @@ var {
 // package.json
 var package_default = {
   name: "@yoqa/cli",
-  version: "0.3.27",
+  version: "0.3.28",
   description: "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
   license: "UNLICENSED",
   type: "module",
@@ -8295,7 +8373,7 @@ var package_default = {
     url: "git+https://github.com/Aris-ngoy/qa-agent.git",
     directory: "packages/cli"
   },
-  homepage: "https://yoqa.mintlify.app/docs/cli",
+  homepage: "https://yoqa.arisn.dev/docs/cli",
   bugs: {
     url: "https://github.com/Aris-ngoy/qa-agent/issues"
   },
@@ -8315,7 +8393,7 @@ var package_default = {
     health: "bun run src/main.ts health"
   },
   dependencies: {
-    "@yoqa/runner": "0.3.27"
+    "@yoqa/runner": "0.3.28"
   },
   devDependencies: {
     "@types/node": "^22.15.30",
@@ -9244,7 +9322,14 @@ program2.command("screenshot").description("Capture a screenshot from the active
 });
 var action = program2.command("action").description("Perform an action on the active device");
 function addActionOptions(cmd) {
-  return cmd.option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("-d, --description <text>", "Ground target by natural language").option("--label <text>", "Tap/focus by accessibility label (cleaned screen tree)").option("--id <text>", "Tap/focus by resource-id / accessibility id").option("--x <n>", "X in 0–1000", (v) => Number(v)).option("--y <n>", "Y in 0–1000", (v) => Number(v)).option("--x2 <n>", "End X in 0–1000", (v) => Number(v)).option("--y2 <n>", "End Y in 0–1000", (v) => Number(v)).option("--duration <ms>", "Gesture duration ms (long-press for tap)", (v) => Number(v)).option("--double", "Double-tap (tap only)").option("--text <text>", "Text to type").option("--app-id <id>", "Bundle id / application id").option("--url <url>", "URL to open").option("--seconds <n>", "Background seconds", (v) => Number(v));
+  return cmd.option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("-d, --description <text>", "Ground target by natural language").option("--label <text>", "Tap/focus by accessibility label (cleaned screen tree)").option("--id <text>", "Tap/focus by resource-id / accessibility id").option("--x <n>", "X in 0–1000", (v) => Number(v)).option("--y <n>", "Y in 0–1000", (v) => Number(v)).option("--x2 <n>", "End X in 0–1000", (v) => Number(v)).option("--y2 <n>", "End Y in 0–1000", (v) => Number(v)).option("--duration <ms>", "Gesture duration ms (long-press for tap)", (v) => Number(v)).option("--double", "Double-tap (tap only)").option("--text <text>", "Text to type").option("--app-id <id>", "Bundle id / application id").option("--url <url>", "URL to open").option("--seconds <n>", "Background seconds", (v) => Number(v)).option("--screenshot", "Wait for the screen to settle, then return the result screenshot (and a copy marking where the tap or swipe landed)").option("--settle <ms>", "With --screenshot: longest wait for the screen to settle (default 1500)", (v) => Number(v));
+}
+function printResultScreenshot(shot) {
+  console.log(`screenshot ${shot.path}`);
+  if (shot.annotatedPath)
+    console.log(`marked ${shot.annotatedPath}`);
+  console.log(`settled ${shot.settled} (${Math.round(shot.waitedMs)}ms)`);
+  console.log(`changed ${shot.changed === null ? "unknown (screen still animating)" : shot.changed}`);
 }
 for (const kind of [
   "tap",
@@ -9273,7 +9358,9 @@ for (const kind of [
         description: options.description,
         appId: options.appId,
         url: options.url,
-        seconds: options.seconds
+        seconds: options.seconds,
+        screenshot: options.screenshot === true ? true : undefined,
+        settleMs: options.settle
       });
       if (options.json) {
         console.log(JSON.stringify(body, null, 2));
@@ -9283,6 +9370,8 @@ for (const kind of [
       if (body.resolved?.x != null && body.resolved?.y != null) {
         console.log(`resolved ${body.resolved.x},${body.resolved.y}`);
       }
+      if (body.screenshot)
+        printResultScreenshot(body.screenshot);
     } catch (error) {
       fail(`action ${kind}`, error);
     }
@@ -9292,13 +9381,17 @@ addActionOptions(action.command("alert").description("Accept or dismiss a system
   try {
     const body = await client(String(options.baseUrl)).performAction({
       kind: "alert",
-      alertAction: options.dismiss ? "dismiss" : "accept"
+      alertAction: options.dismiss ? "dismiss" : "accept",
+      screenshot: options.screenshot === true ? true : undefined,
+      settleMs: options.settle
     });
     if (options.json) {
       console.log(JSON.stringify(body, null, 2));
       return;
     }
     console.log(`ok ${body.kind}`);
+    if (body.screenshot)
+      printResultScreenshot(body.screenshot);
   } catch (error) {
     fail("action alert", error);
   }
@@ -9588,13 +9681,14 @@ appsCmd.command("get").argument("<app>", "App prefix or id").option("--base-url
     console.log(`prefix: ${app.prefix}`);
     console.log(`name: ${app.name}`);
     console.log(`app_context: ${app.context || "(empty)"}`);
+    console.log(`app_knowledge: ${app.knowledge || "(empty)"}`);
     console.log(`ios_bundle_id: ${app.iosBundleId || "(empty)"}`);
     console.log(`android_application_id: ${app.androidApplicationId || "(empty)"}`);
   } catch (error) {
     fail("apps get", error);
   }
 });
-appsCmd.command("update").argument("<app>", "App prefix or id").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--name <name>", "Display name").option("--prefix <prefix>", "CLI prefix").option("--context <text>", "App context / shared rules").option("--ios-bundle-id <id>", "iOS bundle id").option("--android-application-id <id>", "Android application id").option("--json", "Print raw JSON").action(async (appArg, options) => {
+appsCmd.command("update").argument("<app>", "App prefix or id").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--name <name>", "Display name").option("--prefix <prefix>", "CLI prefix").option("--context <text>", "App context / shared rules").option("--knowledge <text>", "App knowledge notes injected into agent runs").option("--ios-bundle-id <id>", "iOS bundle id").option("--android-application-id <id>", "Android application id").option("--json", "Print raw JSON").action(async (appArg, options) => {
   try {
     const c = client(options.baseUrl);
     const resolved = await resolveAppId(c, appArg);
@@ -9602,6 +9696,7 @@ appsCmd.command("update").argument("<app>", "App prefix or id").option("--base-u
       name: options.name,
       prefix: options.prefix,
       context: options.context,
+      knowledge: options.knowledge,
       iosBundleId: options.iosBundleId,
       androidApplicationId: options.androidApplicationId
     });
@@ -9927,7 +10022,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").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) => {
+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("--screen-mode <mode>", "vision | tree — what the agent sees: screenshot only, or also the accessibility tree (default: vision)").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);
@@ -9959,6 +10054,10 @@ 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 screenMode = options.screenMode === "vision" || options.screenMode === "tree" ? options.screenMode : undefined;
+    if (options.screenMode && !screenMode) {
+      throw new Error("--screen-mode must be vision or tree");
+    }
     let run = await c.createRun({
       appId: resolved.id,
       caseIds,
@@ -9966,7 +10065,8 @@ runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("
       platform,
       buildId: options.buildId,
       buildPath: options.buildPath,
-      executionMode
+      executionMode,
+      screenMode
     });
     if (options.wait) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yoqa/cli",
-	"version": "0.3.27",
+	"version": "0.3.28",
 	"description": "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
 	"license": "UNLICENSED",
 	"type": "module",
@@ -18,7 +18,7 @@
 		"url": "git+https://github.com/Aris-ngoy/qa-agent.git",
 		"directory": "packages/cli"
 	},
-	"homepage": "https://yoqa.mintlify.app/docs/cli",
+	"homepage": "https://yoqa.arisn.dev/docs/cli",
 	"bugs": {
 		"url": "https://github.com/Aris-ngoy/qa-agent/issues"
 	},
@@ -38,7 +38,7 @@
 		"health": "bun run src/main.ts health"
 	},
 	"dependencies": {
-		"@yoqa/runner": "0.3.27"
+		"@yoqa/runner": "0.3.28"
 	},
 	"devDependencies": {
 		"@types/node": "^22.15.30",