@ishlabs/cli 0.25.0 → 0.26.1

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

@@ -0,0 +1,303 @@
+/**
+ * Host-side WebDriverAgent (XCUITest) client — the iOS UI-interaction + a11y
+ * layer that replaces idb. Device LIFECYCLE (install target app, screenshot,
+ * launch/terminate target) stays on `xcrun simctl` in `simctl.ts`; this module
+ * owns ONLY the WDA surface.
+ *
+ * Mechanism (validated on the simulator, no xcodebuild): a PREBUILT WDA runner
+ * (Appium's `WebDriverAgentRunner-Runner.app`, bundle id
+ * `com.facebook.WebDriverAgentRunner.xctrunner`) is `simctl install`-ed and
+ * `simctl launch`-ed with `SIMCTL_CHILD_USE_PORT`; the xctrunner self-hosts the
+ * XCTest runtime and serves W3C WebDriver on `localhost:<port>`. We then drive
+ * taps/swipes/text via `/session/:id/actions` and read the a11y tree via
+ * `/session/:id/source?format=json` (parsed by `parseXcuiHierarchy`).
+ *
+ * API mirrors the idb functions in `simctl.ts` (udid-keyed, points space) so
+ * `ios.ts` swaps the import with a near-identical call surface. Per-udid session
+ * state (port + WDA sessionId) is held in a module map; `ensureWda` is idempotent
+ * and reuses an already-running runner.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import * as path from "node:path";
+import { wdaDir, wdaVersionFile } from "../paths.js";
+import { IosError } from "./simctl.js";
+const execFileAsync = promisify(execFile);
+const XCRUN = "/usr/bin/xcrun";
+/** Bundle id of Appium's prebuilt WDA xctrunner (self-hosts the XCTest runtime). */
+const WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
+/** Default WDA port; override with ISH_WDA_PORT. One device → one runner. */
+const DEFAULT_PORT = Number(process.env.ISH_WDA_PORT) || 8100;
+/** WDA's XCTest runtime cold-starts slowly; poll /status up to this long. */
+const STARTUP_TIMEOUT_MS = 75_000;
+/** W3C ENTER key (maps the idb HID Return keycode 40 used by ios.ts). */
+const W3C_ENTER = "\uE007"; // idb HID Return (40) -> W3C ENTER
+const sessions = new Map();
+// ── WDA bundle resolution (fetch is wired in the distribution phase) ──────────
+/** Appium's prebuilt WebDriverAgent simulator release we fetch + pin. */
+const WDA_PINNED_TAG = "v13.2.0";
+/**
+ * Resolve the prebuilt WDA `.app`, downloading it on first use:
+ * `ISH_WDA_PATH` override → `~/.ish/bin/wda/` cache → fetch Appium's prebuilt
+ * WebDriverAgent-for-simulator from its GitHub release. Mirrors
+ * `connect.ts:resolveCloudflaredBin` (which fetches cloudflared the same way).
+ */
+export async function resolveWdaBundle() {
+    const override = process.env.ISH_WDA_PATH;
+    if (override) {
+        if (!existsSync(override)) {
+            throw new IosError(`ISH_WDA_PATH does not exist: ${override}`);
+        }
+        return override.endsWith(".app") ? override : findApp(override);
+    }
+    const dir = wdaDir();
+    if (existsSync(dir)) {
+        try {
+            return findApp(dir);
+        }
+        catch {
+            // cache dir exists but holds no .app yet → (re)download
+        }
+    }
+    return downloadWdaBundle();
+}
+/**
+ * Fetch Appium's prebuilt WDA-for-simulator zip (just the xctrunner `.app`,
+ * which self-hosts the XCTest runtime — no xcodebuild) and unpack it into
+ * `~/.ish/bin/wda/`. arch follows the host (arm64 sims on Apple Silicon, x86_64
+ * on Intel). Logs to stderr so a run shows the one-time fetch.
+ */
+async function downloadWdaBundle() {
+    const arch = process.arch === "arm64" ? "arm64" : "x86_64";
+    const asset = `WebDriverAgentRunner-Build-Sim-${arch}.zip`;
+    const url = `https://github.com/appium/WebDriverAgent/releases/download/${WDA_PINNED_TAG}/${asset}`;
+    const dir = wdaDir();
+    console.error(`Fetching the iOS automation runner (WebDriverAgent ${WDA_PINNED_TAG}, ${arch})...`);
+    mkdirSync(dir, { recursive: true });
+    const zipPath = path.join(dir, "wda.zip");
+    let resp;
+    try {
+        resp = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        throw new IosError(`failed to download WebDriverAgent from ${url}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!resp.ok) {
+        throw new IosError(`failed to download WebDriverAgent: HTTP ${resp.status} from ${url}`);
+    }
+    writeFileSync(zipPath, Buffer.from(await resp.arrayBuffer()));
+    try {
+        await execFileAsync("/usr/bin/unzip", ["-o", "-q", zipPath, "-d", dir], { timeout: 60_000 });
+    }
+    catch (e) {
+        throw new IosError(`failed to unpack WebDriverAgent: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    rmSync(zipPath, { force: true });
+    writeFileSync(wdaVersionFile(), `${WDA_PINNED_TAG} ${arch}\n`);
+    return findApp(dir);
+}
+/** First `*.app` directly under `dir` (or `dir` itself if it is one). */
+function findApp(dir) {
+    if (dir.endsWith(".app") && existsSync(dir))
+        return dir;
+    try {
+        const hit = readdirSync(dir).find((e) => e.endsWith(".app"));
+        if (hit)
+            return path.join(dir, hit);
+    }
+    catch {
+        /* fallthrough */
+    }
+    throw new IosError(`No WebDriverAgentRunner-Runner.app found under ${dir}`);
+}
+// ── HTTP to the runner ────────────────────────────────────────────────────
+async function wdaCall(port, method, route, body) {
+    const url = `http://localhost:${port}${route}`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method,
+            headers: body ? { "Content-Type": "application/json" } : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (e) {
+        throw new IosError(`WDA ${method} ${route} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const text = await resp.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new IosError(`WDA ${method} ${route} returned non-JSON (HTTP ${resp.status})`);
+    }
+    if (!resp.ok) {
+        const detail = json?.value?.message ?? text.slice(0, 200);
+        throw new IosError(`WDA ${method} ${route} -> HTTP ${resp.status}: ${detail}`);
+    }
+    return json;
+}
+function unwrap(json) {
+    return json && typeof json === "object" && "value" in json
+        ? json.value
+        : json;
+}
+// ── Lifecycle ─────────────────────────────────────────────────────────────
+async function simctlRun(args, timeoutMs = 180_000) {
+    try {
+        const { stdout } = await execFileAsync(XCRUN, ["simctl", ...args], {
+            timeout: timeoutMs,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (e) {
+        throw new IosError(`xcrun simctl ${args[0]} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function statusOk(port) {
+    try {
+        const resp = await fetch(`http://localhost:${port}/status`, { signal: AbortSignal.timeout(2500) });
+        return resp.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure a WDA runner is up for `udid` and a session exists, idempotently. If a
+ * runner already answers on the port (a prior `ensureWda`, or an externally
+ * launched one), it is reused — only a fresh session is created. Otherwise the
+ * prebuilt runner is installed and `simctl launch`-ed.
+ */
+export async function ensureWda(udid, opts = {}) {
+    const existing = sessions.get(udid);
+    if (existing && (await statusOk(existing.port)))
+        return existing;
+    const port = DEFAULT_PORT;
+    if (!(await statusOk(port))) {
+        const app = await resolveWdaBundle();
+        await simctlRun(["install", udid, app]);
+        // SIMCTL_CHILD_* env passes through to the launched process; USE_PORT tells
+        // WDA which port to bind. --terminate-running-process clears a stale runner.
+        await execFileAsync(XCRUN, ["simctl", "launch", "--terminate-running-process", udid, WDA_BUNDLE_ID], { timeout: 30_000, env: { ...process.env, SIMCTL_CHILD_USE_PORT: String(port) } }).catch((e) => {
+            throw new IosError(`failed to launch WDA runner: ${e instanceof Error ? e.message : String(e)}`);
+        });
+        const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+        while (!(await statusOk(port))) {
+            if (Date.now() > deadline) {
+                throw new IosError(`WDA runner did not start within ${STARTUP_TIMEOUT_MS / 1000}s`);
+            }
+            await sleep(1000);
+        }
+    }
+    const baseUrl = `http://localhost:${port}`;
+    const caps = opts.bundleId
+        ? { capabilities: { alwaysMatch: { bundleId: opts.bundleId } } }
+        : { capabilities: { alwaysMatch: {} } };
+    const resp = (await wdaCall(port, "POST", "/session", caps));
+    const sessionId = resp.sessionId ?? unwrap(resp)?.sessionId;
+    if (!sessionId)
+        throw new IosError("WDA did not return a sessionId");
+    const session = { port, baseUrl, sessionId };
+    sessions.set(udid, session);
+    return session;
+}
+async function getSession(udid) {
+    const s = sessions.get(udid);
+    if (s && (await statusOk(s.port)))
+        return s;
+    return ensureWda(udid);
+}
+/** Tear down the WDA session for `udid` (the runner is left for the next run). */
+export async function closeWda(udid) {
+    const s = sessions.get(udid);
+    sessions.delete(udid);
+    if (!s)
+        return;
+    try {
+        await wdaCall(s.port, "DELETE", `/session/${s.sessionId}`);
+    }
+    catch {
+        /* best-effort teardown */
+    }
+}
+// ── Geometry + a11y ─────────────────────────────────────────────────────────
+/** Screen geometry from WDA `/wda/screen` (points + retina scale). */
+export async function describeScreen(udid) {
+    const s = await getSession(udid);
+    const v = unwrap(await wdaCall(s.port, "GET", "/wda/screen"));
+    const pointWidth = Number(v.screenSize?.width) || 0;
+    const pointHeight = Number(v.screenSize?.height) || 0;
+    const density = Number(v.scale) || 1;
+    if (!pointWidth || !pointHeight)
+        throw new IosError("WDA /wda/screen returned no screen size");
+    return {
+        pointWidth,
+        pointHeight,
+        density,
+        pixelWidth: Math.round(pointWidth * density),
+        pixelHeight: Math.round(pointHeight * density),
+    };
+}
+/** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
+export async function describeAll(udid) {
+    const s = await getSession(udid);
+    const json = await wdaCall(s.port, "GET", `/session/${s.sessionId}/source?format=json`);
+    return JSON.stringify(json);
+}
+// ── Gestures (W3C pointer actions; coordinates in POINTS) ────────────────────
+function pointerAction(steps) {
+    return {
+        actions: [{ type: "pointer", id: "finger1", parameters: { pointerType: "touch" }, actions: steps }],
+    };
+}
+async function performActions(udid, steps) {
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/actions`, pointerAction(steps));
+}
+export async function uiTap(udid, x, y) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x, y },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: 60 },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+export async function uiLongPress(udid, x, y, durationMs = 600) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x, y },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: durationMs },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+export async function uiSwipe(udid, x1, y1, x2, y2, durationMs = 300) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x: x1, y: y1 },
+        { type: "pointerDown", button: 0 },
+        { type: "pointerMove", duration: durationMs, x: x2, y: y2 },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+/** Type into the focused element (the caller taps a field first). */
+export async function uiText(udid, text) {
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [...text] });
+}
+/**
+ * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
+ * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ */
+export async function uiKey(udid, keycode) {
+    if (keycode !== 40)
+        throw new IosError(`unsupported WDA keycode: ${keycode}`);
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [W3C_ENTER] });
+}
+/** Re-export so a future ios.ts can drop the simctl HID constant. */
+export const HID_KEY_RETURN = 40;

package/dist/lib/paths.d.ts

@@ -12,4 +12,18 @@ export declare function binDir(): string;
 export declare function browsersDir(): string;
 export declare function simulationsDir(): string;
 export declare function cloudflaredBin(): string;
+/**
+ * Cache dir for the prebuilt iOS XCUITest runner (WebDriverAgent) bundle —
+ * the `.app` + `.xctestrun` fetched on demand for native iOS simulations,
+ * mirroring how `cloudflaredBin()` is fetched into `binDir()`.
+ */
+export declare function wdaDir(): string;
+/** Stamp file recording which CLI/runner version the cached WDA bundle is for. */
+export declare function wdaVersionFile(): string;
+/**
+ * Path to `adb` inside Google's standalone Android platform-tools, when we've
+ * fetched it into `binDir()` on demand (the zip unpacks a `platform-tools/`
+ * dir). Mirrors `cloudflaredBin()` / `wdaDir()`.
+ */
+export declare function adbBin(): string;
 export declare function connectLockPath(): string;

package/dist/lib/paths.js

@@ -34,6 +34,27 @@ export function cloudflaredBin() {
     const exe = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
     return path.join(binDir(), exe);
 }
+/**
+ * Cache dir for the prebuilt iOS XCUITest runner (WebDriverAgent) bundle —
+ * the `.app` + `.xctestrun` fetched on demand for native iOS simulations,
+ * mirroring how `cloudflaredBin()` is fetched into `binDir()`.
+ */
+export function wdaDir() {
+    return path.join(binDir(), "wda");
+}
+/** Stamp file recording which CLI/runner version the cached WDA bundle is for. */
+export function wdaVersionFile() {
+    return path.join(wdaDir(), "VERSION");
+}
+/**
+ * Path to `adb` inside Google's standalone Android platform-tools, when we've
+ * fetched it into `binDir()` on demand (the zip unpacks a `platform-tools/`
+ * dir). Mirrors `cloudflaredBin()` / `wdaDir()`.
+ */
+export function adbBin() {
+    const exe = process.platform === "win32" ? "adb.exe" : "adb";
+    return path.join(binDir(), "platform-tools", exe);
+}
 export function connectLockPath() {
     return path.join(rootDir(), "connect.lock");
 }

package/dist/lib/report-readiness.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Best-effort readiness reporting to the ish backend.
+ *
+ * After the CLI computes its native-simulation readiness checks (the same
+ * array `ish check <platform> --json` emits), we POST them to
+ * `${apiUrl}/api/v1/connect/device` so the ish web app can render a live
+ * native-readiness panel. This is the native analog of how `ish connect
+ * <port>` registers a cloudflare tunnel: a side-channel that tells the
+ * backend "this developer's machine is (or isn't) ready to drive a native
+ * iOS/Android simulation right now."
+ *
+ * Contract (must match the backend exactly):
+ *
+ *   POST /api/v1/connect/device
+ *   {
+ *     "platform":    "ios" | "android",
+ *     "checks":      [ {key,name,group,status,message?,fix?}, ... ],
+ *     "overall":     "pass" | "warn" | "fail" | "skip",
+ *     "cli_version": "<package.json version>"
+ *   }
+ *
+ * This is COMPLETELY best-effort. It never throws, never blocks the command,
+ * never writes to stdout, and silently returns when the user isn't logged in
+ * or is offline. The CLI's normal output and exit code are unaffected. The
+ * only side-channel is an optional stderr line under a `debug` flag, mirroring
+ * how connect.ts logs its own warnings.
+ */
+import type { GlobalOpts } from "./command-helpers.js";
+import type { Check, CheckStatus } from "../commands/doctor.js";
+/**
+ * POST the platform-scoped readiness checks to the backend. Best-effort:
+ * resolves auth + posts inside a single try/catch, swallowing every error.
+ *
+ * @param platform  The native platform the checks were scoped to.
+ * @param checks    The exact `runChecks()` array (already scoped to `platform`).
+ * @param overall   The aggregate status (`overall(checks)`).
+ * @param globals   Resolved CLI globals — used only for `--api-url` / `--dev`
+ *                  / `--token` resolution. Pass the command's `globals`.
+ * @param opts.debug  When true, log a one-line failure note to stderr (off by
+ *                    default so the post is silent). Mirrors connect.ts.
+ */
+export declare function reportReadiness(platform: "ios" | "android", checks: Check[], overall: CheckStatus, globals: Pick<GlobalOpts, "apiUrl" | "dev" | "token" | "tokenFile">, opts?: {
+    debug?: boolean;
+}): Promise<void>;

package/dist/lib/report-readiness.js

@@ -0,0 +1,74 @@
+/**
+ * Best-effort readiness reporting to the ish backend.
+ *
+ * After the CLI computes its native-simulation readiness checks (the same
+ * array `ish check <platform> --json` emits), we POST them to
+ * `${apiUrl}/api/v1/connect/device` so the ish web app can render a live
+ * native-readiness panel. This is the native analog of how `ish connect
+ * <port>` registers a cloudflare tunnel: a side-channel that tells the
+ * backend "this developer's machine is (or isn't) ready to drive a native
+ * iOS/Android simulation right now."
+ *
+ * Contract (must match the backend exactly):
+ *
+ *   POST /api/v1/connect/device
+ *   {
+ *     "platform":    "ios" | "android",
+ *     "checks":      [ {key,name,group,status,message?,fix?}, ... ],
+ *     "overall":     "pass" | "warn" | "fail" | "skip",
+ *     "cli_version": "<package.json version>"
+ *   }
+ *
+ * This is COMPLETELY best-effort. It never throws, never blocks the command,
+ * never writes to stdout, and silently returns when the user isn't logged in
+ * or is offline. The CLI's normal output and exit code are unaffected. The
+ * only side-channel is an optional stderr line under a `debug` flag, mirroring
+ * how connect.ts logs its own warnings.
+ */
+import { resolveApiUrl, resolveToken } from "./auth.js";
+import { ApiClient } from "./api-client.js";
+import pkg from "../../package.json" with { type: "json" };
+/** Backend endpoint (relative to the `/api/v1` base ApiClient prepends). */
+const DEVICE_ENDPOINT = "/connect/device";
+/**
+ * POST the platform-scoped readiness checks to the backend. Best-effort:
+ * resolves auth + posts inside a single try/catch, swallowing every error.
+ *
+ * @param platform  The native platform the checks were scoped to.
+ * @param checks    The exact `runChecks()` array (already scoped to `platform`).
+ * @param overall   The aggregate status (`overall(checks)`).
+ * @param globals   Resolved CLI globals — used only for `--api-url` / `--dev`
+ *                  / `--token` resolution. Pass the command's `globals`.
+ * @param opts.debug  When true, log a one-line failure note to stderr (off by
+ *                    default so the post is silent). Mirrors connect.ts.
+ */
+export async function reportReadiness(platform, checks, overall, globals, opts = {}) {
+    try {
+        const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+        // resolveToken throws when the user isn't logged in (or a network blip
+        // prevents an expired-token refresh) — that throw is caught below and we
+        // silently return, exactly as required for the offline / logged-out case.
+        const token = await resolveToken(globals.token, apiUrl, globals.tokenFile);
+        const client = new ApiClient({ apiUrl, token });
+        await client.post(DEVICE_ENDPOINT, {
+            platform,
+            checks,
+            overall,
+            cli_version: pkg.version,
+        }, 
+        // Tight timeout: `ish check` awaits this so the beacon lands before the
+        // process exits, but the panel POST must never stall the command. 2.5s
+        // is plenty on a healthy backend and bounds the worst case if the host
+        // is unreachable or hung.
+        { timeout: 2_500 });
+    }
+    catch (err) {
+        // Swallow everything. A logged-out user, an offline machine, an old
+        // backend without the endpoint, a 5xx — none of it should ever surface
+        // to the user or change the command's behavior.
+        if (opts.debug) {
+            const reason = err instanceof Error ? err.message : String(err);
+            console.error(`(readiness report skipped: ${reason})`);
+        }
+    }
+}

package/dist/lib/skill-content.js

@@ -230,6 +230,8 @@ To hand a study to someone **without an ish account** — a prospect, a stakehol
 - **\`ish person create\` accepts inline flags** (mirrors \`person update\`): the file-only API (\`--file <path>\`) is preserved as an escape hatch but the common path is \`ish person create --name "X" --type ai --country US ...\` — \`--type\` defaults to \`ai\` when \`--file\` is omitted. See \`ish person create --help\` for the full inline-flag set including \`--household\` (MECE rule applies) and \`--accessibility-profile\`.
 - **\`ish status\` now surfaces \`chat_endpoint\`** alongside \`workspace\`/\`study\`/\`ask\`. Stale or orphan active refs get a \`warning\` + \`hint\` field on the affected ref (instead of silently dropping the \`name\`). On \`workspace use <other>\`, the CLI cascade-clears \`study\`/\`ask\`/\`chat_endpoint\` (they belong to the previous workspace).
 - **Share link URL host ≠ API host**: \`ish study share\` prints the backend-built \`share_url\` (the web frontend host). Use it verbatim — never reconstruct the URL from the API host or app URL; they differ. \`ish study unshare\` takes the **raw token** (from \`study share\` / \`study share --list\`), not a study id or alias.
+- **Native app iterations (ios/android) name the app, not a URL**: \`ish iteration create --platform ios --app <bundle-id>\` stores the target as \`app_artifact\` (no URL). The iteration remembers it, so \`ish study run --local\` needs **no \`--app\` on reruns** (it defaults from the iteration). Pass \`--app <path-to.app|.apk>\` only to override with a fresh local build. \`--app\` is optional at create time (omit it for "chosen at run time"). Only \`browser\`/\`figma\` iterations require \`--url\`.
+- **Local runs have no server-side screenshots**: \`ish study run --local\` (including ios/android) writes a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (path printed at the end of the run) instead of pushing screenshots to the server. \`ish study screenshots list\` on a local-only study finds none — open the debug report instead.
 
 ## When in doubt
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {