@ishlabs/cli 0.19.0 → 0.21.0

package/dist/commands/study.js

@@ -3,10 +3,12 @@
  */
 import { readFileSync } from "node:fs";
 import { Option } from "commander";
-import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive, readFileOrStdin } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive, readFileOrStdin, collectIds } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
-import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsSummary, buildChatTranscript, output, ValidationError, } from "../lib/output.js";
+import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsEnvelope, buildStudyResultsSummary, buildChatTranscript, formatStudyResultsGroupBy, output, ValidationError, } from "../lib/output.js";
+import { applyResultsFilters } from "../lib/study-results-filters.js";
+import { buildStudyResultsPerIteration, buildStudyResultsPerFrame, buildStudyResultsPerSegment, buildStudyResultsPerTurn, buildStudyResultsPerAssignment, buildStudyResultsPerStep, } from "../lib/study-results-projections.js";
 import { VALID_CONTENT_TYPES } from "../lib/types.js";
 import { fetchStudyParticipants } from "../lib/study-participants.js";
 import { parseAssignment, loadAssignmentsFile, validateAssignmentsArray, parseQuestion } from "../lib/study-inputs.js";
@@ -544,8 +546,18 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             const data = await client.post(`/products/${resolvedWs}/studies`, body);
             if (data.id) {
                 const config = loadConfig();
+                const prevStudy = config.study;
                 config.study = data.id;
                 saveConfig(config);
+                // Auto-activating the new study is intentional ergonomics (the
+                // common next step is `ish iteration create --study <new>`), but
+                // it was previously silent — surprised users who had set a
+                // different active study just before (ISSUE-030). Always
+                // surface the side-effect on stderr.
+                if (!globals.json) {
+                    const verb = prevStudy && prevStudy !== data.id ? "replaced" : "set";
+                    console.error(`Active study ${verb} to "${data.name || data.id}".`);
+                }
             }
             const result = data;
             if (result.id)
@@ -659,22 +671,41 @@ list table layout in human mode.`)
     });
     study
         .command("results")
-        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
+        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed. Slice with filter flags (--frame, --segment, --turn, --side, --assignment, --step, --sentiment, --actor, --iteration, --participant) or project with --group-by (iteration|frame|segment|turn|assignment|step).")
         .argument("<id>", "Study ID")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
-        .option("--summary", "Lean summary projection: counts + sentiment + per-participant {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns.")
+        .option("--summary", "Lean summary projection: counts + sentiment + per-participant {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns. Composes with filters: `--summary --frame login` narrows the summary to the login-screen interactions.")
         // PC-N4: agents reach for `--summarize` (verb) by analogy with the MCP
         // `summarize` action; accept it as a hidden alias of --summary so the
         // canonical flag stays the documented one but the muscle-memory variant
         // works without a round-trip.
         .addOption(new Option("--summarize", "Hidden alias for --summary").hideHelp())
-        .option("--transcript <participant_id>", "Chat transcript projection for one participant: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape.")
+        .option("--transcript <participant_id>", "Chat transcript projection for one participant: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape. Cannot combine with filters or --group-by (transcript is a single-participant projection).")
+        // --- Slice / projection flags (T5) ---
+        .option("--frame <ref>", "Filter to interactions whose Frame name contains <ref> (case-insensitive), or whose Frame UUID / `f-…` alias / frame_version_id matches. Interactive only — warned and ignored on other modalities.")
+        .option("--segment <ref>", "Filter media studies (video/audio/text/document) by segment index (integer) or segment label (substring). Image and other modalities: warned and ignored.")
+        .option("--turn <n>", "Filter chat interactions to a single `actions[0].data.turn_index`. Non-chat modalities: warned and ignored.")
+        .option("--side <a|b>", "Filter participant_pair chat interactions by assignment side. Other modalities: warned and ignored.")
+        .option("--assignment <ref>", "Filter to a single assignment by UUID or name (substring, case-insensitive).")
+        .option("--step <ref>", "Filter `participant_assignments[].step_results[]` to a single step by step-id or name (substring). Pair with --include-evidence to also drop non-evidence interactions.")
+        .option("--sentiment <labels>", "Filter to interactions whose sentiment.label is in the comma-separated list (case-insensitive; repeatable). Drops null-sentiment rows.", collectIds, [])
+        .option("--actor <actor>", "Filter to interactions whose actor is `ai`, `human`, or `user` (case-insensitive).")
+        .option("--iteration <ref>", "Restrict to a single iteration by UUID or label.")
+        .option("--participant <ref>", "Restrict to a single participant by UUID or `pt-…` alias.")
+        .option("--include-unmatched", "When --frame is set, keep interactions with null frame_version_id under a synthetic `_unmatched` bucket instead of dropping them.")
+        .option("--include-evidence", "When --step is set, also drop interactions not listed in any surviving step_results[].evidence_interaction_ids[].")
+        .option("--group-by <axis>", "Project results into per-axis slices: iteration | frame | segment | turn | assignment | step. Mutually exclusive with --summary and --transcript.")
         .addHelpText("after", `
 Examples:
   $ ish study results <id>
   $ ish study results <id> --json
   $ ish study results <id> --summary --json
   $ ish study results <id> --transcript pt-d4e --json
+  # Slice (filters compose: AND across flags, OR within --sentiment)
+  $ ish study results <id> --frame login --group-by iteration
+  $ ish study results <id> --segment 3 --sentiment Frustrated
+  $ ish study results <id> --assignment "Sign up" --step verify-email --group-by step
+  $ ish study results <id> --side a --turn 4
 
 Default --json envelope (M10: per-answer sentiment now included):
   {
@@ -697,6 +728,11 @@ Default --json envelope (M10: per-answer sentiment now included):
     ]
   }
 
+When any filter flag is passed, the envelope gains a \`totals_unfiltered\` field
+({ participant_count, interaction_count }) so callers can sanity-check coverage
+("matched 12 / 80 participants"). A zero-match filter returns the stable
+envelope with participant_count=0 and exit code 0 (not 4).
+
 --summary projection (M2-friction-7: drops the interview_answers payload):
   { study, participant_count, completed_count, failed_count, sentiment, participants: [...] }
 
@@ -713,6 +749,24 @@ Default --json envelope (M10: per-answer sentiment now included):
     "participant_summary": { "comment": "...", "sentiment": {...} }
   }
 
+--group-by iteration projection:
+  { study, slices: [{ iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions }, ...], totals_unfiltered, warnings }
+
+--group-by frame projection (interactive only):
+  [{ frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases }, ...]
+
+--group-by segment projection (video/audio/text/document):
+  [{ segment_index, segment_label, interaction_count, sentiment_histogram, engagement_histogram, sample_comments }, ...]
+
+--group-by turn projection (chat only):
+  [{ turn_index, interaction_count, sentiment_histogram, sample_replies, failures }, ...]
+
+--group-by assignment projection:
+  [{ assignment_id, assignment_name, interaction_count, sentiment_histogram, step_completion }, ...]
+
+--group-by step projection:
+  [{ assignment_id, assignment_name, step_id, step_name, total, passed, inconclusive, failed, rate, participant_verdicts: [{ participant_alias, verdict, reason, evidence_interaction_ids }, ...] }, ...]
+
 Tips:
   Use \`--get <path>\` for a single value (e.g. \`--get participant_count\`),
   \`--fields a,b,c\` to project the JSON output further.
@@ -731,6 +785,7 @@ Common --get paths (default envelope):
   --get interview_answers                       # full per-question payload
   --get interview_answers.0.question            # text of the first question
   --get interview_answers.0.answers.0.answer    # first answer to the first question
+  --get totals_unfiltered.participant_count          # pre-filter participant count (when slicing)
 
 Common --get paths (--transcript <participant_id> envelope):
   --get transcript                              # full role/text/turn array
@@ -739,6 +794,18 @@ Common --get paths (--transcript <participant_id> envelope):
   --get participant_summary.sentiment                # aggregate sentiment map
   --get unique_bot_replies                      # bot-side message count
 
+Common --get paths (--group-by projections):
+  --get slices.iteration_label                       # per-iteration: one label per line
+  --get slices.0.participant_count                   # per-iteration: first slice's count
+  --get 0.frame_label                                # per-frame: first frame's label
+  --get 0.sentiment_histogram                        # per-frame/segment/turn: first slice's sentiment map
+  --get 0.segment_index                              # per-segment: first segment's index
+  --get 0.turn_index                                 # per-turn: first turn's index
+  --get 0.assignment_name                            # per-assignment/step: first slice's assignment
+  --get 0.step_name                                  # per-step: first slice's step
+  --get 0.rate                                       # per-step: first step's pass-rate
+  --get 0.participant_verdicts.verdict               # per-step: verdict per participant
+
 When no runs have completed, the default envelope is returned with zero counts and empty arrays.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -746,10 +813,76 @@ When no runs have completed, the default envelope is returned with zero counts a
             // into a single boolean before validation so the rest of the
             // handler reads only `summary`.
             const wantsSummary = !!(opts.summary || opts.summarize);
+            // T5: detect whether any filter flag was passed. Interaction-level
+            // and participant-level flags both count — they all narrow the
+            // result set. `--include-unmatched`/`--include-evidence` are
+            // modifiers that only make sense alongside --frame/--step but
+            // count as "filter intent" for the transcript/conflict check.
+            const hasFilter = opts.frame !== undefined ||
+                opts.segment !== undefined ||
+                opts.turn !== undefined ||
+                opts.side !== undefined ||
+                opts.assignment !== undefined ||
+                opts.step !== undefined ||
+                (opts.sentiment !== undefined && opts.sentiment.length > 0) ||
+                opts.actor !== undefined ||
+                opts.iteration !== undefined ||
+                opts.participant !== undefined ||
+                opts.includeUnmatched === true ||
+                opts.includeEvidence === true;
+            const hasGroupBy = opts.groupBy !== undefined;
+            // --- Conflict validation (no IO yet) ---
             if (wantsSummary && opts.transcript) {
                 throw new ValidationError("Pass only one of: --summary, --transcript.", ["--summary", "--transcript"]);
             }
+            if (opts.transcript && (hasFilter || hasGroupBy)) {
+                // --transcript is a single-participant chat projection — slicing
+                // doesn't make sense.
+                throw new ValidationError("--transcript is a single-participant projection; cannot combine with filter flags or --group-by.", ["--transcript"]);
+            }
+            if (wantsSummary && hasGroupBy) {
+                throw new ValidationError("Pass only one of: --summary, --group-by.", ["--summary", "--group-by"]);
+            }
+            // --side validation: must be exactly "a" or "b" (case-insensitive).
+            const sideNormalised = opts.side ? opts.side.toLowerCase() : undefined;
+            if (sideNormalised !== undefined && sideNormalised !== "a" && sideNormalised !== "b") {
+                throw new ValidationError(`--side must be "a" or "b", got "${opts.side}".`, ["a", "b"]);
+            }
+            // --actor validation: must be one of ai|human|user (case-insensitive).
+            const actorNormalised = opts.actor ? opts.actor.toLowerCase() : undefined;
+            if (actorNormalised !== undefined &&
+                actorNormalised !== "ai" &&
+                actorNormalised !== "human" &&
+                actorNormalised !== "user") {
+                throw new ValidationError(`--actor must be "ai", "human", or "user", got "${opts.actor}".`, ["ai", "human", "user"]);
+            }
+            // --turn validation: must parse as a non-negative integer.
+            let turnNum;
+            if (opts.turn !== undefined) {
+                const n = parseInt(opts.turn, 10);
+                if (Number.isNaN(n) || n < 0 || String(n) !== opts.turn.trim()) {
+                    throw new ValidationError(`--turn must be a non-negative integer, got "${opts.turn}".`, []);
+                }
+                turnNum = n;
+            }
+            // --group-by axis whitelist.
+            const VALID_GROUP_BY = [
+                "iteration",
+                "frame",
+                "segment",
+                "turn",
+                "assignment",
+                "step",
+            ];
+            let groupByKind;
+            if (opts.groupBy !== undefined) {
+                if (!VALID_GROUP_BY.includes(opts.groupBy)) {
+                    throw new ValidationError(`--group-by must be one of: ${VALID_GROUP_BY.join(", ")}. Got "${opts.groupBy}".`, VALID_GROUP_BY);
+                }
+                groupByKind = opts.groupBy;
+            }
             const rid = resolveId(id);
+            // --- --transcript fast path (no fetch of study payload) ---
             if (opts.transcript) {
                 // --transcript <participant_id>: bypass the study aggregator; fetch
                 // the named participant directly. Cheaper (one GET, no nested
@@ -759,20 +892,134 @@ When no runs have completed, the default envelope is returned with zero counts a
                 output(buildChatTranscript(participant), globals.json, { preProjected: true });
                 return;
             }
-            const [data, participants] = await Promise.all([
+            // --- Default-fast path: no filter, no group-by ---
+            if (!hasFilter && !hasGroupBy) {
+                const [data, participants] = await Promise.all([
+                    client.get(`/studies/${rid}`),
+                    fetchStudyParticipants(client, rid),
+                ]);
+                if (wantsSummary) {
+                    output(buildStudyResultsSummary(data, participants), globals.json, { preProjected: true });
+                }
+                else {
+                    formatStudyResults(data, participants, globals.json);
+                }
+                if (!globals.json && data.product_id) {
+                    const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                    console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                }
+                return;
+            }
+            // --- Slice / projection path: fetch in parallel, then filter+project ---
+            //
+            // Modality gating for --group-by happens AFTER the study fetch
+            // (we need study.modality), but BEFORE any further work — see the
+            // post-fetch validation block below. Pre-fetch validation above is
+            // limited to checks that don't need wire data.
+            const fetchFrames = opts.frame !== undefined;
+            const [study, participants, framesPayload] = await Promise.all([
                 client.get(`/studies/${rid}`),
                 fetchStudyParticipants(client, rid),
+                fetchFrames
+                    ? client.get(`/studies/${rid}/frames`)
+                    : Promise.resolve([]),
             ]);
-            if (wantsSummary) {
-                output(buildStudyResultsSummary(data, participants), globals.json, { preProjected: true });
+            const studyRec = study;
+            const modality = typeof studyRec.modality === "string" ? studyRec.modality : "unknown";
+            // Modality gating for --group-by — router-level, NOT projection-level
+            // (devon's T7 note: projection builders are intentionally
+            // modality-agnostic and bucket non-matching rows into `_unmatched`;
+            // the surface is responsible for refusing nonsensical axes up front).
+            if (groupByKind === "frame" && modality !== "interactive") {
+                throw new ValidationError(`--group-by frame requires modality=interactive; this study is "${modality}".`, ["interactive"]);
             }
-            else {
-                formatStudyResults(data, participants, globals.json);
+            const SEGMENT_MODALITIES = ["video", "audio", "text", "document"];
+            if (groupByKind === "segment" && !SEGMENT_MODALITIES.includes(modality)) {
+                throw new ValidationError(`--group-by segment requires modality ∈ {${SEGMENT_MODALITIES.join(", ")}}; this study is "${modality}".`, SEGMENT_MODALITIES);
             }
-            if (!globals.json && data.product_id) {
-                const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
-                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            if (groupByKind === "turn" && modality !== "chat") {
+                throw new ValidationError(`--group-by turn requires modality=chat; this study is "${modality}".`, ["chat"]);
+            }
+            // Coerce the frames payload to a plain array of records (the API
+            // returns a bare array). Tolerate `{items: [...]}` shape in case the
+            // endpoint ever normalises.
+            const rawFrames = Array.isArray(framesPayload)
+                ? framesPayload
+                : Array.isArray(framesPayload?.items)
+                    ? (framesPayload.items)
+                    : [];
+            const filters = {
+                frame: opts.frame,
+                segment: opts.segment,
+                turn: turnNum,
+                side: sideNormalised,
+                assignment: opts.assignment,
+                step: opts.step,
+                sentiment: opts.sentiment && opts.sentiment.length > 0 ? opts.sentiment : undefined,
+                actor: actorNormalised,
+                iteration: opts.iteration,
+                participant: opts.participant,
+                includeUnmatched: opts.includeUnmatched === true ? true : undefined,
+                includeEvidence: opts.includeEvidence === true ? true : undefined,
+            };
+            const filtered = applyResultsFilters(studyRec, participants, rawFrames, filters);
+            // Surface modality-mismatch warnings (and any other diagnostics from
+            // applyResultsFilters) on stderr so JSON output stays clean. The
+            // filter pipeline downgrades mismatched flags to no-ops; the warnings
+            // tell the agent which flags were ignored and why.
+            if (filtered.warnings.length > 0 && !globals.quiet) {
+                for (const w of filtered.warnings) {
+                    console.error(`warning: ${w}`);
+                }
+            }
+            // --- Dispatch: --group-by projection > --summary on filtered > filtered envelope ---
+            if (groupByKind !== undefined) {
+                let projection;
+                switch (groupByKind) {
+                    case "iteration":
+                        projection = buildStudyResultsPerIteration(filtered);
+                        break;
+                    case "frame":
+                        projection = buildStudyResultsPerFrame(filtered);
+                        break;
+                    case "segment":
+                        projection = buildStudyResultsPerSegment(filtered);
+                        break;
+                    case "turn":
+                        projection = buildStudyResultsPerTurn(filtered);
+                        break;
+                    case "assignment":
+                        projection = buildStudyResultsPerAssignment(filtered);
+                        break;
+                    case "step":
+                        projection = buildStudyResultsPerStep(filtered);
+                        break;
+                }
+                formatStudyResultsGroupBy(projection, groupByKind, globals.json);
+                return;
+            }
+            if (wantsSummary) {
+                // --summary on filtered participants: narrowed summary projection.
+                // Attach totals_unfiltered so callers can still see the pre-filter
+                // denominator (e.g. "12 / 80 participants matched").
+                const summary = buildStudyResultsSummary(filtered.study, filtered.participants);
+                const summaryOut = {
+                    ...summary,
+                    totals_unfiltered: filtered.totals_unfiltered,
+                };
+                output(summaryOut, globals.json, { preProjected: true });
+                return;
             }
+            // Default (no --group-by, no --summary) but filters set: stable
+            // envelope on the filtered participants + totals_unfiltered. Empty
+            // slice contract: zero matches yields participant_count=0 and exit
+            // 0, never a 4/not-found.
+            const envelope = buildStudyResultsEnvelope(filtered.study, filtered.participants);
+            const envelopeOut = {
+                ...envelope,
+                totals_unfiltered: filtered.totals_unfiltered,
+            };
+            output(envelopeOut, globals.json, { preProjected: true });
         });
     });
     study
@@ -856,6 +1103,15 @@ checklists ("steps") ride along when present in the JSON forms
                 json: globals.json,
             });
             await client.del(`/studies/${rid}`);
+            // If the deleted study was active, clear it (Pattern A — parallel to
+            // ask delete and chat endpoint delete which already do this).
+            const config = loadConfig();
+            if (config.study === rid) {
+                delete config.study;
+                saveConfig(config);
+                if (!globals.json)
+                    console.error("(Cleared active study.)");
+            }
             output({ id: rid, alias: tagAlias(ALIAS_PREFIX.study, rid), message: "Study deleted" }, globals.json, { writePath: true });
         });
     });

package/dist/commands/workspace.js

@@ -1,7 +1,7 @@
 /**
  * ish workspace — Manage workspaces (API: /products).
  */
-import { withClient, getWebUrl, terminalLink, resolveWorkspace } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
 import { formatWorkspaceList, formatWorkspaceDetail, formatSiteAccessStatus, output } from "../lib/output.js";
@@ -134,13 +134,35 @@ existing workspace was returned. On creation, \`reused: false\`.`)
     });
     workspace
         .command("delete")
-        .description("Delete a workspace")
+        .description("Delete a workspace (and ALL nested studies, asks, people, secrets, configs, sources, chat endpoints)")
         .argument("<id>", "Workspace ID")
-        .addHelpText("after", "\nExamples:\n  $ ish workspace delete <id>")
-        .action(async (id, _opts, cmd) => {
+        .option("-y, --yes", "Skip confirmation prompt (required in --json or non-TTY contexts)")
+        .addHelpText("after", `
+Deleting a workspace is the highest-blast-radius destructive op in the CLI:
+it removes ALL nested studies, asks, people, secrets, configs, sources, and
+chat endpoints. This cannot be undone.
+
+Examples:
+  $ ish workspace delete <id>             # interactive — prompts for confirmation
+  $ ish workspace delete <id> --yes       # non-interactive
+  $ ish workspace delete <id> --json --yes`)
+        .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const rid = resolveId(id);
+            await confirmDestructive(`Delete workspace ${tagAlias(ALIAS_PREFIX.workspace, rid)}? This will delete ALL nested studies, asks, people, secrets, configs, sources, and chat endpoints. This cannot be undone.`, { yes: opts.yes, json: globals.json });
             await client.del(`/products/${rid}`);
+            // If the deleted workspace was active, clear it + its scoped children
+            // so subsequent commands don't render orphan refs (Pattern A).
+            const config = loadConfig();
+            if (config.workspace === rid) {
+                delete config.workspace;
+                delete config.study;
+                delete config.ask;
+                delete config.chat_endpoint;
+                saveConfig(config);
+                if (!globals.json)
+                    console.error("(Cleared active workspace + study / ask / chat endpoint.)");
+            }
             output({ id: rid, alias: tagAlias(ALIAS_PREFIX.workspace, rid), message: "Workspace deleted" }, globals.json, { writePath: true });
         });
     });
@@ -187,9 +209,12 @@ Examples:
         if (opts.clear) {
             const config = loadConfig();
             delete config.workspace;
+            // workspace-scoped children: clearing the workspace orphans them all.
             delete config.study;
+            delete config.ask;
+            delete config.chat_endpoint;
             saveConfig(config);
-            console.error("Cleared active workspace (and study).");
+            console.error("Cleared active workspace (and active study / ask / chat endpoint).");
             return;
         }
         if (!id) {
@@ -199,10 +224,20 @@ Examples:
             const rid = resolveId(id);
             const data = await client.get(`/products/${rid}`);
             const config = loadConfig();
+            const switched = config.workspace !== rid;
             config.workspace = rid;
-            delete config.study; // study belongs to workspace
+            if (switched) {
+                // Switching workspaces orphans all workspace-scoped active refs;
+                // dropping them avoids silent cross-workspace footguns (ISSUE-004).
+                delete config.study;
+                delete config.ask;
+                delete config.chat_endpoint;
+            }
             saveConfig(config);
             console.error(`Active workspace set to "${data.name || rid}".`);
+            if (switched) {
+                console.error("(Cleared active study / ask / chat endpoint — they belonged to the previous workspace.)");
+            }
         });
     });
 }