@ishlabs/cli 0.26.0 → 0.26.1

package/dist/commands/doctor.d.ts

@@ -23,4 +23,20 @@
  *    build.
  */
 import type { Command } from "commander";
+export type CheckStatus = "pass" | "warn" | "fail" | "skip";
+export interface Check {
+    /** Stable machine key (for --json). */
+    key: string;
+    /** Human label. */
+    name: string;
+    /** Coarse grouping for the human checklist. */
+    group: "iOS" | "Android" | "Web" | "Account";
+    status: CheckStatus;
+    message?: string;
+    /** One-line remediation hint shown on warn/fail. */
+    fix?: string;
+}
+export declare function runChecks(): Promise<Check[]>;
+export declare function scopeChecks(checks: Check[], platform?: string): Check[];
+export declare function overall(checks: Check[]): CheckStatus;
 export declare function registerDoctorCommands(program: Command): void;

package/dist/commands/doctor.js

@@ -28,9 +28,10 @@ import { existsSync, readdirSync } from "node:fs";
 import * as path from "node:path";
 import { runInline } from "../lib/command-helpers.js";
 import { output } from "../lib/output.js";
+import { reportReadiness } from "../lib/report-readiness.js";
 import { loadConfig } from "../config.js";
 import { decodeJwtClaims, isTokenExpired } from "../auth.js";
-import { wdaDir } from "../lib/paths.js";
+import { wdaDir, adbBin } from "../lib/paths.js";
 import pkg from "../../package.json" with { type: "json" };
 const execFileAsync = promisify(execFile);
 const XCRUN = "/usr/bin/xcrun";
@@ -52,7 +53,7 @@ async function tryExec(cmd, args, timeoutMs = 8000) {
         };
     }
 }
-/** adb path, mirroring the device layer's resolution (ISH_ADB → ANDROID_HOME → PATH). */
+/** adb path, mirroring the device layer's resolution (ISH_ADB → SDK → Homebrew → our download cache → PATH). */
 function resolveAdb() {
     for (const v of [process.env.ISH_ADB, process.env.ADB]) {
         if (v && existsSync(v))
@@ -65,6 +66,10 @@ function resolveAdb() {
                 return p;
         }
     }
+    if (existsSync("/opt/homebrew/bin/adb"))
+        return "/opt/homebrew/bin/adb";
+    if (existsSync(adbBin()))
+        return adbBin();
     return "adb";
 }
 // ── Individual checks ──────────────────────────────────────────────────────
@@ -156,7 +161,7 @@ async function checkAdb() {
     const adbPath = resolveAdb();
     const r = await tryExec(adbPath, ["devices"]);
     if (!r.ok) {
-        const adb = { key: "adb", name: "Android adb", group: "Android", status: "warn", message: "not found (only needed for Android)", fix: "Install Android platform-tools" };
+        const adb = { key: "adb", name: "Android adb", group: "Android", status: "warn", message: "not found (only needed for Android)", fix: "ish setup (fetches adb), or install Android platform-tools" };
         const emulator = { key: "android_emulator", name: "Android emulator", group: "Android", status: "skip" };
         return { adb, emulator };
     }
@@ -188,7 +193,7 @@ async function checkChromium() {
 function checkCli() {
     return { key: "cli", name: "ish CLI", group: "Account", status: "pass", message: `v${pkg.version}` };
 }
-async function runChecks() {
+export async function runChecks() {
     const { adb, emulator } = await checkAdb();
     return [
         await checkXcode(),
@@ -218,13 +223,13 @@ const PLATFORM_GROUPS = {
     android: ["Android", "Account"],
     web: ["Web", "Account"],
 };
-function scopeChecks(checks, platform) {
+export function scopeChecks(checks, platform) {
     if (!platform)
         return checks;
     const groups = PLATFORM_GROUPS[platform];
     return groups ? checks.filter((c) => groups.includes(c.group)) : checks;
 }
-function overall(checks) {
+export function overall(checks) {
     if (checks.some((c) => c.status === "fail"))
         return "fail";
     if (checks.some((c) => c.status === "warn"))
@@ -274,17 +279,28 @@ export function registerDoctorCommands(program) {
                 throw new Error(`Unknown platform "${platform}". Use one of: ios, android, web.`);
             }
             const checks = scopeChecks(await runChecks(), scope);
+            const aggregate = overall(checks);
             if (globals.json) {
-                output({ checks, overall: overall(checks) }, true);
+                output({ checks, overall: aggregate }, true);
             }
             else {
                 renderHuman(checks);
             }
+            // Best-effort: when scoped to a native platform, report readiness to
+            // the backend so the web app can render a live native-readiness panel
+            // (the native analog of `ish connect` registering a tunnel). Never for
+            // the no-arg `ish check` (no single platform) or `web`. Awaited so a
+            // short-lived `ish check` doesn't drop the in-flight request before
+            // exit — `reportReadiness` is fully best-effort and never throws or
+            // blocks meaningfully (5s ceiling).
+            if (scope === "ios" || scope === "android") {
+                await reportReadiness(scope, checks, aggregate, globals);
+            }
         });
     });
     program
         .command("setup")
-        .description("Fetch/install local-simulation dependencies (Chromium, iOS runner) and show what's left to do")
+        .description("Fetch/install local-simulation dependencies (Chromium, iOS runner, adb) and show what's left to do")
         .action(async (_opts, cmd) => {
         await runInline(cmd, async (globals) => {
             const quiet = globals.json;
@@ -320,7 +336,16 @@ export function registerDoctorCommands(program) {
                     log(`iOS runner: could not fetch (${e instanceof Error ? e.message : String(e)}).`);
                 }
             }
-            // 3. Re-run checks so the user sees the resulting state, and hand back
+            // 3. Android adb — auto-fetchable (Google's standalone platform-tools).
+            try {
+                const { ensureAdb } = await import("../lib/local-sim/adb.js");
+                await ensureAdb();
+                log("Android adb: ready.");
+            }
+            catch (e) {
+                log(`Android adb: could not fetch (${e instanceof Error ? e.message : String(e)}).`);
+            }
+            // 4. Re-run checks so the user sees the resulting state, and hand back
             //    the structured result on --json.
             const checks = await runChecks();
             if (globals.json) {

package/dist/commands/iteration.js

@@ -23,6 +23,15 @@ function readTextOrAtFile(value) {
     }
     return value;
 }
+/**
+ * Native (ios/android) interactive platforms. For these the real target app is
+ * supplied at run time via `ish study run --app <bundle>`, so the iteration's
+ * `url` is just a placeholder — we don't force the user to invent one.
+ * Mirrors `isNativePlatform` in `lib/local-sim/loop.ts`.
+ */
+function isNativePlatform(platform) {
+    return platform === "ios" || platform === "android";
+}
 /**
  * Parse a JSON-blob flag that also supports `@filepath` (read from disk).
  * Used for participant_pair `--role-criteria-a/-b` and any future blob inputs.
@@ -282,7 +291,7 @@ function buildIterationDetails(modality, opts) {
             };
         }
         default:
-            if (!opts.url) {
+            if (!opts.url && !isNativePlatform(opts.platform)) {
                 throw new Error("Interactive iterations require --url. Provide the URL to test.");
             }
             if (opts.platform === "figma" && (!opts.fileKey || !opts.startNodeId)) {
@@ -296,10 +305,18 @@ function buildIterationDetails(modality, opts) {
                 }
                 screenFormat = normalized;
             }
+            // Native (ios/android) names its target via app_artifact (a bundle id /
+            // package name, or a local .app/.apk path) and carries no url. We accept
+            // the target from --app (preferred) or a --url passed out of habit. When
+            // neither is given, app_artifact is omitted = "chosen at run time".
+            const isNative = isNativePlatform(opts.platform);
+            const nativeTarget = isNative ? (opts.app ?? opts.url)?.trim() : undefined;
             return {
                 type: "interactive",
                 platform: opts.platform || "browser",
-                url: opts.url,
+                ...(isNative
+                    ? (nativeTarget ? { app_artifact: nativeTarget } : {})
+                    : { url: opts.url }),
                 screen_format: screenFormat,
                 ...(opts.locale && { locale: opts.locale }),
                 ...(opts.fileKey && { file_key: opts.fileKey }),
@@ -365,8 +382,9 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--name <name>", "Iteration name (defaults to the next position letter A/B/C… if omitted)")
         .option("--description <description>", "Iteration description")
         // Interactive
-        .option("--platform <platform>", "Platform (browser, android, figma, code) — interactive only")
-        .option("--url <url>", "URL to test — interactive only")
+        .option("--platform <platform>", "Platform (browser, android, ios, figma, code) — interactive only")
+        .option("--url <url>", "URL to test — interactive only (optional for ios/android native apps)")
+        .option("--app <id>", "Native app bundle id (or .app/.apk path) — ios/android; supplies the iteration target so --url isn't required")
         .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only; hyphen/underscore variants accepted")
         .option("--locale <locale>", "Locale code (e.g. en-US) — interactive only")
         .option("--file-key <key>", "Figma file key — required when --platform=figma")
@@ -596,7 +614,7 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                         break;
                     }
                     default:
-                        if (!opts.url) {
+                        if (!opts.url && !isNativePlatform(opts.platform)) {
                             throw new Error("Interactive iterations require --url. Provide the URL to test.");
                         }
                 }

package/dist/commands/study-participant.js

@@ -109,7 +109,7 @@ Tips:
         .option("--study <id>", "Study ID; resolves to the latest iteration on that study (alternative to --iteration)")
         .requiredOption("--person <id>", "Participant profile ID")
         .option("--language <lang>", "Language code (e.g. en, sv)")
-        .option("--platform <platform>", "Platform (browser, android, figma, code)")
+        .option("--platform <platform>", "Platform (browser, android, ios, figma, code)")
         .option("--participant-type <type>", "Participant type (ai, human)", "ai")
         .addHelpText("after", "\nExamples:\n  $ ish study participant create --iteration <id> --person <id>\n  $ ish study participant create --study s-XXX --person p-XXX\n  $ ish study participant create --iteration <id> --person <id> --platform android --json")
         .action(async (opts, cmd) => {

package/dist/commands/study-run.js

@@ -24,6 +24,8 @@ import { isMediaModality, isChatModality, iterationHasContent, describeRequiredC
 // just `study run --local`. The bun-compiled binary bundles the deep
 // path so it doesn't hit Node's resolver; only the npm path is sensitive.
 import { estimateChatPair, estimateChatSolo, estimateMediaRun } from "../lib/billing.js";
+import { reportReadiness } from "../lib/report-readiness.js";
+import { runChecks, scopeChecks, overall } from "./doctor.js";
 function parseMaxInteractions(value) {
     const n = parseInt(value, 10);
     if (isNaN(n) || n < 1)
@@ -262,6 +264,7 @@ function readIterationDetails(details) {
         ...(screenFormat && { screenFormat }),
         ...(typeof details.locale === "string" && { locale: details.locale }),
         ...(typeof details.title === "string" && { title: details.title }),
+        ...(typeof details.app_artifact === "string" && { appArtifact: details.app_artifact }),
     };
 }
 /**
@@ -760,6 +763,24 @@ Examples:
                 ?? platformFromApp
                 ?? detailsView.platform
                 ?? "browser";
+            // Best-effort native-readiness report. When this is a LOCAL native run
+            // (iOS/Android driven on this developer's machine), fire-and-forget a
+            // fresh, platform-scoped `runChecks()` to the backend so the web app
+            // can render a live native-readiness panel — the native analog of how
+            // `ish connect` registers a tunnel. Fully decoupled from the run:
+            // never awaited (must not delay dispatch), never blocks, never throws.
+            // Browser local runs and all remote runs are skipped (remote runs use
+            // Browserbase, so this machine's device readiness is irrelevant there).
+            if (opts.local && (resolvedPlatform === "ios" || resolvedPlatform === "android")) {
+                const readinessPlatform = resolvedPlatform;
+                void (async () => {
+                    const scoped = scopeChecks(await runChecks(), readinessPlatform);
+                    await reportReadiness(readinessPlatform, scoped, overall(scoped), globals, { debug: !!opts.debug });
+                })().catch(() => {
+                    // Belt-and-suspenders: reportReadiness already swallows everything,
+                    // but runChecks() / scopeChecks() must not bubble either.
+                });
+            }
             if (isPair && pairConfig) {
                 // Pair-mode flow mirrors the MCP (`ish-mcp` `_run_pair_mode`):
                 //   1. If the iteration already carries `conversations[]` from a
@@ -884,7 +905,11 @@ Examples:
                     debug: opts.debug,
                     parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
                     platform: resolvedPlatform,
-                    ...(opts.app && { appPath: opts.app }),
+                    // Native target: --app overrides; otherwise default from the
+                    // iteration's remembered app_artifact so reruns need no --app.
+                    ...((opts.app ?? detailsView.appArtifact) && {
+                        appPath: opts.app ?? detailsView.appArtifact,
+                    }),
                     quiet: globals.quiet,
                     json: globals.json,
                 });

package/dist/commands/study-screenshots.js

@@ -21,6 +21,36 @@ import { dirname, extname, join } from "node:path";
 import { withClient, resolveStudy } from "../lib/command-helpers.js";
 import { resolveId } from "../lib/alias-store.js";
 import { output, printTable } from "../lib/output.js";
+import { ApiError } from "../lib/api-client.js";
+/**
+ * Server-side screenshots are produced by remote interactive runs only. A
+ * study whose only runs were local (`ish study run --local`) has none — and the
+ * grouped endpoint currently 500s instead of returning an empty index. Tag this
+ * hint onto the error so the bare 500 points the user at the local debug report.
+ */
+const LOCAL_RUN_SCREENSHOT_HINT = [
+    "Screenshots are produced by remote runs only.",
+    "Ran this study locally (--local)? The per-step screenshots are in the HTML debug report under ~/.ish/debug/ (path printed at the end of each local run).",
+];
+/**
+ * GET the frame-grouped screenshot index, tagging the local-run hint onto any
+ * ApiError before it propagates to `outputError` (which merges `.suggestions`).
+ */
+async function getGroupedScreenshots(client, studyId) {
+    try {
+        return await client.get(`/studies/${studyId}/screenshots/grouped`);
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            const tagged = err;
+            tagged.suggestions = [
+                ...(Array.isArray(tagged.suggestions) ? tagged.suggestions : []),
+                ...LOCAL_RUN_SCREENSHOT_HINT,
+            ];
+        }
+        throw err;
+    }
+}
 function projectScreenshot(s) {
     return {
         id: s.id,
@@ -106,9 +136,12 @@ Examples:
   $ ish study screenshots download <study-id> --id <scid> --out shot.png
   $ ish study screenshots download <study-id> --all --out ./shots/
 
-Screenshots are produced server-side by interactive runs only — chat / video /
-text studies don't have them. Each row's storage URL is self-credentialed,
-so the CLI fetches bytes without forwarding your bearer.`);
+Screenshots are produced server-side by remote interactive runs only — chat /
+video / text studies don't have them, and neither do local runs
+(\`ish study run --local\`), which instead write a per-step HTML debug report to
+~/.ish/debug/ (the path is printed at the end of each local run). Each row's
+storage URL is self-credentialed, so the CLI fetches bytes without forwarding
+your bearer.`);
     screenshots
         .command("list", { isDefault: true })
         .description("List screenshots for a study (frame-grouped).")
@@ -117,7 +150,7 @@ so the CLI fetches bytes without forwarding your bearer.`);
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const studyId = resolveStudy(id);
-            const raw = await client.get(`/studies/${studyId}/screenshots/grouped`);
+            const raw = await getGroupedScreenshots(client, studyId);
             const listing = projectListing(studyId, raw);
             if (globals.json) {
                 output(listing, true, { preProjected: true });
@@ -172,7 +205,7 @@ so the CLI fetches bytes without forwarding your bearer.`);
             }
             // --all: walk the index, fetch each row, save under --out dir.
             const outDir = opts.out ?? "./screenshots";
-            const grouped = await client.get(`/studies/${studyId}/screenshots/grouped`);
+            const grouped = await getGroupedScreenshots(client, studyId);
             const all = [
                 ...(grouped.groups ?? []).flatMap((g) => g.screenshots ?? []),
                 ...(grouped.uncategorized ?? []),

package/dist/lib/api-client.d.ts

@@ -40,6 +40,7 @@ export declare class ApiClient {
         iteration_id: string;
     }): Promise<import("./local-sim/types.js").LocalSimInitResponse>;
     localSimStep(body: import("./local-sim/types.js").LocalSimStepRequest): Promise<import("./local-sim/types.js").LocalSimStepResponseRaw>;
+    localSimRecordInteraction(body: import("./local-sim/types.js").LocalSimInteractionRequest): Promise<import("./local-sim/types.js").LocalSimInteractionResponse>;
     localSimRecord(body: import("./local-sim/types.js").LocalSimRecordRequest): Promise<import("./local-sim/types.js").LocalSimRecordResponse>;
     localSimMatchFrame(body: {
         product_id: string;
@@ -50,6 +51,8 @@ export declare class ApiClient {
         screen_format?: string;
         full_page_screenshot_base64?: string;
         platform?: string;
+        previous_frame_version_id?: string;
+        same_screen_continuation?: boolean;
     }): Promise<{
         frame_version_id: string;
     }>;

package/dist/lib/api-client.js

@@ -260,8 +260,13 @@ export class ApiClient {
     async localSimStep(body) {
         return this.post("/simulation/local/step", body, { timeout: 60_000 });
     }
+    async localSimRecordInteraction(body) {
+        return this.post("/simulation/local/interaction", body, { timeout: 30_000 });
+    }
     async localSimRecord(body) {
-        return this.post("/simulation/local/record", body, { timeout: 60_000 });
+        // Finalize now runs the pre/post survey + participant summary inline
+        // server-side, so it can take materially longer than a plain DB write.
+        return this.post("/simulation/local/record", body, { timeout: 180_000 });
     }
     async localSimMatchFrame(body) {
         return this.post("/simulation/local/match-frame", body, { timeout: 30_000 });

package/dist/lib/docs.js

@@ -380,6 +380,14 @@ ish iteration create --platform figma --url https://figma.com/proto \\
     --screen-format mobile_portrait --file-key abc123 --start-node-id 0:1 \\
     --flow-name "Onboarding A"
 
+# Native app (ios / android): --app names the target, stored as app_artifact (no URL).
+ish iteration create --platform ios --app com.example.app
+ish iteration create --platform ios            # --app optional; "chosen at run time"
+# drive it locally against a booted simulator / emulator — the iteration
+# remembers the app, so no --app needed on reruns:
+ish study run --local
+ish study run --local --app ./Build.app        # override with a fresh local build
+
 # Text/email content from a file:
 ish iteration create --content-text @./email.html --title "Newsletter"
 
@@ -1992,10 +2000,14 @@ Interactive study runs produce per-frame screenshots server-side. They
 let you (or an agent) see what participants actually saw alongside the
 sentiment summary.
 
-## Screenshots — interactive studies only
+## Screenshots — remote interactive studies only
 
-Screenshots are produced by interactive runs only — chat / video / text
-studies don't have them.
+Screenshots are produced by remote interactive runs only — chat / video /
+text studies don't have them. **Local runs** (\`ish study run --local\`,
+including ios/android) don't push screenshots to the server either; they
+write a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (the path is
+printed at the end of the run). \`ish study screenshots list\` on a local-only
+study therefore returns nothing useful — open the debug report instead.
 
 ### CLI
 

package/dist/lib/local-sim/actions.d.ts

@@ -25,6 +25,24 @@ export declare function resolveTextValue(action: LocalStepAction, contextValues:
  * Compare two base64 screenshots to detect visible change.
  */
 export declare function detectNoVisibleChange(before: string, after: string): boolean;
+/**
+ * Logical classification of what a completed step's batch of actions did to the
+ * screen, used to tell the backend's frame matcher whether the NEXT observation
+ * is the same logical screen (so it reuses the previous frame instead of minting
+ * a new one off shifted pixels).
+ *
+ * - "scroll":   a pure vertical scroll (all actions succeeded) — same screen.
+ * - "keyboard": raised the keyboard without submitting/navigating — same screen.
+ * - "ui_change": anything that (likely) changed the logical screen — NOT same.
+ * - "none":     nothing actionable happened (empty batch / think-only).
+ */
+export type StepKind = "scroll" | "keyboard" | "ui_change" | "none";
+/**
+ * Classify a step's batch of actions into a StepKind. Pure — `successByIndex[i]`
+ * is the executor's `result.success` for `actions[i]`. `think` actions are
+ * ignored entirely (they neither move the screen nor count toward a verdict).
+ */
+export declare function classifyStepKind(actions: LocalStepAction[], successByIndex: boolean[]): StepKind;
 /**
  * Build a human-readable action description matching backend's format_action_detail().
  */

package/dist/lib/local-sim/actions.js

@@ -403,6 +403,36 @@ function isRecoverableError(err) {
 export function detectNoVisibleChange(before, after) {
     return before === after;
 }
+// Scroll directions that keep us on the same logical screen (vertical pan).
+// undefined/null defaults to a downward scroll in executeScroll(), so it counts.
+const VERTICAL_SCROLL_DIRECTIONS = new Set([
+    "up", "down", "to_top", "to_bottom", "to_element",
+]);
+/**
+ * Classify a step's batch of actions into a StepKind. Pure — `successByIndex[i]`
+ * is the executor's `result.success` for `actions[i]`. `think` actions are
+ * ignored entirely (they neither move the screen nor count toward a verdict).
+ */
+export function classifyStepKind(actions, successByIndex) {
+    // Keep the original index so success lines up after dropping `think`s.
+    const considered = actions
+        .map((action, i) => ({ action, success: successByIndex[i] }))
+        .filter(({ action }) => action.type !== "think");
+    if (considered.length === 0)
+        return "none";
+    // Pure vertical scroll: every action a successful vertical scroll.
+    const allScroll = considered.every(({ action, success }) => action.type === "scroll" &&
+        success === true &&
+        VERTICAL_SCROLL_DIRECTIONS.has(action.direction ?? "down"));
+    if (allScroll)
+        return "scroll";
+    // Keyboard-only: every action a text_input that raises the keyboard WITHOUT
+    // submitting/navigating. A submit makes it a ui_change (it can navigate away).
+    const allKeyboard = considered.every(({ action }) => action.type === "text_input" && !action.submit);
+    if (allKeyboard)
+        return "keyboard";
+    return "ui_change";
+}
 /**
  * Build a human-readable action description matching backend's format_action_detail().
  */

package/dist/lib/local-sim/adb.d.ts

@@ -10,6 +10,8 @@
  * backend's 0-1000 coordinates against the screencap pixel size and taps
  * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
  */
+/** Resolve adb, downloading Google's platform-tools on first use if not found. */
+export declare function ensureAdb(): Promise<string>;
 export declare class AdbError extends Error {
     constructor(message: string);
 }
@@ -17,6 +19,27 @@ export declare class AdbError extends Error {
 export declare function adb(args: string[], timeoutMs?: number): Promise<string>;
 /** Run `adb shell <args>` and return trimmed stdout. */
 export declare function adbShell(args: string[], timeoutMs?: number): Promise<string>;
+/**
+ * Pull versionName / versionCode out of `dumpsys package <pkg>` text. The
+ * relevant lines read `versionCode=42 minSdk=24 targetSdk=34` and
+ * `versionName=1.2.3`; `\d+` stops the build before the trailing tokens and
+ * `\S+` takes the version up to the next space. Returns null when neither is
+ * present (wrong/empty package).
+ */
+export declare function parseDumpsysAppBuild(out: string): {
+    version: string | null;
+    build: string | null;
+} | null;
+/**
+ * Read an installed package's versionName / versionCode from
+ * `dumpsys package <pkg>`. Best-effort: returns null on any failure (the run
+ * never depends on it). Covers both freshly-installed apks and pre-installed
+ * packages — by call time the package name is already resolved.
+ */
+export declare function appBuildFromDevice(pkg: string): Promise<{
+    version: string | null;
+    build: string | null;
+} | null>;
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary