@ishlabs/cli 0.8.1

package/dist/commands/simulation.js

@@ -0,0 +1,647 @@
+/**
+ * ish simulation — Run, monitor, and cancel simulations.
+ *
+ * Primary command: `ish simulation run` — orchestrates the full flow:
+ *   1. Creates iteration (if not provided)
+ *   2. Creates testers from profiles
+ *   3. Starts simulations (interactive or media, based on study modality)
+ */
+import * as readline from "node:readline/promises";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, formatSimulationPoll } from "../lib/output.js";
+function parseMaxInteractions(value) {
+    const n = parseInt(value, 10);
+    if (isNaN(n) || n < 1)
+        throw new Error(`Invalid --max-interactions value: ${value}`);
+    return n;
+}
+function parseSlowMo(value) {
+    const n = parseInt(value, 10);
+    if (isNaN(n) || n < 0)
+        throw new Error(`Invalid --slow-mo value: ${value}`);
+    return n;
+}
+import { MEDIA_MODALITIES } from "../lib/types.js";
+import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
+import { runLocalSimulations } from "../lib/local-sim/loop.js";
+import { ensureBrowser } from "../lib/local-sim/install.js";
+function isMediaModality(modality) {
+    return !!modality && MEDIA_MODALITIES.includes(modality);
+}
+/**
+ * Build iteration details based on study modality and CLI options.
+ */
+function buildCopyContent(opts) {
+    if (!opts.copyText)
+        return undefined;
+    return {
+        text: opts.copyText,
+        ...(opts.copyHtml && { html: opts.copyHtml }),
+        ...(opts.socialPlatform && { social_platform: opts.socialPlatform }),
+        ...(opts.copyPosition && { position: opts.copyPosition }),
+    };
+}
+function buildIterationDetails(modality, opts) {
+    switch (modality) {
+        case "text":
+            if (!opts.contentText) {
+                throw new Error("Text studies require --content-text. Provide the text content to evaluate.");
+            }
+            return {
+                type: "text",
+                content_text: opts.contentText,
+                ...(opts.contentHtml && { content_html: opts.contentHtml }),
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+            };
+        case "video":
+        case "audio": {
+            if (!opts.contentUrl) {
+                throw new Error(`${modality} studies require --content-url. Provide the URL to the ${modality} file.`);
+            }
+            const copy = buildCopyContent(opts);
+            return {
+                type: modality,
+                content_url: opts.contentUrl,
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(copy && { copy_content: copy }),
+            };
+        }
+        case "image": {
+            if (!opts.imageUrls) {
+                throw new Error("Image studies require --image-urls. Provide comma-separated image URLs.");
+            }
+            const copy = buildCopyContent(opts);
+            return {
+                type: "image",
+                image_urls: opts.imageUrls.split(",").map((s) => s.trim()).filter(Boolean),
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(copy && { copy_content: copy }),
+            };
+        }
+        case "document":
+            if (!opts.contentUrl) {
+                throw new Error("Document studies require --content-url. Provide the URL to the document.");
+            }
+            return {
+                type: "document",
+                content_url: opts.contentUrl,
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+            };
+        default:
+            // Interactive
+            if (!opts.url) {
+                throw new Error("Interactive studies require --url. Provide the URL to test.");
+            }
+            return {
+                type: "interactive",
+                platform: opts.platform || "browser",
+                url: opts.url,
+                screen_format: opts.screenFormat || "desktop",
+                ...(opts.locale && { locale: opts.locale }),
+            };
+    }
+}
+/**
+ * Copy relevant fields from a previous iteration's details for reuse.
+ */
+function copyDetailsFromPrevious(modality, details) {
+    if (isMediaModality(modality)) {
+        const copy = details.copy_content;
+        return {
+            ...(typeof details.content_text === "string" && { contentText: details.content_text }),
+            ...(typeof details.content_html === "string" && { contentHtml: details.content_html }),
+            ...(typeof details.content_url === "string" && { contentUrl: details.content_url }),
+            ...(Array.isArray(details.image_urls) && { imageUrls: details.image_urls.join(",") }),
+            ...(typeof details.title === "string" && { title: details.title }),
+            ...(typeof details.mime_type === "string" && { mimeType: details.mime_type }),
+            ...(copy && typeof copy.text === "string" && { copyText: copy.text }),
+            ...(copy && typeof copy.html === "string" && { copyHtml: copy.html }),
+            ...(copy && typeof copy.social_platform === "string" && { socialPlatform: copy.social_platform }),
+            ...(copy && typeof copy.position === "string" && { copyPosition: copy.position }),
+        };
+    }
+    const screenFormat = typeof details.screen_format === "string"
+        ? details.screen_format
+        : typeof details.screenFormat === "string"
+            ? details.screenFormat
+            : undefined;
+    return {
+        ...(typeof details.platform === "string" && { platform: details.platform }),
+        ...(typeof details.url === "string" && { url: details.url }),
+        ...(screenFormat && { screenFormat }),
+    };
+}
+export function registerSimulationCommands(program) {
+    const sim = program
+        .command("simulation")
+        .alias("sim")
+        .description("Run and monitor simulations");
+    // --- Primary: `simulation run` ---
+    sim
+        .command("run")
+        .description("Run simulations (creates iteration + testers + starts simulations)")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
+        .option("--profiles <ids>", "Comma-separated tester profile IDs (auto-selected from last iteration if omitted)")
+        .option("--iteration <id>", "Use existing iteration (skip creation)")
+        .option("--iteration-name <name>", "Name for new iteration (forces creating a new iteration)")
+        // Interactive options
+        .option("--platform <platform>", "Platform (browser, android, figma, code) — interactive only")
+        .option("--url <url>", "URL to test — interactive only")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only")
+        // Media options
+        .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file — text modality")
+        .option("--content-html <html>", "HTML version of the text, or @filepath to read from file — text modality")
+        .option("--content-url <url>", "URL or local file path to media file — video, audio, document modalities")
+        .option("--image-urls <urls>", "Comma-separated image URLs or local file paths — image modality")
+        .option("--title <title>", "Content title — media modalities")
+        .option("--mime-type <type>", "MIME type (e.g. video/mp4) — media modalities")
+        // Copy/caption options (ads & social posts)
+        .option("--copy-text <text>", "Ad copy or social post caption (or @filepath) — ads & social posts")
+        .option("--copy-html <html>", "HTML version of copy text (or @filepath)")
+        .option("--social-platform <platform>", "Social platform (instagram, tiktok, facebook, linkedin, x)")
+        .option("--copy-position <pos>", "Copy position relative to media (before, after)", "after")
+        .option("--config <id>", "Simulation config ID (required for media, auto-resolved for interactive)")
+        // Shared options
+        .option("--max-interactions <n>", "Max interactions per tester")
+        .option("--language <lang>", "Language code (e.g. en, sv)")
+        .option("--locale <locale>", "Locale code (e.g. en-US)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        // Local simulation options
+        .option("--local", "Run simulation with local browser (Playwright) instead of remote")
+        .option("--headed", "Show browser window (local mode only)")
+        .option("--slow-mo <ms>", "Slow down actions by ms (local mode only)")
+        .option("--devtools", "Open Chrome DevTools (local mode only)")
+        .option("--debug", "Enable detailed debug logging to stderr and ~/.ish/local-sim.log")
+        .option("--parallel <n>", "Run N testers in parallel (local mode only, default: all)")
+        .addHelpText("after", `
+Note: --workspace and --study are optional if you have set active context
+  via \`ish workspace use <alias>\` and \`ish study use <alias>\`.
+  Profiles and iteration settings are auto-reused from the latest iteration.
+
+Examples:
+  # Re-run with same settings (after setting context):
+  $ ish sim run -y
+
+  # Interactive — first run:
+  $ ish sim run --workspace w-6ec --study s-b2c --profiles tp-795,tp-af2 --url https://example.com
+
+  # Text/email (inline or from file):
+  $ ish sim run --content-text "Your email content..." --config c-c3c
+  $ ish sim run --content-text @./email.html --config c-c3c
+
+  # Video (URL or local file):
+  $ ish sim run --content-url ./video.mp4 --config c-c3c
+
+  # Image (local files):
+  $ ish sim run --image-urls "./a.png,./b.png" --config c-c3c
+
+  # Document:
+  $ ish sim run --content-url ./report.pdf --config c-c3c
+
+  # Video ad with copy text:
+  $ ish sim run --content-url ./ad.mp4 --copy-text "Buy now — 50% off!" --config c-c3c
+
+  # Social post with caption:
+  $ ish sim run --image-urls ./post.png --copy-text @./caption.txt --social-platform instagram --config c-c3c
+
+  # Re-run existing iteration:
+  $ ish sim run --iteration i-d4e
+
+  # Local browser simulation (no remote Browserbase):
+  $ ish sim run --local --url http://localhost:3000
+  $ ish sim run --local --url http://localhost:3000 --headed --slow-mo 500`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const log = (msg) => { if (!globals.quiet)
+                console.error(msg); };
+            const resolvedWorkspace = resolveWorkspace(opts.workspace);
+            const resolvedStudy = resolveStudy(opts.study);
+            if (opts.iteration && opts.iterationName) {
+                throw new Error("Cannot use both --iteration and --iteration-name. Use --iteration to reuse an existing iteration, or --iteration-name to create a new one.");
+            }
+            // Step 0: Fetch study to determine modality and resolve defaults
+            const study = await client.get(`/studies/${resolvedStudy}`);
+            const modality = study.modality || "interactive";
+            const isMedia = isMediaModality(modality);
+            if (!study.assignments || study.assignments.length === 0) {
+                throw new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `ish study generate`.");
+            }
+            // Validate conflicting options
+            if (isMedia && opts.url) {
+                throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use --content-text, --content-url, or --image-urls instead.`);
+            }
+            if (!isMedia && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
+                throw new Error(`This study uses "interactive" modality — --content-text, --content-url, and --image-urls are for media studies. Use --url instead.`);
+            }
+            // Resolve defaults from latest iteration
+            let profileIds = opts.profiles
+                ? opts.profiles.split(",").map((s) => s.trim()).filter(Boolean).map(resolveId)
+                : [];
+            const profileNames = new Map();
+            let iterationId = opts.iteration ? resolveId(opts.iteration) : undefined;
+            // Mutable copies for resolving from previous iteration
+            let resolvedOpts = { ...opts };
+            const iterations = study.iterations || [];
+            const latest = iterations.length > 0 ? iterations[iterations.length - 1] : null;
+            if (latest) {
+                const iterLabel = latest.label || latest.name || latest.id.slice(0, 8);
+                log(`Using iteration "${iterLabel}" as baseline`);
+                // Reuse iteration if not creating a new one
+                if (!iterationId && !opts.iterationName) {
+                    iterationId = latest.id;
+                }
+                // Fill defaults from previous iteration details
+                const details = latest.details;
+                if (details) {
+                    const prev = copyDetailsFromPrevious(modality, details);
+                    if (!resolvedOpts.platform && prev.platform)
+                        resolvedOpts.platform = prev.platform;
+                    if (!resolvedOpts.url && prev.url)
+                        resolvedOpts.url = prev.url;
+                    if (!resolvedOpts.screenFormat && prev.screenFormat)
+                        resolvedOpts.screenFormat = prev.screenFormat;
+                    if (!resolvedOpts.contentText && prev.contentText)
+                        resolvedOpts.contentText = prev.contentText;
+                    if (!resolvedOpts.contentHtml && prev.contentHtml)
+                        resolvedOpts.contentHtml = prev.contentHtml;
+                    if (!resolvedOpts.contentUrl && prev.contentUrl)
+                        resolvedOpts.contentUrl = prev.contentUrl;
+                    if (!resolvedOpts.imageUrls && prev.imageUrls)
+                        resolvedOpts.imageUrls = prev.imageUrls;
+                    if (!resolvedOpts.title && prev.title)
+                        resolvedOpts.title = prev.title;
+                    if (!resolvedOpts.mimeType && prev.mimeType)
+                        resolvedOpts.mimeType = prev.mimeType;
+                    if (!resolvedOpts.copyText && prev.copyText)
+                        resolvedOpts.copyText = prev.copyText;
+                    if (!resolvedOpts.copyHtml && prev.copyHtml)
+                        resolvedOpts.copyHtml = prev.copyHtml;
+                    if (!resolvedOpts.socialPlatform && prev.socialPlatform)
+                        resolvedOpts.socialPlatform = prev.socialPlatform;
+                    if (!resolvedOpts.copyPosition && prev.copyPosition)
+                        resolvedOpts.copyPosition = prev.copyPosition;
+                }
+                // Auto-select profiles from latest iteration's testers
+                if (profileIds.length === 0 && latest.testers && latest.testers.length > 0) {
+                    const seen = new Set();
+                    for (const t of latest.testers) {
+                        const pid = t.tester_profile_id || t.tester_profile?.id;
+                        if (pid && !seen.has(pid)) {
+                            seen.add(pid);
+                            profileIds.push(pid);
+                            const name = t.tester_profile?.name;
+                            if (name)
+                                profileNames.set(pid, name);
+                        }
+                    }
+                }
+            }
+            if (profileIds.length === 0) {
+                throw new Error("No profiles specified and no previous iteration to copy from. Use --profiles <ids>.");
+            }
+            // Resolve local file paths → upload to storage and get URLs
+            if (isMedia) {
+                if (resolvedOpts.contentText) {
+                    resolvedOpts.contentText = resolveTextContent(resolvedOpts.contentText);
+                }
+                if (resolvedOpts.contentHtml) {
+                    resolvedOpts.contentHtml = resolveTextContent(resolvedOpts.contentHtml);
+                }
+                if (resolvedOpts.copyText) {
+                    resolvedOpts.copyText = resolveTextContent(resolvedOpts.copyText);
+                }
+                if (resolvedOpts.copyHtml) {
+                    resolvedOpts.copyHtml = resolveTextContent(resolvedOpts.copyHtml);
+                }
+                if (resolvedOpts.contentUrl) {
+                    resolvedOpts.contentUrl = await resolveContentUrl(client, resolvedStudy, resolvedOpts.contentUrl, { mimeTypeOverride: resolvedOpts.mimeType, quiet: globals.quiet });
+                }
+                if (resolvedOpts.imageUrls) {
+                    const urls = await resolveContentUrls(client, resolvedStudy, resolvedOpts.imageUrls, { mimeTypeOverride: resolvedOpts.mimeType, quiet: globals.quiet });
+                    resolvedOpts.imageUrls = urls.join(",");
+                }
+            }
+            // Resolve config_id for media simulations
+            const resolvedConfigOverride = opts.config ? resolveId(opts.config) : undefined;
+            const profileConfigMap = new Map();
+            if (isMedia && !resolvedConfigOverride) {
+                // Resolve config from each profile's simulation_config_id
+                for (const pid of profileIds) {
+                    const profile = await client.get(`/tester-profiles/${pid}`);
+                    if (profile.simulation_config_id) {
+                        profileConfigMap.set(pid, profile.simulation_config_id);
+                    }
+                    else {
+                        throw new Error(`Profile ${profileNames.get(pid) || pid} has no simulation config assigned.\n` +
+                            "Use --config <id> to specify one, or assign a config to the profile.\n" +
+                            "List configs with: ish config list");
+                    }
+                }
+            }
+            // Confirmation step
+            if (!globals.json && !opts.yes) {
+                log("");
+                log("  Simulation settings:");
+                log(`    Modality:       ${modality}`);
+                if (study.content_type)
+                    log(`    Content type:   ${study.content_type}`);
+                if (isMedia) {
+                    if (resolvedOpts.title)
+                        log(`    Title:          ${resolvedOpts.title}`);
+                    if (resolvedOpts.contentText)
+                        log(`    Content:        ${resolvedOpts.contentText.slice(0, 80)}${resolvedOpts.contentText.length > 80 ? "..." : ""}`);
+                    if (resolvedOpts.contentUrl)
+                        log(`    Content URL:    ${resolvedOpts.contentUrl}`);
+                    if (resolvedOpts.imageUrls)
+                        log(`    Image URLs:     ${resolvedOpts.imageUrls}`);
+                    if (resolvedOpts.mimeType)
+                        log(`    MIME type:      ${resolvedOpts.mimeType}`);
+                    if (resolvedOpts.copyText)
+                        log(`    Copy text:      ${resolvedOpts.copyText.slice(0, 80)}${resolvedOpts.copyText.length > 80 ? "..." : ""}`);
+                    if (resolvedOpts.socialPlatform)
+                        log(`    Platform:       ${resolvedOpts.socialPlatform}`);
+                    if (resolvedConfigOverride)
+                        log(`    Config:         ${resolvedConfigOverride}`);
+                }
+                else {
+                    log(`    Platform:       ${resolvedOpts.platform || "browser"}`);
+                    log(`    Screen format:  ${resolvedOpts.screenFormat || "desktop"}`);
+                    if (resolvedOpts.url)
+                        log(`    URL:            ${resolvedOpts.url}`);
+                }
+                if (opts.language)
+                    log(`    Language:       ${opts.language}`);
+                log(`    Profiles (${profileIds.length}):`);
+                for (const pid of profileIds) {
+                    const name = profileNames.get(pid);
+                    log(`      - ${name ? `${name} (${pid})` : pid}`);
+                }
+                log("");
+                const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+                const answer = await rl.question("  Proceed? [Y/n] ");
+                rl.close();
+                if (answer && !["y", "yes", ""].includes(answer.toLowerCase().trim())) {
+                    log("Aborted.");
+                    process.exit(0);
+                }
+                log("");
+            }
+            // Ensure browser is ready before creating server-side state
+            if (opts.local) {
+                await ensureBrowser({ quiet: globals.quiet, skipPrompt: globals.json });
+            }
+            // Step 1: Create or use existing iteration
+            if (!iterationId) {
+                const iterName = resolvedOpts.iterationName || `CLI ${new Date().toISOString().slice(0, 16)}`;
+                const iterBody = {
+                    name: iterName,
+                    details: buildIterationDetails(modality, resolvedOpts),
+                };
+                log(`Creating iteration "${iterName}"...`);
+                const iter = await client.post(`/studies/${resolvedStudy}/iterations`, iterBody);
+                iterationId = iter.id;
+                log(`Created iteration "${iterName}"`);
+            }
+            else if (!opts.iteration) {
+                // Auto-reused iteration — update its details to reflect current run
+                const newDetails = buildIterationDetails(modality, resolvedOpts);
+                await client.put(`/iterations/${iterationId}`, { details: newDetails });
+            }
+            // Step 2: Create testers from profiles (or reuse from explicit iteration)
+            let createdTesters;
+            if (opts.iteration && !opts.profiles) {
+                // Reuse existing testers from the explicitly provided iteration
+                const existingIter = await client.get(`/iterations/${iterationId}`);
+                if (existingIter.testers && existingIter.testers.length > 0) {
+                    createdTesters = existingIter.testers;
+                    log(`Reusing ${createdTesters.length} existing tester${createdTesters.length > 1 ? "s" : ""} from iteration`);
+                }
+                else {
+                    throw new Error("Iteration has no existing testers. Use --profiles to create new testers.");
+                }
+            }
+            else {
+                const testerInputs = profileIds.map((profileId) => ({
+                    tester_profile_id: profileId,
+                    tester_type: "ai",
+                    status: "draft",
+                    ...(opts.language && { language: opts.language }),
+                    ...(!isMedia && { platform: resolvedOpts.platform || "browser" }),
+                }));
+                log(`Creating ${testerInputs.length} tester${testerInputs.length > 1 ? "s" : ""}...`);
+                const batchResult = await client.post(`/iterations/${iterationId}/testers/batch`, { testers: testerInputs });
+                createdTesters = batchResult.testers;
+                log(`Created ${createdTesters.length} tester${createdTesters.length > 1 ? "s" : ""}`);
+            }
+            // Step 3: Start simulations
+            // Local mode: run simulations with local browser
+            if (opts.local) {
+                if (isMedia) {
+                    throw new Error("Local mode is only supported for interactive simulations.");
+                }
+                const testerNameMap = new Map();
+                for (const t of createdTesters) {
+                    testerNameMap.set(t.id, t.tester_profile?.name ?? "Unknown");
+                }
+                await runLocalSimulations(client, {
+                    workspaceId: resolvedWorkspace,
+                    studyId: resolvedStudy,
+                    iterationId: iterationId,
+                    testerIds: createdTesters.map((t) => t.id),
+                    testerNames: testerNameMap,
+                    url: resolvedOpts.url,
+                    screenFormat: resolvedOpts.screenFormat,
+                    locale: opts.locale,
+                    maxInteractions: opts.maxInteractions ? parseMaxInteractions(opts.maxInteractions) : undefined,
+                    headed: !!opts.headed,
+                    slowMo: opts.slowMo ? parseSlowMo(opts.slowMo) : undefined,
+                    devtools: opts.devtools,
+                    debug: opts.debug,
+                    parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
+                    quiet: globals.quiet,
+                    json: globals.json,
+                });
+                if (globals.json) {
+                    output({
+                        iteration_id: iterationId,
+                        testers: createdTesters.map((t) => ({ id: t.id, profile_name: t.tester_profile?.name })),
+                        mode: "local",
+                    }, true);
+                }
+                return;
+            }
+            // Remote mode: delegate to backend
+            log(`Starting ${createdTesters.length} simulation${createdTesters.length > 1 ? "s" : ""}...`);
+            let simResults;
+            if (isMedia) {
+                // Media batch endpoint — resolve config per tester from override or profile
+                const mediaBatchItems = createdTesters.map((t, i) => ({
+                    study_id: resolvedStudy,
+                    tester_id: t.id,
+                    config_id: resolvedConfigOverride || profileConfigMap.get(profileIds[i]),
+                    ...(opts.language && { language: opts.language }),
+                }));
+                const simResult = await client.post("/simulation/media/start/batch", {
+                    product_id: resolvedWorkspace,
+                    simulations: mediaBatchItems,
+                    ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                }, { timeout: 60_000 });
+                simResults = simResult.results;
+            }
+            else {
+                // Interactive batch endpoint
+                const simItems = createdTesters.map((t) => ({
+                    study_id: resolvedStudy,
+                    tester_id: t.id,
+                    ...(opts.config && { config_id: resolveId(opts.config) }),
+                    ...(opts.language && { language: opts.language }),
+                    ...(opts.locale && { locale: opts.locale }),
+                }));
+                const simResult = await client.post("/simulation/interactive/start/batch", {
+                    product_id: resolvedWorkspace,
+                    simulations: simItems,
+                    platform: resolvedOpts.platform || "browser",
+                    ...(resolvedOpts.url && { url: resolvedOpts.url }),
+                    screen_format: resolvedOpts.screenFormat || "desktop",
+                    ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                }, { timeout: 60_000 });
+                simResults = simResult.results;
+            }
+            if (globals.json) {
+                output({
+                    iteration_id: iterationId,
+                    testers: createdTesters.map((t) => ({ id: t.id, profile_name: t.tester_profile?.name })),
+                    simulations: simResults,
+                }, true);
+            }
+            else {
+                for (let i = 0; i < simResults.length; i++) {
+                    const tester = createdTesters[i];
+                    const profileName = tester?.tester_profile?.name || "Unknown";
+                    log(`  ${profileName.padEnd(24)} QUEUED`);
+                }
+                const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
+                log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                log(`Run \`ish simulation poll --study ${resolvedStudy}\` to check progress.`);
+            }
+        });
+    });
+    // --- Poll: check simulation progress ---
+    sim
+        .command("poll")
+        .description("Check simulation progress")
+        .argument("[job_id]", "Job ID (for single simulation)")
+        .option("--study <id>", "Study ID (poll all simulations for study)")
+        .addHelpText("after", "\nExamples:\n  $ ish simulation poll --study <study_id>\n  $ ish simulation poll <job_id> --json")
+        .action(async (jobId, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (jobId) {
+                // Single job status
+                const data = await client.get(`/simulation/status/${resolveId(jobId)}`);
+                output(data, globals.json);
+            }
+            else if (opts.study) {
+                const rid = resolveId(opts.study);
+                const study = await client.get(`/studies/${rid}`);
+                const isMedia = isMediaModality(study.modality);
+                // Collect all testers across iterations
+                const allTesters = [];
+                for (const iteration of study.iterations || []) {
+                    for (const tester of iteration.testers || []) {
+                        allTesters.push({
+                            id: tester.id,
+                            status: tester.status,
+                            tester_name: tester.tester_profile?.name || "Unknown",
+                            interaction_count: Array.isArray(tester.interactions) ? tester.interactions.length : 0,
+                            ...(tester.error && { error: tester.error }),
+                            ...(tester.failure_reason && { error: tester.failure_reason }),
+                        });
+                    }
+                }
+                formatSimulationPoll(allTesters, globals.json, isMedia);
+                if (!globals.json && study.product_id) {
+                    const url = getWebUrl(globals, `/${study.product_id}/${rid}/timeline`);
+                    console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                }
+            }
+            else {
+                throw new Error("Provide a job_id argument or --study flag");
+            }
+        });
+    });
+    // --- Lower-level commands ---
+    sim
+        .command("start")
+        .description("Start a single interactive simulation (low-level)")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
+        .requiredOption("--tester <id>", "Tester ID")
+        .option("--config <id>", "Simulation config ID (resolved from profile if omitted)")
+        .option("--platform <platform>", "Platform (browser, android, figma, code)", "browser")
+        .option("--url <url>", "URL to test")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop)")
+        .option("--max-interactions <n>", "Max interactions")
+        .option("--language <lang>", "Language code")
+        .option("--locale <locale>", "Locale code")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                product_id: resolveWorkspace(opts.workspace),
+                study_id: resolveStudy(opts.study),
+                tester_id: resolveId(opts.tester),
+                ...(opts.config && { config_id: resolveId(opts.config) }),
+                platform: opts.platform,
+                ...(opts.url && { url: opts.url }),
+                ...(opts.screenFormat && { screen_format: opts.screenFormat }),
+                ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                ...(opts.language && { language: opts.language }),
+                ...(opts.locale && { locale: opts.locale }),
+            };
+            const data = await client.post("/simulation/interactive/start", body);
+            output(data, globals.json);
+        });
+    });
+    sim
+        .command("start-media")
+        .description("Start a media simulation (low-level)")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
+        .requiredOption("--tester <id>", "Tester ID")
+        .requiredOption("--config <id>", "Simulation config ID")
+        .option("--max-interactions <n>", "Max interactions")
+        .option("--language <lang>", "Language code")
+        .addHelpText("after", `
+Examples:
+  $ ish sim start-media --workspace W --study S --tester T --config C
+  $ ish sim start-media --workspace W --study S --tester T --config C --max-interactions 10`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                product_id: resolveWorkspace(opts.workspace),
+                study_id: resolveStudy(opts.study),
+                tester_id: resolveId(opts.tester),
+                config_id: resolveId(opts.config),
+                ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                ...(opts.language && { language: opts.language }),
+            };
+            const data = await client.post("/simulation/media/start", body);
+            output(data, globals.json);
+        });
+    });
+    sim
+        .command("cancel")
+        .description("Cancel a simulation")
+        .argument("<job_id>", "Job ID")
+        .action(async (jobId, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.post(`/simulation/cancel/${resolveId(jobId)}`);
+            output(data, globals.json);
+        });
+    });
+}

package/dist/commands/study.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ish study — Manage studies.
+ */
+import type { Command } from "commander";
+export declare function registerStudyCommands(program: Command): void;