speqs 0.4.0 → 0.5.1

package/dist/commands/config.d.ts

@@ -0,0 +1,5 @@
+/**
+ * speqs config — Manage simulation configs.
+ */
+import type { Command } from "commander";
+export declare function registerConfigCommands(program: Command): void;

package/dist/commands/config.js

@@ -0,0 +1,73 @@
+/**
+ * speqs config — Manage simulation configs.
+ */
+import { withClient, readJsonFileOrStdin } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, formatConfigList } from "../lib/output.js";
+export function registerConfigCommands(program) {
+    const config = program
+        .command("config")
+        .description("Manage simulation configs");
+    config
+        .command("list")
+        .description("List all simulation configs")
+        .addHelpText("after", "\nExamples:\n  $ speqs config list\n  $ speqs config list --json")
+        .action(async (_opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get("/dev/simulation-configs");
+            formatConfigList(data, globals.json);
+        });
+    });
+    config
+        .command("create")
+        .description("Create a simulation config")
+        .requiredOption("--file <path>", "JSON file with config data")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.post("/dev/simulation-configs", body);
+            output(data, globals.json);
+        });
+    });
+    config
+        .command("get")
+        .description("Get simulation config details")
+        .argument("<id>", "Config ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/dev/simulation-configs/${resolveId(id)}`);
+            output(data, globals.json);
+        });
+    });
+    config
+        .command("schema")
+        .description("Get simulation config schema with defaults")
+        .action(async (_opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get("/dev/simulation-configs/schema");
+            output(data, globals.json);
+        });
+    });
+    config
+        .command("update")
+        .description("Update a simulation config")
+        .argument("<id>", "Config ID")
+        .requiredOption("--file <path>", "JSON file with update data")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.put(`/dev/simulation-configs/${resolveId(id)}`, body);
+            output(data, globals.json);
+        });
+    });
+    config
+        .command("delete")
+        .description("Delete a simulation config")
+        .argument("<id>", "Config ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/dev/simulation-configs/${resolveId(id)}`);
+            output({ message: "Config deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/iteration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * speqs iteration — Manage iterations (usually created via `simulation run`).
+ */
+import type { Command } from "commander";
+export declare function registerIterationCommands(program: Command): void;

package/dist/commands/iteration.js

@@ -0,0 +1,83 @@
+/**
+ * speqs iteration — Manage iterations (usually created via `simulation run`).
+ */
+import { withClient } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, formatIterationList } from "../lib/output.js";
+export function registerIterationCommands(program) {
+    const iteration = program
+        .command("iteration")
+        .description("Manage iterations (usually created via `simulation run`)");
+    iteration
+        .command("list")
+        .description("List iterations for a study")
+        .requiredOption("--study <id>", "Study ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs iteration list --study <id>\n  $ speqs iteration list --study <id> --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/studies/${resolveId(opts.study)}/iterations`);
+            formatIterationList(data, globals.json);
+        });
+    });
+    iteration
+        .command("create")
+        .description("Create a new iteration (low-level)")
+        .requiredOption("--study <id>", "Study ID")
+        .requiredOption("--name <name>", "Iteration name")
+        .option("--description <description>", "Iteration description")
+        .option("--details-json <json>", "Iteration details as JSON string")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                name: opts.name,
+                ...(opts.description && { description: opts.description }),
+                ...(opts.detailsJson && { details: JSON.parse(opts.detailsJson) }),
+            };
+            const data = await client.post(`/studies/${resolveId(opts.study)}/iterations`, body);
+            output(data, globals.json);
+        });
+    });
+    iteration
+        .command("get")
+        .description("Get iteration details")
+        .argument("<id>", "Iteration ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/iterations/${resolveId(id)}`);
+            output(data, globals.json);
+        });
+    });
+    iteration
+        .command("update")
+        .description("Update an iteration")
+        .argument("<id>", "Iteration ID")
+        .option("--name <name>", "Iteration name")
+        .option("--description <description>", "Iteration description")
+        .option("--details-json <json>", "Iteration details as JSON string")
+        .option("--label <label>", "Iteration label (uppercase letters)")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {};
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.detailsJson !== undefined)
+                body.details = JSON.parse(opts.detailsJson);
+            if (opts.label !== undefined)
+                body.label = opts.label;
+            const data = await client.put(`/iterations/${resolveId(id)}`, body);
+            output(data, globals.json);
+        });
+    });
+    iteration
+        .command("delete")
+        .description("Delete an iteration")
+        .argument("<id>", "Iteration ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/iterations/${resolveId(id)}`);
+            output({ message: "Iteration deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/simulation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * speqs simulation — Run, monitor, and cancel simulations.
+ *
+ * Primary command: `speqs simulation run` — orchestrates the full flow:
+ *   1. Creates iteration (if not provided)
+ *   2. Creates testers from profiles
+ *   3. Starts simulations
+ */
+import type { Command } from "commander";
+export declare function registerSimulationCommands(program: Command): void;

package/dist/commands/simulation.js

@@ -0,0 +1,314 @@
+/**
+ * speqs simulation — Run, monitor, and cancel simulations.
+ *
+ * Primary command: `speqs simulation run` — orchestrates the full flow:
+ *   1. Creates iteration (if not provided)
+ *   2. Creates testers from profiles
+ *   3. Starts simulations
+ */
+import * as readline from "node:readline/promises";
+import { withClient, getWebUrl, terminalLink } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, outputError, 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;
+}
+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)")
+        .requiredOption("--workspace <id>", "Workspace ID")
+        .requiredOption("--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)")
+        .option("--platform <platform>", "Platform (browser, android, figma, code)")
+        .option("--url <url>", "URL to test")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop)")
+        .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")
+        .addHelpText("after", `
+Examples:
+  # Re-run with same settings and profiles as last time:
+  $ speqs sim run --workspace W --study S
+
+  # Re-run with different profiles:
+  $ speqs sim run --workspace W --study S --profiles p1,p2
+
+  # Force a new iteration:
+  $ speqs sim run --workspace W --study S --iteration-name "Round 2"
+
+  # First run (no previous iteration):
+  $ speqs sim run --workspace W --study S --profiles p1,p2 --url https://example.com`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const log = (msg) => { if (!globals.quiet)
+                console.error(msg); };
+            // Step 0: Resolve defaults from latest iteration
+            let resolvedPlatform = opts.platform;
+            let resolvedUrl = opts.url;
+            let resolvedScreenFormat = opts.screenFormat;
+            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;
+            const resolvedWorkspace = resolveId(opts.workspace);
+            const resolvedStudy = resolveId(opts.study);
+            if (!iterationId || profileIds.length === 0 || !resolvedPlatform || !resolvedScreenFormat) {
+                const study = await client.get(`/studies/${resolvedStudy}`);
+                if (!study.assignments || study.assignments.length === 0) {
+                    outputError(new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `speqs study generate`."), globals.json);
+                    process.exit(1);
+                }
+                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 platform/url/screen-format from iteration details
+                    const details = latest.details;
+                    if (details) {
+                        if (!resolvedPlatform)
+                            resolvedPlatform = details.platform;
+                        if (!resolvedUrl)
+                            resolvedUrl = details.url;
+                        if (!resolvedScreenFormat)
+                            resolvedScreenFormat = details.screen_format || details.screenFormat;
+                    }
+                    // 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);
+                            }
+                        }
+                    }
+                }
+            }
+            // Apply hardcoded fallbacks
+            resolvedPlatform = resolvedPlatform || "browser";
+            resolvedScreenFormat = resolvedScreenFormat || "desktop";
+            if (profileIds.length === 0) {
+                outputError(new Error("No profiles specified and no previous iteration to copy from. Use --profiles <ids>."), globals.json);
+                process.exit(1);
+            }
+            // Confirmation step — show resolved settings
+            if (!globals.json && !opts.yes) {
+                log("");
+                log("  Simulation settings:");
+                log(`    Platform:       ${resolvedPlatform}`);
+                log(`    Screen format:  ${resolvedScreenFormat}`);
+                if (resolvedUrl)
+                    log(`    URL:            ${resolvedUrl}`);
+                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("");
+            }
+            // Step 1: Create or use existing iteration
+            if (!iterationId) {
+                const iterName = opts.iterationName || `CLI ${new Date().toISOString().slice(0, 16)}`;
+                const iterBody = {
+                    name: iterName,
+                    details: {
+                        type: "interactive",
+                        platform: resolvedPlatform,
+                        url: resolvedUrl || "",
+                        screen_format: resolvedScreenFormat,
+                        ...(opts.locale && { locale: opts.locale }),
+                    },
+                };
+                log(`Creating iteration "${iterName}"...`);
+                const iter = await client.post(`/studies/${resolvedStudy}/iterations`, iterBody);
+                iterationId = iter.id;
+                log(`Created iteration "${iterName}"`);
+            }
+            // Step 2: Create testers from profiles
+            const testerInputs = profileIds.map((profileId) => ({
+                tester_profile_id: profileId,
+                tester_type: "ai",
+                status: "draft",
+                ...(opts.language && { language: opts.language }),
+                platform: resolvedPlatform,
+            }));
+            log(`Creating ${testerInputs.length} tester${testerInputs.length > 1 ? "s" : ""}...`);
+            const batchResult = await client.post(`/iterations/${iterationId}/testers/batch`, { testers: testerInputs });
+            const createdTesters = batchResult.testers;
+            log(`Created ${createdTesters.length} tester${createdTesters.length > 1 ? "s" : ""}`);
+            // Step 3: Start simulations (batch) — config resolved from profiles by backend
+            const simItems = createdTesters.map((t) => ({
+                study_id: resolvedStudy,
+                tester_id: t.id,
+                ...(opts.language && { language: opts.language }),
+                ...(opts.locale && { locale: opts.locale }),
+            }));
+            log(`Starting ${simItems.length} simulation${simItems.length > 1 ? "s" : ""}...`);
+            const simResult = await client.post("/simulation/interactive/start/batch", {
+                product_id: resolvedWorkspace,
+                simulations: simItems,
+                platform: resolvedPlatform,
+                ...(resolvedUrl && { url: resolvedUrl }),
+                screen_format: resolvedScreenFormat,
+                ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+            }, { timeout: 60_000 });
+            if (globals.json) {
+                output({
+                    iteration_id: iterationId,
+                    testers: createdTesters.map((t) => ({ id: t.id, profile_name: t.tester_profile?.name })),
+                    simulations: simResult.results,
+                }, true);
+            }
+            else {
+                // Human-readable summary (to stderr — not data)
+                for (let i = 0; i < simResult.results.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 \`speqs 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  $ speqs simulation poll --study <study_id>\n  $ speqs 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);
+                // Get study to find all testers with running/queued simulations
+                const study = await client.get(`/studies/${rid}`);
+                // 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,
+                        });
+                    }
+                }
+                formatSimulationPoll(allTesters, globals.json);
+                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 {
+                outputError(new Error("Provide a job_id argument or --study flag"), globals.json);
+                process.exit(1);
+            }
+        });
+    });
+    // --- Lower-level commands ---
+    sim
+        .command("start")
+        .description("Start a single interactive simulation (low-level)")
+        .requiredOption("--workspace <id>", "Workspace ID")
+        .requiredOption("--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: resolveId(opts.workspace),
+                study_id: resolveId(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)")
+        .requiredOption("--workspace <id>", "Workspace ID")
+        .requiredOption("--study <id>", "Study ID")
+        .requiredOption("--tester <id>", "Tester ID")
+        .option("--config <id>", "Simulation config ID (resolved from profile if omitted)")
+        .option("--max-interactions <n>", "Max interactions")
+        .option("--language <lang>", "Language code")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                product_id: resolveId(opts.workspace),
+                study_id: resolveId(opts.study),
+                tester_id: resolveId(opts.tester),
+                ...(opts.config && { 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 @@
+/**
+ * speqs study — Manage studies.
+ */
+import type { Command } from "commander";
+export declare function registerStudyCommands(program: Command): void;