@ishlabs/cli 0.27.0 → 0.27.1

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

@@ -31,8 +31,19 @@ const WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
 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
+/**
+ * The Return keystroke we feed to WDA's `/wda/keys` for a submit.
+ *
+ * NOT the W3C ENTER code (U+E007): WDA's `/wda/keys` does NOT interpret the
+ * WebDriver special-key PUA codepoints \u2014 it types them LITERALLY. On the
+ * simulator U+E007 renders as a running-shoe emoji, so a submit appended a
+ * stray `\uD83D\uDC5F` to the field (e.g. a search for `Photos` became `Photos\uD83D\uDC5F`,
+ * returning no results and derailing the run) AND never actually submitted.
+ * A plain newline is what WDA's keyboard treats as Return \u2014 it submits
+ * single-line fields and inserts a line break in multiline ones, with no glyph.
+ * Verified on a booted iOS 18 simulator (Settings search).
+ */
+export const WDA_RETURN = "\n";
 const sessions = new Map();
 // ── WDA bundle resolution (fetch is wired in the distribution phase) ──────────
 /** Appium's prebuilt WebDriverAgent simulator release we fetch + pin. */
@@ -178,7 +189,10 @@ export async function ensureWda(udid, opts = {}) {
     const existing = sessions.get(udid);
     if (existing && (await statusOk(existing.port)))
         return existing;
-    const port = DEFAULT_PORT;
+    // Each device gets its own WDA runner on its own port so N pooled simulators
+    // don't collide on 8100. The pool allocates the port and passes it in; the
+    // single-device path falls back to DEFAULT_PORT (8100 / $ISH_WDA_PORT).
+    const port = opts.port ?? DEFAULT_PORT;
     if (!(await statusOk(port))) {
         const app = await resolveWdaBundle();
         await simctlRun(["install", udid, app]);
@@ -211,7 +225,9 @@ async function getSession(udid) {
     const s = sessions.get(udid);
     if (s && (await statusOk(s.port)))
         return s;
-    return ensureWda(udid);
+    // Re-ensure on the SAME port if this device had one (a WDA restart mid-run
+    // must not migrate a pooled device back to DEFAULT_PORT).
+    return ensureWda(udid, s ? { port: s.port } : {});
 }
 /** Tear down the WDA session for `udid` (the runner is left for the next run). */
 export async function closeWda(udid) {
@@ -307,13 +323,13 @@ export async function uiText(udid, 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.
+ * map it to a newline (see WDA_RETURN). 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] });
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [WDA_RETURN] });
 }
 /** 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

@@ -27,3 +27,4 @@ export declare function wdaVersionFile(): string;
  */
 export declare function adbBin(): string;
 export declare function connectLockPath(): string;
+export declare function devicePoolLockPath(): string;

package/dist/lib/paths.js

@@ -58,3 +58,6 @@ export function adbBin() {
 export function connectLockPath() {
     return path.join(rootDir(), "connect.lock");
 }
+export function devicePoolLockPath() {
+    return path.join(rootDir(), "device-pool.lock");
+}

package/dist/lib/skill-content.js

@@ -230,8 +230,11 @@ 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.
+- **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). \`screen_format\` defaults to **mobile_portrait** for native (vs desktop for browser). 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\`. Full walkthrough: \`ish docs get-page guides/native-app\`.
+- **Native runs reset state per participant only with a local .app**: with a local \`.app\`/\`.apk\` the runner uninstall+reinstalls before each participant (no state leak). A bare bundle-id / system app (e.g. \`com.apple.reminders\`) can't be reinstalled — it relaunches and warns once that earlier-participant state may persist; pass \`--app <.app>\` or run one participant per study for a clean start.
+- **Parallel native runs**: \`ish study run --local --platform ios|android --parallel N\` drives a **pool of N devices** (iOS: reuses booted simulators + auto-creates the shortfall; Android: reuses online emulators + auto-launches headless emulators from your AVDs), one participant per device, and tears down only what it started. N auto-sizes to host RAM; default 1, max 5 — small machines run fewer + queue, never error. Android needs just **one AVD** (the pool clones it via file-copy — no JDK — and deletes the clones). Browser \`--parallel\` is unchanged.
+- **Local runs still capture per-interaction screenshots**: \`ish study run --local\` (including ios/android) does NOT populate the remote frame-grouped index (\`ish study screenshots list\` reads that and won't show local frames), but per-interaction screenshots ARE captured — read them via \`ish study get <id>\` (each interaction carries \`screenshot_url\`) or the per-step HTML debug report at \`~/.ish/debug/sim-*.html\` (path printed at the end of the run).
+- **\`<entity> use --json\` is capturable**: \`study use\`/\`workspace use\`/\`ask use\` print the human confirmation to stderr and an \`{id, alias, name, active}\` object to stdout under \`--json\`, so \`ish study use s-… --json --get alias\` works.
 
 ## When in doubt
 

package/dist/lib/upload.d.ts

@@ -16,6 +16,14 @@ export declare function validateFile(filePath: string): Promise<{
     size: number;
     mime: string;
 }>;
+/**
+ * Upload raw bytes to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url. The bytes-level core shared by file uploads
+ * and HTML image archiving (no temp file needed).
+ */
+export declare function uploadStudyContentBytes(client: ApiClient, studyId: string, data: Buffer, mime: string, name: string, opts?: {
+    quiet?: boolean;
+}): Promise<string>;
 /**
  * Upload a local file to Supabase Storage via the backend's signed URL flow.
  * Returns the public content_url for use in iteration details.
@@ -40,6 +48,25 @@ export declare function resolveContentUrls(client: ApiClient, studyId: string, c
     mimeTypeOverride?: string;
     quiet?: boolean;
 }): Promise<string[]>;
+/**
+ * Archive every external `<img>` in a text iteration's `content_html` onto the
+ * workspace storage origin, rewriting each `src` to the uploaded URL.
+ *
+ * Why: the render-to-image worker that lets a participant SEE the page
+ * default-denies egress to every origin except workspace storage (SSRF guard).
+ * An `<img>` pointing at the open web is therefore aborted and renders broken.
+ * The frontend's paste pipeline (`cacheHtmlAssets`) already archives images;
+ * this is the CLI-side equivalent so `ish iteration create --content-html`
+ * produces content whose images actually render. It is a focused subset (just
+ * `<img src>` via regex — the CLI has no HTML-parser dependency); inline
+ * `data:` images, relative paths, and non-image responses are left untouched.
+ *
+ * Best-effort: a single image that cannot be fetched/uploaded is left as-is
+ * with a warning rather than failing the whole create.
+ */
+export declare function archiveHtmlImages(client: ApiClient, studyId: string, html: string, opts?: {
+    quiet?: boolean;
+}): Promise<string>;
 /**
  * Resolve text content. If the value starts with '@', read the file at
  * the path that follows (curl-style convention). Otherwise return as-is.

package/dist/lib/upload.js

@@ -96,29 +96,30 @@ export async function validateFile(filePath) {
 // Core upload: 3-step backend-mediated flow
 // ---------------------------------------------------------------------------
 /**
- * Upload a local file to Supabase Storage via the backend's signed URL flow.
- * Returns the public content_url for use in iteration details.
+ * Upload raw bytes to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url. The bytes-level core shared by file uploads
+ * and HTML image archiving (no temp file needed).
  */
-export async function uploadStudyContent(client, studyId, filePath, opts) {
-    const resolved = resolvePath(filePath);
-    const { size, mime: detectedMime } = await validateFile(filePath);
-    const mime = opts?.mimeTypeOverride || detectedMime;
-    const name = basename(filePath);
+export async function uploadStudyContentBytes(client, studyId, data, mime, name, opts) {
+    const size = data.byteLength;
     const sizeMB = (size / (1024 * 1024)).toFixed(1);
     const log = (msg) => { if (!opts?.quiet)
         process.stderr.write(msg); };
     // Step 1: Request a signed upload URL from the backend
     log(`Uploading ${name} (${sizeMB} MB)...`);
     const uploadResp = await client.post(`/studies/${studyId}/content/upload`, { content_type: mime, file_size_bytes: size }, { timeout: 60_000 });
-    // Step 2: PUT the raw file bytes to the signed URL
-    const fileBuffer = await readFile(resolved);
+    // Step 2: PUT the raw bytes to the signed URL
     const putResp = await fetch(uploadResp.upload_info.signed_upload_url, {
         method: "PUT",
         headers: {
             "Content-Type": mime,
-            "Content-Length": String(fileBuffer.byteLength),
+            "Content-Length": String(size),
         },
-        body: fileBuffer,
+        // Zero-copy view as Uint8Array<ArrayBuffer>: a Node Buffer's generic
+        // ArrayBufferLike (which includes SharedArrayBuffer) is not a valid fetch
+        // BodyInit, but a plain-ArrayBuffer-backed view is. Node buffers are never
+        // SharedArrayBuffer-backed, so the cast is safe.
+        body: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
         signal: AbortSignal.timeout(300_000), // 5 min timeout for large files
     });
     if (!putResp.ok) {
@@ -133,6 +134,17 @@ export async function uploadStudyContent(client, studyId, filePath, opts) {
     log(" done.\n");
     return uploadResp.content_url;
 }
+/**
+ * Upload a local file to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url for use in iteration details.
+ */
+export async function uploadStudyContent(client, studyId, filePath, opts) {
+    const resolved = resolvePath(filePath);
+    const { mime: detectedMime } = await validateFile(filePath);
+    const mime = opts?.mimeTypeOverride || detectedMime;
+    const fileBuffer = await readFile(resolved);
+    return uploadStudyContentBytes(client, studyId, fileBuffer, mime, basename(filePath), { quiet: opts?.quiet });
+}
 // ---------------------------------------------------------------------------
 // High-level resolvers (URL passthrough or upload)
 // ---------------------------------------------------------------------------
@@ -157,6 +169,91 @@ export async function resolveContentUrls(client, studyId, commaSeparated, opts)
     }
     return results;
 }
+// ---------------------------------------------------------------------------
+// HTML image archiving (text modality)
+// ---------------------------------------------------------------------------
+const MAX_ARCHIVED_IMAGE_BYTES = 15 * 1024 * 1024; // 15 MB per image
+const IMAGE_FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Archive every external `<img>` in a text iteration's `content_html` onto the
+ * workspace storage origin, rewriting each `src` to the uploaded URL.
+ *
+ * Why: the render-to-image worker that lets a participant SEE the page
+ * default-denies egress to every origin except workspace storage (SSRF guard).
+ * An `<img>` pointing at the open web is therefore aborted and renders broken.
+ * The frontend's paste pipeline (`cacheHtmlAssets`) already archives images;
+ * this is the CLI-side equivalent so `ish iteration create --content-html`
+ * produces content whose images actually render. It is a focused subset (just
+ * `<img src>` via regex — the CLI has no HTML-parser dependency); inline
+ * `data:` images, relative paths, and non-image responses are left untouched.
+ *
+ * Best-effort: a single image that cannot be fetched/uploaded is left as-is
+ * with a warning rather than failing the whole create.
+ */
+export async function archiveHtmlImages(client, studyId, html, opts) {
+    const log = (msg) => { if (!opts?.quiet)
+        process.stderr.write(msg); };
+    const imgTags = html.match(/<img\b[^>]*>/gi);
+    if (!imgTags)
+        return html;
+    let result = html;
+    let archived = 0;
+    let failed = 0;
+    const seen = new Map(); // original src -> archived url
+    for (const tag of imgTags) {
+        const srcMatch = tag.match(/\bsrc\s*=\s*("([^"]*)"|'([^']*)')/i);
+        if (!srcMatch)
+            continue;
+        const src = srcMatch[2] ?? srcMatch[3] ?? "";
+        // Only archive remote http(s) images; leave data:/blob:/relative as-is.
+        if (!/^https?:\/\//i.test(src))
+            continue;
+        let archivedUrl = seen.get(src);
+        if (archivedUrl === undefined) {
+            try {
+                archivedUrl = await fetchAndUploadImage(client, studyId, src, archived, opts);
+                seen.set(src, archivedUrl);
+                archived += 1;
+            }
+            catch (e) {
+                failed += 1;
+                const reason = e instanceof Error ? e.message : String(e);
+                log(`  ! could not archive image ${src}: ${reason} (it will not render)\n`);
+                continue;
+            }
+        }
+        // Rewrite this tag: point src at the archived URL and drop srcset so the
+        // browser uses the archived src, not an un-archived srcset candidate.
+        let newTag = tag.replace(srcMatch[0], `src="${archivedUrl}"`);
+        newTag = newTag.replace(/\s+srcset\s*=\s*("[^"]*"|'[^']*')/gi, "");
+        if (newTag !== tag)
+            result = result.replace(tag, newTag);
+    }
+    if (archived > 0 || failed > 0) {
+        log(`Archived ${archived} image(s) to workspace storage${failed ? `, ${failed} failed` : ""}.\n`);
+    }
+    return result;
+}
+async function fetchAndUploadImage(client, studyId, url, index, opts) {
+    const resp = await fetch(url, {
+        signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
+        redirect: "follow",
+    });
+    if (!resp.ok)
+        throw new Error(`HTTP ${resp.status}`);
+    const ctype = (resp.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+    if (!ctype.startsWith("image/")) {
+        throw new Error(`not an image (content-type: ${ctype || "unknown"})`);
+    }
+    const bytes = Buffer.from(await resp.arrayBuffer());
+    if (bytes.byteLength === 0)
+        throw new Error("empty response");
+    if (bytes.byteLength > MAX_ARCHIVED_IMAGE_BYTES) {
+        throw new Error(`image too large (${(bytes.byteLength / (1024 * 1024)).toFixed(1)} MB)`);
+    }
+    const ext = ctype.split("/")[1]?.split("+")[0] || "img";
+    return uploadStudyContentBytes(client, studyId, bytes, ctype, `imported-image-${index}.${ext}`, { quiet: opts?.quiet });
+}
 /**
  * Resolve text content. If the value starts with '@', read the file at
  * the path that follows (curl-style convention). Otherwise return as-is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
     "@sentry/node": "^10.13.0",
     "commander": "^13.0.0",
     "http-proxy": "^1.18.1",
-    "playwright-core": "^1.58.2"
+    "playwright-core": "1.59.1"
   },
   "devDependencies": {
     "@types/http-proxy": "^1.17.17",