@ishlabs/cli 0.8.1 → 0.8.2

package/dist/commands/study-tester.js

@@ -0,0 +1,149 @@
+/**
+ * ish study tester — Inspect and manage testers (low-level; usually
+ * created via `ish study run`).
+ *
+ * Default action: `ish study tester <id>` shows tester details and results.
+ */
+import { withClient, readJsonFileOrStdin } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { formatTesterDetail, output } from "../lib/output.js";
+/** Pick the latest iteration on a study (highest order_index, falling back to last). */
+async function latestIterationForStudy(client, studyId) {
+    const study = await client.get(`/studies/${studyId}`);
+    const iterations = study.iterations ?? [];
+    if (iterations.length === 0) {
+        throw new Error(`Study ${studyId} has no iterations. Create one first with \`ish iteration create\`.`);
+    }
+    const sorted = [...iterations].sort((a, b) => (b.order_index ?? 0) - (a.order_index ?? 0));
+    return sorted[0].id;
+}
+/**
+ * Walk a parsed JSON body and resolve any alias-shaped strings (tp-..., i-..., s-...)
+ * appearing in well-known id fields. Pure client-side: avoids a backend round-trip
+ * when the body uses local aliases that the backend wouldn't recognise.
+ */
+const ALIAS_FIELDS = new Set(["tester_profile_id", "iteration_id", "study_id"]);
+const ALIAS_RE = /^(tp|i|s)-[0-9a-f]{3,}$/i;
+function prewalkAliases(value) {
+    if (Array.isArray(value)) {
+        return value.map(prewalkAliases);
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (ALIAS_FIELDS.has(k) && typeof v === "string" && ALIAS_RE.test(v)) {
+                try {
+                    out[k] = resolveId(v);
+                }
+                catch {
+                    out[k] = v;
+                }
+            }
+            else {
+                out[k] = prewalkAliases(v);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+export function attachStudyTesterCommands(study) {
+    const tester = study
+        .command("tester")
+        .description("Inspect or manage testers (low-level; usually created via `study run`)")
+        .argument("[id]", "Tester ID — pass directly to view tester details and results")
+        .addHelpText("after", "\nExamples:\n  $ ish study tester t-d4e                  # show tester details\n  $ ish study tester create --iteration <id> --profile <id>\n  $ ish study tester batch-create --iteration <id> --file testers.json\n  $ ish study tester delete t-d4e")
+        .action(async (id, _opts, cmd) => {
+        if (!id) {
+            cmd.help();
+        }
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/testers/${resolveId(id)}`);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.tester, String(result.id));
+            formatTesterDetail(result, globals.json);
+        });
+    });
+    tester
+        .command("create")
+        .description("Create a tester (low-level)")
+        .option("--iteration <id>", "Iteration ID (or use --study to pick the latest iteration on a study)")
+        .option("--study <id>", "Study ID; resolves to the latest iteration on that study (alternative to --iteration)")
+        .requiredOption("--profile <id>", "Tester profile ID")
+        .option("--language <lang>", "Language code (e.g. en, sv)")
+        .option("--platform <platform>", "Platform (browser, android, figma, code)")
+        .option("--tester-type <type>", "Tester type (ai, human)", "ai")
+        .addHelpText("after", "\nExamples:\n  $ ish study tester create --iteration <id> --profile <id>\n  $ ish study tester create --study s-XXX --profile tp-XXX\n  $ ish study tester create --iteration <id> --profile <id> --platform android --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (!opts.iteration && !opts.study) {
+                throw new Error("Provide --iteration <id> or --study <id> (the latest iteration on that study will be used).");
+            }
+            if (opts.iteration && opts.study) {
+                throw new Error("Pass either --iteration or --study, not both.");
+            }
+            const iterationId = opts.iteration
+                ? resolveId(opts.iteration)
+                : await latestIterationForStudy(client, resolveId(opts.study));
+            const body = {
+                tester_profile_id: resolveId(opts.profile),
+                tester_type: opts.testerType,
+                ...(opts.language && { language: opts.language }),
+                ...(opts.platform && { platform: opts.platform }),
+            };
+            const data = await client.post(`/iterations/${iterationId}/testers`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.tester, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    tester
+        .command("batch-create")
+        .description("Create multiple testers (low-level)")
+        .requiredOption("--iteration <id>", "Iteration ID")
+        .option("--file <path>", "JSON file with testers array (alternative to --profiles)")
+        .option("--profiles <ids>", "Comma-separated profile IDs/aliases; shortcut for --file with one tester per profile (mutually exclusive with --file)")
+        .addHelpText("after", "\nExamples:\n  $ ish study tester batch-create --iteration <id> --file testers.json\n  $ ish study tester batch-create --iteration <id> --profiles tp-eba,tp-289,tp-913\n\n  Expected JSON: [{ \"tester_profile_id\": \"<id>\", \"platform\": \"browser\" }, ...]\n  Profile-id strings inside --file (tester_profile_id, iteration_id, study_id) are resolved client-side via the local alias store before submitting.")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (!opts.file && !opts.profiles) {
+                throw new Error("Provide --file <path> or --profiles <ids>.");
+            }
+            if (opts.file && opts.profiles) {
+                throw new Error("Pass either --file or --profiles, not both.");
+            }
+            const iterationId = resolveId(opts.iteration);
+            let body;
+            if (opts.profiles) {
+                const ids = opts.profiles
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                    .map((s) => resolveId(s));
+                if (ids.length === 0) {
+                    throw new Error("--profiles must contain at least one profile id/alias.");
+                }
+                body = { testers: ids.map((pid) => ({ tester_profile_id: pid, tester_type: "ai" })) };
+            }
+            else {
+                const parsed = await readJsonFileOrStdin(opts.file);
+                body = prewalkAliases(parsed);
+            }
+            const data = await client.post(`/iterations/${iterationId}/testers/batch`, body);
+            output(data, globals.json);
+        });
+    });
+    tester
+        .command("delete")
+        .description("Delete a tester")
+        .argument("<id>", "Tester ID")
+        .addHelpText("after", "\nExamples:\n  $ ish study tester delete <id>")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/testers/${resolveId(id)}`);
+            output({ message: "Tester deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/study.js

@@ -6,10 +6,63 @@ import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
 import { formatStudyList, formatStudyDetail, formatStudyResults, output, ValidationError } from "../lib/output.js";
 import { VALID_CONTENT_TYPES } from "../lib/types.js";
+import { parseAssignment, loadAssignmentsFile, parseQuestion } from "../lib/study-inputs.js";
+import { loadQuestionsManifest } from "../lib/ask-questions.js";
+import { attachStudyRunCommands } from "./study-run.js";
+import { attachStudyTesterCommands } from "./study-tester.js";
+function collectRepeatable(value, prev = []) {
+    return prev.concat([value]);
+}
+function resolveAssignments(opts) {
+    const sources = [];
+    if (opts.assignment && opts.assignment.length > 0)
+        sources.push("--assignment");
+    if (opts.assignmentsFile)
+        sources.push("--assignments-file");
+    if (opts.assignments)
+        sources.push("--assignments");
+    if (sources.length > 1) {
+        throw new Error(`Pass only one of: ${sources.join(", ")}.`);
+    }
+    if (opts.assignment && opts.assignment.length > 0) {
+        return opts.assignment.map(parseAssignment);
+    }
+    if (opts.assignmentsFile) {
+        return loadAssignmentsFile(opts.assignmentsFile);
+    }
+    if (opts.assignments) {
+        try {
+            return JSON.parse(opts.assignments);
+        }
+        catch {
+            throw new Error("Invalid --assignments JSON");
+        }
+    }
+    return undefined;
+}
+function resolveQuestionnaire(opts) {
+    if (opts.question && opts.question.length > 0 && opts.questionnaire) {
+        throw new Error("Pass only one of: --question, --questionnaire.");
+    }
+    if (opts.question && opts.question.length > 0) {
+        return opts.question.map(parseQuestion);
+    }
+    if (opts.questionnaire) {
+        return loadQuestionsManifest(opts.questionnaire);
+    }
+    return undefined;
+}
 export function registerStudyCommands(program) {
     const study = program
         .command("study")
-        .description("Manage studies");
+        .description("Manage and run studies")
+        .addHelpText("after", `
+A study is the persistent research artifact: modality + assignments + questionnaire.
+Iterations carry the URL or media. \`ish study run\` dispatches simulations on the latest iteration.
+
+Concept pages: ish docs get-page concepts/study
+                ish docs get-page concepts/run-verbs
+                ish docs get-page concepts/assignment`);
     study
         .command("list")
         .description("List studies for a workspace")
@@ -23,69 +76,68 @@ export function registerStudyCommands(program) {
     });
     study
         .command("create")
-        .description("Create a new study")
+        .description("Create a new study (the persistent shape: modality, tasks, questionnaire)")
         .option("--workspace <id>", "Workspace ID")
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document)")
         .option("--content-type <type>", "Content type (varies by modality — see examples below)")
-        .option("--assignments <json>", "JSON array of assignments, e.g. '[{\"name\":\"Task\",\"instructions\":\"Do something\"}]'")
-        .option("--questions <json>", "JSON array of interview questions, e.g. '[{\"question\":\"How was it?\",\"type\":\"text\",\"timing\":\"after\"}]'")
+        .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
+        .option("--assignments-file <path>", "JSON file with assignments array")
+        .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
+        .option("--question <text>", "Add a text question to the questionnaire (repeatable; type=text, timing=after)", collectRepeatable, [])
+        .option("--questionnaire <path>", "JSON file defining the questionnaire (supports text, slider, likert, single-choice, multiple-choice, number; timing=before|after)")
         .addHelpText("after", `
 Note: --workspace is optional if set via \`ish workspace use <alias>\`.
 
+The questionnaire is the set of questions testers answer. Use \`--question\` to
+quickly add simple text questions, or \`--questionnaire <file.json>\` for richer
+types (slider, likert, choice) and custom timing. The two forms are mutually
+exclusive — pick one.
+
 Examples:
-  # Interactive study:
+  # Interactive study with one assignment and a single-question questionnaire:
   $ ish study create --name "Onboarding UX" --modality interactive \\
-    --assignments '[{"name":"Sign up","instructions":"Complete the signup flow"}]'
+      --assignment "Sign up:Complete the signup flow" \\
+      --question "How easy was it?"
 
-  # Text/email study:
-  $ ish study create --name "Newsletter" --modality text --content-type email \\
-    --assignments '[{"name":"Read","instructions":"Read this email naturally"}]'
+  # Multiple assignments + a richer questionnaire from a file:
+  $ ish study create --name "Checkout" --modality interactive \\
+      --assignment "Browse:Find a product you like" \\
+      --assignment "Buy:Add to cart and checkout" \\
+      --questionnaire ./questionnaire.json
 
-  # Audio conversation study:
-  $ ish study create --name "Episode Review" --modality audio --content-type conversation \\
-    --assignments '[{"name":"Listen","instructions":"Listen and react naturally"}]'
+  # Text/email study, all assignments from a file:
+  $ ish study create --name "Newsletter" --modality text --content-type email \\
+      --assignments-file ./assignments.json
 
-  # Video ad study:
+  # Video ad study with a quick two-question questionnaire:
   $ ish study create --name "Product Ad" --modality video --content-type ad \\
-    --assignments '[{"name":"Watch","instructions":"Watch this ad and share your reaction"}]'
-
-  # Image social post study:
-  $ ish study create --name "Instagram Post" --modality image --content-type social_post \\
-    --assignments '[{"name":"View","instructions":"Look at this post naturally"}]'
+      --assignment "Watch:Watch this ad and share your reaction" \\
+      --question "What stuck with you?" \\
+      --question "Would you click through?"
 
-  # With interview questions:
-  $ ish study create --name "Checkout" --modality interactive \\
-    --assignments '[{"name":"Buy","instructions":"Add to cart and checkout"}]' \\
-    --questions '[{"question":"How easy was it?","type":"slider","timing":"after","min":0,"max":10}]'
+  # Sample questionnaire.json (full InterviewQuestion shape):
+  #   [
+  #     { "question": "How easy?", "type": "slider", "timing": "after",
+  #       "min": 0, "max": 10 },
+  #     { "question": "Which fits best?", "type": "single-choice",
+  #       "options": ["A","B","C"] }
+  #   ]
 
 Content types by modality:
   text:     narrative, informational, commercial, editorial, reference, email, news
   video:    tutorial, documentary, entertainment, review, lifestyle, news, social_post, ad
   audio:    music, narration, conversation, speech, soundscape, news, ad
   image:    product, photography, infographic, artwork, interface, social_post, ad
-  document: deck, presentation, report, brochure, guide`)
+  document: deck, presentation, report, brochure, guide
+
+Next: configure a run with \`ish iteration create --study <id>\`,
+      then dispatch with \`ish study run\`.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            let assignments;
-            let interviewQuestions;
-            if (opts.assignments) {
-                try {
-                    assignments = JSON.parse(opts.assignments);
-                }
-                catch {
-                    throw new Error("Invalid --assignments JSON");
-                }
-            }
-            if (opts.questions) {
-                try {
-                    interviewQuestions = JSON.parse(opts.questions);
-                }
-                catch {
-                    throw new Error("Invalid --questions JSON");
-                }
-            }
+            const assignments = resolveAssignments(opts);
+            const interviewQuestions = resolveQuestionnaire(opts);
             // Validate content_type against modality
             if (opts.contentType && opts.modality) {
                 const validTypes = VALID_CONTENT_TYPES[opts.modality];
@@ -112,7 +164,7 @@ Content types by modality:
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
-            formatStudyDetail(result, globals.json);
+            formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
                 console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
@@ -133,11 +185,11 @@ Content types by modality:
                 ...(opts.targetUrl && { target_url: opts.targetUrl }),
             };
             const resolvedWs = resolveWorkspace(opts.workspace);
-            const data = await client.post(`/products/${resolvedWs}/studies/generate`, body);
+            const data = await client.post(`/products/${resolvedWs}/studies/generate`, body, { timeout: 120_000 });
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
-            formatStudyDetail(result, globals.json);
+            formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
                 console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
@@ -165,9 +217,31 @@ Content types by modality:
     });
     study
         .command("results")
-        .description("View aggregated results (sentiment, interview answers)")
+        .description("View aggregated results: tester counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
         .argument("<id>", "Study ID")
-        .addHelpText("after", "\nExamples:\n  $ ish study results <id>\n  $ ish study results <id> --json")
+        .addHelpText("after", `
+Examples:
+  $ ish study results <id>
+  $ ish study results <id> --json
+
+Example response (--json):
+  {
+    "study_id": "<uuid>",
+    "alias": "s-...",
+    "name": "...",
+    "tester_count": 12,
+    "completed_count": 8,
+    "errored_count": 0,
+    "total_interactions": 142,
+    "sentiment": { "Satisfied": 5, "Frustrated": 2, "Neutral": 1 },
+    "interview_answers": [
+      { "question_id": "...", "question": "...", "type": "text",
+        "answers": [ { "tester_id": "...", "tester_alias": "t-...", "answer": "..." } ] }
+    ],
+    "testers": [ { "id": "...", "alias": "t-...", "name": "...", "status": "completed", "interaction_count": 12 } ]
+  }
+
+When no runs have completed, the same envelope is returned with zero counts and empty arrays.`)
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const rid = resolveId(id);
@@ -188,29 +262,27 @@ Content types by modality:
         .option("--status <status>", "Study status (draft, running, completed)")
         .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document)")
         .option("--content-type <type>", "Content type")
-        .option("--assignments <json>", "JSON array of assignments, e.g. '[{\"name\":\"Task\",\"instructions\":\"Do something\"}]'")
-        .option("--questions <json>", "JSON array of interview questions")
-        .addHelpText("after", "\nExamples:\n  $ ish study update <id> --name \"Updated Name\"\n  $ ish study update <id> --status running --json")
+        .option("--assignment <name:instructions>", "Replace all assignments with these (repeatable)", collectRepeatable, [])
+        .option("--assignments-file <path>", "JSON file with assignments array")
+        .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
+        .option("--question <text>", "Replace the questionnaire with these text questions (repeatable)", collectRepeatable, [])
+        .option("--questionnaire <path>", "Replace the questionnaire from a JSON file (full InterviewQuestion shape)")
+        .addHelpText("after", `
+Replacing the questionnaire: pass either \`--question\` (one or more text
+questions) or \`--questionnaire <file.json>\` (full shape: slider, likert,
+choice, custom timing). The two are mutually exclusive.
+
+Examples:
+  $ ish study update <id> --name "Updated Name"
+  $ ish study update <id> --status running --json
+  $ ish study update <id> --assignment "Sign up:Complete the signup flow" \\
+      --question "How easy was it?"
+  $ ish study update <id> --questionnaire ./questionnaire.json
+  $ ish study update <id> --assignments-file ./assignments.json`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            let assignments;
-            let interviewQuestions;
-            if (opts.assignments) {
-                try {
-                    assignments = JSON.parse(opts.assignments);
-                }
-                catch {
-                    throw new Error("Invalid --assignments JSON");
-                }
-            }
-            if (opts.questions) {
-                try {
-                    interviewQuestions = JSON.parse(opts.questions);
-                }
-                catch {
-                    throw new Error("Invalid --questions JSON");
-                }
-            }
+            const assignments = resolveAssignments(opts);
+            const interviewQuestions = resolveQuestionnaire(opts);
             if (opts.contentType && opts.modality) {
                 const validTypes = VALID_CONTENT_TYPES[opts.modality];
                 if (validTypes && !validTypes.includes(opts.contentType)) {
@@ -240,7 +312,7 @@ Content types by modality:
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
-            formatStudyDetail(result, globals.json);
+            formatStudyDetail(result, globals.json, { writePath: true });
         });
     });
     study
@@ -250,8 +322,9 @@ Content types by modality:
         .addHelpText("after", "\nExamples:\n  $ ish study delete <id>")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            await client.del(`/studies/${resolveId(id)}`);
-            output({ message: "Study deleted" }, globals.json);
+            const rid = resolveId(id);
+            await client.del(`/studies/${rid}`);
+            output({ id: rid, alias: tagAlias(ALIAS_PREFIX.study, rid), message: "Study deleted" }, globals.json, { writePath: true });
         });
     });
     study
@@ -280,4 +353,6 @@ Content types by modality:
             console.error(`Active study set to "${data.name || rid}".`);
         });
     });
+    attachStudyRunCommands(study);
+    attachStudyTesterCommands(study);
 }