@ishlabs/cli 0.12.2 → 0.14.0

package/dist/commands/study-analyze.js

@@ -0,0 +1,187 @@
+/**
+ * ish study analyze / ish study insights — AI summary + key insights for a
+ * study.
+ *
+ * Wraps three backend endpoints already shipped server-side and used by the
+ * web overview page:
+ *
+ *   POST /studies/{id}/analysis  — kick off an analysis run
+ *   GET  /studies/{id}/results   — list runs for a study (newest first)
+ *   GET  /study-results/{id}     — fetch one run
+ *
+ * Status state machine: pending → running → (completed | failed). Polling
+ * mirrors the FE behaviour (5s here vs 15s in the FE — agents care more
+ * about latency than load).
+ */
+import { withClient, resolveStudy, parseWaitTimeout } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, printTable } from "../lib/output.js";
+import { WaitTimeoutError } from "./study-run.js";
+const POLL_INTERVAL_MS = 5_000;
+const ANALYSIS_TERMINAL_STATUSES = new Set(["completed", "failed"]);
+async function pollAnalysisUntilDone(client, opts) {
+    const start = Date.now();
+    let lastReported = "";
+    while (true) {
+        const result = await client.get(`/study-results/${opts.resultId}`, undefined, { timeout: 60_000 });
+        if (!opts.quiet) {
+            const line = result.progress_message
+                ? `${result.status}: ${result.progress_message}`
+                : result.status;
+            if (line !== lastReported) {
+                process.stderr.write(`  ${line}\n`);
+                lastReported = line;
+            }
+        }
+        if (ANALYSIS_TERMINAL_STATUSES.has(result.status)) {
+            return result;
+        }
+        if (Date.now() - start > opts.timeoutMs) {
+            throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for analysis. ` +
+                `Status: ${result.status}. Run \`ish study insights ${opts.studyId}\` to check later.`, {
+                study_id: opts.studyId,
+                timeout_seconds: Math.round(opts.timeoutMs / 1000),
+                done: 0,
+                total: 1,
+                pending: 1,
+                rows: [],
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+}
+function formatKeyInsightsTable(insights) {
+    printTable(["#", "CATEGORY", "TESTERS", "TITLE"], insights
+        .filter((i) => !i.is_discarded)
+        .map((i) => [
+        String(i.sequence),
+        i.category,
+        String(i.tester_count),
+        i.title,
+    ]));
+}
+function formatStudyAnalysis(result) {
+    const header = `Analysis ${result.id} — ${result.status}`;
+    console.log(header);
+    if (result.started_at)
+        console.log(`  started_at: ${result.started_at}`);
+    if (result.progress_message)
+        console.log(`  progress: ${result.progress_message}`);
+    if (result.error_message)
+        console.log(`  error: ${result.error_message}`);
+    if (result.summary) {
+        console.log(`\nSummary:\n${result.summary}`);
+    }
+    if (result.key_insights && result.key_insights.length > 0) {
+        console.log("\nKey insights:");
+        formatKeyInsightsTable(result.key_insights);
+    }
+}
+export function attachStudyAnalyzeCommands(study) {
+    study
+        .command("analyze")
+        .description("Trigger an AI summary + key-insights analysis for a study. " +
+        "First analysis per study is free; subsequent runs cost 10 credits.")
+        .argument("[id]", "Study ID (defaults to active study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .option("--wait", "Poll until the run reaches completed or failed")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300; only with --wait)")
+        .addHelpText("after", `
+Examples:
+  $ ish study analyze                              # uses active study
+  $ ish study analyze <study-id>
+  $ ish study analyze <study-id> --wait
+  $ ish study analyze <study-id> --wait --timeout 600 --json
+
+Prerequisites (enforced server-side):
+  - Study modality is one of: interactive, video, audio, text, image, document
+  - At least 5 testers with completed interactions
+
+Read prior runs:
+  $ ish study insights <study-id>`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const studyId = resolveStudy(id);
+            const initial = await client.post(`/studies/${studyId}/analysis`);
+            if (!opts.wait) {
+                if (globals.json) {
+                    output(initial, true);
+                }
+                else {
+                    formatStudyAnalysis(initial);
+                    console.error(`\n  Run \`ish study insights ${studyId}\` to read the result once it completes,\n  or rerun with --wait to block.`);
+                }
+                return;
+            }
+            const timeoutMs = parseWaitTimeout(opts.timeout, 300_000);
+            const final = await pollAnalysisUntilDone(client, {
+                resultId: initial.id,
+                studyId,
+                timeoutMs,
+                quiet: globals.json,
+            });
+            if (globals.json) {
+                output(final, true);
+            }
+            else {
+                formatStudyAnalysis(final);
+            }
+        });
+    });
+    study
+        .command("insights")
+        .description("Read AI-generated insights from prior `ish study analyze` runs (newest first).")
+        .argument("[id]", "Study ID (defaults to active study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .option("--all", "Show every prior run as a compact table (default: latest only)")
+        .option("--result <id>", "Fetch a specific result by id rather than the latest")
+        .addHelpText("after", `
+Examples:
+  $ ish study insights                             # latest run for active study
+  $ ish study insights <study-id>
+  $ ish study insights <study-id> --all
+  $ ish study insights <study-id> --json
+  $ ish study insights <study-id> --result <result-id>
+
+Trigger a new run with \`ish study analyze --wait\`.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (opts.result) {
+                const single = await client.get(`/study-results/${resolveId(opts.result)}`);
+                if (globals.json) {
+                    output(single, true);
+                }
+                else {
+                    formatStudyAnalysis(single);
+                }
+                return;
+            }
+            const studyId = resolveStudy(id);
+            const history = await client.get(`/studies/${studyId}/results`);
+            const latest = history[0] ?? null;
+            if (globals.json) {
+                output({ latest, history }, true);
+                return;
+            }
+            if (!latest) {
+                console.log("No analysis runs yet. Trigger one with `ish study analyze`.");
+                return;
+            }
+            if (opts.all) {
+                console.log(`Analysis history for study ${studyId}:`);
+                printTable(["#", "ID", "STATUS", "STARTED", "INSIGHTS"], history.map((r, idx) => [
+                    String(history.length - idx),
+                    r.id,
+                    r.status,
+                    r.started_at ?? r.created_at,
+                    String((r.key_insights ?? []).length),
+                ]));
+                return;
+            }
+            formatStudyAnalysis(latest);
+            if (history.length > 1) {
+                console.error(`\n  ${history.length - 1} prior run${history.length - 1 === 1 ? "" : "s"} — pass --all to list.`);
+            }
+        });
+    });
+}