@ishlabs/cli 0.8.4 → 0.8.5

package/dist/lib/command-helpers.js

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import { resolveApiUrl, resolveToken } from "./auth.js";
 import { getAppUrl } from "../auth.js";
 import { ApiClient, ApiError } from "./api-client.js";
-import { outputError, setVerbose, setFields } from "./output.js";
+import { outputError, setVerbose, setFields, setGetField } from "./output.js";
 import { setColorsEnabled, colorsEnabled } from "./colors.js";
 import { loadConfig } from "../config.js";
 import { resolveId } from "./alias-store.js";
@@ -129,8 +129,58 @@ export async function resolveAudienceProfileIds(client, workspace, flags, opts =
         if (opts.excludeProfileIds && opts.excludeProfileIds.size > 0 && !filterDesc) {
             throw new Error("All matching profiles are already in this audience.");
         }
+        // When --country was the binding constraint, query the broader pool (drop
+        // country filter, keep the rest) and surface the top populated countries
+        // so the agent doesn't have to round-trip through `ish profile list` to
+        // find one that matches. Pure best-effort — any failure falls back to the
+        // original error.
+        let suggestion = "";
+        if (flags.country && flags.country.length > 0) {
+            try {
+                const broader = {
+                    product_id: workspace,
+                    type: "ai",
+                    limit: "500",
+                    offset: "0",
+                };
+                if (flags.search)
+                    broader.search = flags.search;
+                if (flags.gender && flags.gender.length > 0)
+                    broader.gender = flags.gender;
+                if (flags.minAge)
+                    broader.min_age = flags.minAge;
+                if (flags.maxAge)
+                    broader.max_age = flags.maxAge;
+                if (flags.visibility)
+                    broader.visibility = flags.visibility;
+                const broaderData = await client.get("/tester-profiles", broader);
+                const broaderItems = Array.isArray(broaderData)
+                    ? broaderData
+                    : Array.isArray(broaderData?.items)
+                        ? broaderData.items
+                        : [];
+                const broaderPool = opts.requireSimulatable
+                    ? broaderItems.filter(isSimulatable)
+                    : broaderItems;
+                const counts = new Map();
+                for (const p of broaderPool) {
+                    const c = typeof p.country === "string" ? p.country : null;
+                    if (c)
+                        counts.set(c, (counts.get(c) ?? 0) + 1);
+                }
+                const top = [...counts.entries()]
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 3);
+                if (top.length > 0) {
+                    suggestion = ` Populated countries with these other filters: ${top.map(([c, n]) => `${c} (${n})`).join(", ")}.`;
+                }
+            }
+            catch {
+                // Swallow — never replace the user's error with a secondary failure.
+            }
+        }
         if (filterDesc) {
-            throw new Error(`No ${sim}tester profiles in workspace ${workspace} match: ${filterDesc}. Broaden your filters or run \`ish profile list\` to inspect the pool.`);
+            throw new Error(`No ${sim}tester profiles in workspace ${workspace} match: ${filterDesc}.${suggestion} Broaden your filters or run \`ish profile list\` to inspect the pool.`);
         }
         throw new Error(`No ${sim}tester profiles found in workspace ${workspace}.${opts.requireSimulatable ? " Create profiles with simulation configs first." : ""}`);
     }
@@ -165,9 +215,52 @@ export function addAudienceFilterFlags(cmd, opts = {}) {
         .option("--visibility <v>", "Filter by visibility (private|public)");
 }
 export function getGlobals(cmd) {
+    let globals;
+    try {
+        globals = computeGlobals(cmd);
+    }
+    catch (err) {
+        // Validation errors (e.g. --get with --human) need to surface as a
+        // clean usage error regardless of which entry point invoked us. Many
+        // commands resolve globals without a withClient/runInline wrapper
+        // (e.g. `ish docs *`) so we cannot rely on those try/catches.
+        const useJson = process.argv.includes("--json")
+            || process.argv.includes("--get")
+            || !process.stdout.isTTY;
+        outputError(err, useJson);
+        process.exit(exitCodeFromError(err));
+    }
+    // Apply side effects (verbose, fields, colors, get-field, active workspace)
+    // here so commands that resolve globals without going through withClient /
+    // runInline still get --get / --human / --fields honored.
+    applyGlobals(globals);
+    return globals;
+}
+function computeGlobals(cmd) {
     const opts = cmd.optsWithGlobals();
-    // Auto-switch to JSON when stdout is piped (non-TTY)
-    const json = opts.json ?? !process.stdout.isTTY;
+    // Pattern Ω: display-vs-capture controls.
+    //   --get <field> implies --json (need structured data to extract from).
+    //   --human forces the human renderer regardless of TTY/pipe state.
+    //   Both passed together is a usage error — capture and display are
+    //   different modes; pick one.
+    const getField = typeof opts.get === "string" && opts.get.length > 0
+        ? opts.get
+        : undefined;
+    const human = opts.human === true;
+    if (getField && human) {
+        const err = new Error("--get and --human are mutually exclusive: --get captures a value (JSON-derived), --human forces human display.");
+        err.name = "ValidationError";
+        throw err;
+    }
+    // Auto-switch to JSON when stdout is piped (non-TTY).
+    // --human overrides the auto-flip; --get implies --json.
+    let json;
+    if (human)
+        json = false;
+    else if (getField)
+        json = true;
+    else
+        json = opts.json ?? !process.stdout.isTTY;
     // Parse --fields into an array
     const fields = opts.fields
         ? String(opts.fields).split(",").map((f) => f.trim()).filter(Boolean)
@@ -182,9 +275,15 @@ export function getGlobals(cmd) {
         dev: opts.dev,
         json,
         verbose: opts.verbose ?? false,
-        quiet: opts.quiet ?? (json && !opts.json), // auto-quiet when auto-json via pipe
+        // --get is silent capture: suppress stderr progress so the bare value is
+        // the only thing the agent has to parse. --human keeps progress on.
+        quiet: opts.quiet ?? (getField ? true : (json && !opts.json)),
+        quietExplicit: opts.quiet === true || getField !== undefined,
         color,
         fields,
+        get: getField,
+        human,
+        workspace: typeof opts.workspace === "string" ? opts.workspace : undefined,
     };
 }
 /**
@@ -224,14 +323,23 @@ export async function createClient(globals) {
     const token = await resolveToken(globals.token, apiUrl, globals.tokenFile);
     return new ApiClient({ apiUrl, token });
 }
+/**
+ * Module-level fallback for `resolveWorkspace`. Set by `applyGlobals` from the
+ * merged `optsWithGlobals().workspace`, so the program-root --workspace flag
+ * propagates to subcommand resolvers without each call site having to thread
+ * `globals` through. Subcommand-level --workspace still wins via Commander's
+ * own merge (it's already reflected in `globals.workspace`).
+ */
+let _activeWorkspace;
 function applyGlobals(globals) {
     setVerbose(globals.verbose);
     setFields(globals.fields);
+    setGetField(globals.get);
     setColorsEnabled(globals.color);
+    _activeWorkspace = globals.workspace;
 }
 export async function withClient(cmd, fn) {
     const globals = getGlobals(cmd);
-    applyGlobals(globals);
     try {
         const client = await createClient(globals);
         await fn(client, globals);
@@ -248,7 +356,6 @@ export async function withClient(cmd, fn) {
  */
 export async function runInline(cmd, fn) {
     const globals = getGlobals(cmd);
-    applyGlobals(globals);
     try {
         await fn(globals);
     }
@@ -299,9 +406,61 @@ export function readJsonFileOrStdin(filePath) {
         process.stdin.on("error", reject);
     });
 }
+/**
+ * Prompt for confirmation of a destructive action, or short-circuit when
+ * `--yes` is set. In `--json` mode without `--yes` we refuse with a usage
+ * error rather than silently proceeding or hanging on a prompt — agents
+ * piping through CLI must be explicit about destructive intent.
+ */
+export async function confirmDestructive(prompt, opts) {
+    if (opts.yes)
+        return;
+    if (opts.json) {
+        const err = new Error(`--yes is required for destructive actions in --json mode. Refusing to proceed without explicit confirmation.`);
+        err.name = "ValidationError";
+        throw err;
+    }
+    if (!process.stdin.isTTY) {
+        const err = new Error(`--yes is required for destructive actions when stdin is not a TTY. Refusing to proceed without explicit confirmation.`);
+        err.name = "ValidationError";
+        throw err;
+    }
+    process.stderr.write(`${prompt} [y/N] `);
+    const answer = await new Promise((resolve, reject) => {
+        let data = "";
+        const onData = (chunk) => {
+            data += chunk.toString();
+            if (data.includes("\n")) {
+                process.stdin.off("data", onData);
+                process.stdin.off("error", onError);
+                process.stdin.pause();
+                resolve(data.trim().toLowerCase());
+            }
+        };
+        const onError = (err) => {
+            process.stdin.off("data", onData);
+            process.stdin.off("error", onError);
+            reject(err);
+        };
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", onData);
+        process.stdin.on("error", onError);
+        process.stdin.resume();
+    });
+    if (answer !== "y" && answer !== "yes") {
+        const err = new Error("Aborted.");
+        err.name = "ValidationError";
+        throw err;
+    }
+}
 export function resolveWorkspace(explicit) {
     if (explicit)
         return resolveId(explicit);
+    // Fall back to the program-root --workspace cached by applyGlobals — covers
+    // `ish --workspace W study list` where the subcommand action doesn't see the
+    // flag in its local opts.
+    if (_activeWorkspace)
+        return resolveId(_activeWorkspace);
     const env = process.env.ISH_WORKSPACE;
     if (env)
         return resolveId(env);

package/dist/lib/docs.js

@@ -47,7 +47,8 @@ Two top-level run verbs:
   and prints active workspace/study/ask. See \`concepts/active-context\`.
 - Running your first study? \`ish docs get-page guides/first-study\`.
 - Comparing study vs ask? \`ish docs get-page concepts/run-verbs\`.
-- Need machine-readable output? \`ish docs get-page reference/json-mode\`.
+- **Output modes** (display vs capture vs chain — \`--human\`, \`--get\`,
+  \`--json\`)? \`ish docs get-page reference/json-mode\`.
 - Auth gated URL? \`ish docs get-page concepts/site-access\`.
 
 ## Install the skill into this project
@@ -74,6 +75,22 @@ A workspace carries:
 - Site-access credentials (encrypted at rest) — see \`concepts/site-access\`.
 - Tester profiles + sources visible to every study/ask in the workspace.
 
+## Selecting a workspace per command
+
+\`--workspace <id>\` works at the **program root** as well as on each
+subcommand — both forms are equivalent, and the subcommand-level flag
+wins on conflict:
+
+\`\`\`
+ish --workspace w-6ec study list           # program root
+ish study list --workspace w-6ec           # subcommand (same effect)
+ish --workspace w-6ec study list --workspace w-other   # w-other wins
+\`\`\`
+
+Use whichever is most natural for your scripting. Without either, the
+CLI falls back to \`ISH_WORKSPACE\` (env var) and then the
+\`workspace\` saved in \`~/.ish/config.json\`.
+
 ## Common commands
 
 \`\`\`
@@ -148,6 +165,21 @@ Every study response carries two status-shaped fields:
 The CLI also surfaces a \`status_inferred\` field + stderr warning when
 it detects raw-vs-derived inconsistencies. See \`reference/json-mode\`.
 
+## Deleting a study
+
+\`ish study delete <id>\` requires explicit confirmation:
+
+- **Interactive (TTY)**: prompts on stderr; type \`y\` to proceed.
+- **Non-interactive** (\`--json\`, piped, or non-TTY stdin): pass
+  \`-y\` / \`--yes\` to confirm. Without it, the CLI exits with usage
+  code 2 rather than deleting silently.
+
+\`\`\`
+ish study delete s-b2c              # interactive prompt
+ish study delete s-b2c --yes        # skip prompt
+ish study delete s-b2c --json --yes # JSON consumers must be explicit
+\`\`\`
+
 ## Generate vs create
 
 \`ish study generate --problem "..."\` runs an LLM-backed flow that
@@ -379,7 +411,12 @@ ish ask results a-6ec --json | jq '.rounds[0].aggregates'
 
 For \`--wants-pick\` / \`--wants-ratings\` rounds, \`ask results --json\`
 includes an \`aggregates\` field per round so you don't have to parse
-prose:
+prose. Each individual pick also carries a **\`pick_confidence\`** score
+(0..1) — the model's self-reported confidence in its variant choice.
+Use it to break ties: when two variants are nominally close on count,
+the variant with higher mean \`pick_confidence\` is the more decisive
+choice. \`pick_confidence\` is only present on rounds run with
+\`--wants-pick\`.
 
 \`\`\`json
 {
@@ -517,6 +554,24 @@ ish profile create --file profile.json
 Expected JSON: \`{ "name": "...", "type": "ai", "gender": "female",
 "country": "US", "occupation": "...", "bio": "..." }\`
 
+## Generation behavior to expect
+
+- **Latency**: \`profile generate\` is LLM-backed and typically takes
+  10–20s for 1–5 profiles. The CLI emits stderr progress lines
+  (\`generating N profiles…\` then \`generated N profiles\`) so you
+  know it's not stuck. Suppress with \`--quiet\`.
+- **Brief fidelity**: bios reference domain-specific terms from your
+  description verbatim or as close paraphrase. If you mention
+  \`F-skatt\`, "manual Excel invoicing", "Stripe payouts", or similar
+  tools/jargon, expect those terms (or paraphrases) to appear in
+  each generated bio's daily-routine framing — not sanded down to
+  generic prose.
+- **DOB diversity**: month-and-day are derived from a deterministic
+  per-profile hash so birthdays spread across the year (no more
+  every-profile-on-\`06-15\`). Year follows the requested age.
+  Re-generating the same name/country/occupation/age yields the
+  same DOB.
+
 ## Related
 
 - \`concepts/source\` — the inputs to \`profile generate\`.
@@ -577,6 +632,24 @@ flags. Two ways to select:
 The two modes are **mutually exclusive** — pass either \`--profile\` or
 the filter set, not both.
 
+## Empty-pool suggestions
+
+When a filter combination matches zero profiles, the error message
+includes the top three populated countries that satisfy your *other*
+filters — so you can pivot to a country with actual coverage without a
+second \`profile list\` round-trip:
+
+\`\`\`
+$ ish study run --country XX --min-age 35 --sample 5
+Error: No simulatable AI tester profiles in workspace w-b32 match:
+       --country XX --min-age 35.
+       Populated countries with these other filters: SE (12), DE (8), NL (3).
+       Broaden your filters or run \`ish profile list\` to inspect the pool.
+\`\`\`
+
+The suggestion is best-effort — it never replaces the original error,
+just augments it.
+
 ## Defaults
 
 - \`ish study run\` with no audience flags → reuses the iteration's
@@ -709,6 +782,13 @@ ish study cancel <tester_id>              # cancel a running simulation
 \`<tester_id>\` accepts a tester alias (\`t-…\`) or a full UUID. The
 study-level \`poll\`/\`wait\` forms also exist (\`--study <id>\` /
 \`--iteration <id>\`) for whole-batch progress.
+
+## Related
+
+- \`reference/json-mode\` — output modes (display vs capture vs chain).
+  Use \`--get tester_aliases\` to capture the run's testers without
+  piping through \`jq\`. \`--human\` forces table output even through
+  \`tee\`/redirection.
 `;
 const REFERENCE_ALIASES = `# reference: aliases
 
@@ -740,15 +820,84 @@ ish profile generate --source tps-3a4 --count 4
 The full UUID is also always accepted. Add \`--verbose\` to JSON output
 to see UUIDs alongside aliases.
 `;
-const REFERENCE_JSON_MODE = `# reference: JSON output for agents
+const REFERENCE_JSON_MODE = `# reference: output modes for agents
+
+\`ish\` distinguishes **three output modes** so agents don't have to
+post-process CLI output with \`jq\` or \`python\` for routine tasks:
+
+1. **Display mode (human)** — readable tables and key/value blocks.
+   Default on a TTY. Force it anywhere with \`--human\` (e.g. \`ish
+   workspace list --human | tee /tmp/x.txt\` keeps the table layout
+   even though stdout is redirected).
+2. **Capture mode (single value)** — \`--get <field>\` extracts the
+   value at a dotted path and prints it bare (no JSON quotes, no
+   indentation). Use this to feed one CLI's output into another:
+   \`ASK=$(ish ask create … --get alias)\` instead of
+   \`ASK=$(ish ask create … --json | jq -r .alias)\`.
+3. **Chain mode (full JSON)** — \`--json\` (or auto-enabled when stdout
+   is piped). Returns structured payloads for downstream parsing.
+   Reach for this only when you actually need multiple fields or a
+   nested shape; for one value, \`--get\` is shorter.
+
+## Picking the right mode
+
+| You want to…                              | Mode                                             |
+|-------------------------------------------|--------------------------------------------------|
+| Show the user a list of workspaces        | bare command (TTY) or \`--human\` if redirecting   |
+| Capture an alias for a follow-up command  | \`--get alias\`                                   |
+| Inspect a specific nested field           | \`--get tester_profile.name\`                     |
+| Compare 2+ fields, or pipe into jq        | \`--json\` (or auto-on when piped)                |
+| Force human output through \`tee\`         | \`--human\`                                       |
+| Force JSON on a TTY                       | \`--json\`                                        |
+
+\`--get\` and \`--human\` are mutually exclusive — capture and display are
+different intents; pick one. \`--get\` implies \`--json\` internally so the
+renderer always has structured data to extract from; you don't need to
+add \`--json\` yourself.
+
+### Worked example: display vs. capture
+
+\`\`\`bash
+# Display: bare command on a TTY → human table.
+ish workspace list
+
+# Capture: feed one alias into the next command, no jq required.
+ASK=$(ish ask create --new --name demo \\
+        --prompt "Which?" --variant text:A --variant text:B \\
+        --sample 30 --get alias)
+ish ask wait "$ASK" --timeout 600
+
+# Capture across an entire list: one value per line.
+ish workspace list --get alias
+# w-6ec
+# w-d02
+# …
 
-Every command that produces output supports machine-readable JSON. JSON
-mode is **auto-enabled when stdout is piped**, so an agent rarely needs
-\`--json\` explicitly.
+# Display preserved through tee:
+ish ask results "$ASK" --human | tee /tmp/transcript.txt
+\`\`\`
 
 ## Flags
 
-- \`--json\`            — force JSON output even on a TTY.
+- \`--human\`            — force human-readable output regardless of TTY
+                          state (overrides the auto-flip-to-JSON when
+                          stdout is piped). Mutually exclusive with
+                          \`--get\`.
+- \`--get <field>\`      — extract a single field from the JSON response
+                          and print only its bare value. Supports dotted
+                          paths (\`tester_profile.name\`). On a paginated
+                          \`{items: [...]}\` response, the path
+                          auto-descends into \`items\` so \`--get alias\`
+                          on a list yields one value per line. Implies
+                          \`--json\` internally; mutually exclusive with
+                          \`--human\`. Strings/numbers/bools are printed
+                          unquoted; \`null\` prints as an empty line;
+                          arrays print one element per line; objects
+                          print as compact one-line JSON. Missing field
+                          → exit 2 with a usage error.
+- \`--json\`             — force JSON output even on a TTY. Auto-enabled
+                          when stdout is piped (unless \`--human\` is
+                          set).
 - \`--fields a,b,c\`    — keep only these fields in JSON output (e.g.
                           \`alias,name,status\`). Filters per item only;
                           list wrappers (\`{items, total, returned,
@@ -757,7 +906,9 @@ mode is **auto-enabled when stdout is piped**, so an agent rarely needs
                           write paths) the full server payload instead
                           of the compact response.
 - \`-q, --quiet\`        — suppress progress messages on stderr (errors
-                          still go to stderr).
+                          still go to stderr). \`--get\` implies
+                          \`--quiet\` so the bare value is the only
+                          thing on stdout.
 
 ## Stable shape rules
 
@@ -854,9 +1005,12 @@ The CLI guarantees these contracts so agents can chain safely:
   in the \`testers[]\` array, and a "Failed testers" subsection in
   human output. Empty when the tester succeeded.
 - **\`profile list\` emits a stderr pagination hint** when
-  \`has_more=true\` and stdout is human (TTY, not piped, not \`--quiet\`).
-  Format: "showing N–M of TOTAL; pass --offset M --limit N for more."
-  JSON consumers read \`has_more\` directly off the envelope.
+  \`has_more=true\` and \`--quiet\` is not set. The hint goes to **stderr
+  in every mode** including \`--json\` and piped stdout — it never
+  pollutes machine-readable stdout but is visible to any agent that
+  reads stderr (which they should, for warnings and progress). Format:
+  "showing N–M of TOTAL; pass --offset M --limit N for more."
+  JSON consumers can also read \`has_more\` directly off the envelope.
 - **\`ask results --json\` adds an \`aggregates\` field per round.** For
   rounds with \`wants_pick\`/\`wants_ratings\`, the CLI computes the
   verdict locally so agents don't have to parse comment prose:
@@ -938,25 +1092,43 @@ a structured error object on **stdout** and a human message on
 ## Examples
 
 \`\`\`
-ish workspace list --json | jq '.[].alias'
-ish study get s-b2c --fields alias,name,status,iterations
+# Display (table on TTY, JSON when piped):
+ish workspace list
+
+# Display preserved through tee/pipe (force human):
+ish ask results a-6ec --human | tee /tmp/results.txt
+
+# Capture a single alias to feed into the next command:
+WS=$(ish workspace list --get alias | head -1)
+
+# Inspect a nested field:
+ish study tester t-a17 --get tester_profile.name
+
+# Chain (full JSON for jq when you need multiple fields):
+ish study get s-b2c --fields alias,name,status,iterations --json
 ish ask results a-6ec --round 1 --json
-ish profile generate --description "..." --count 3 --json | jq '.[].alias'
 \`\`\`
 
 ## Composing commands
 
-JSON mode + alias resolution makes pipelines safe:
+\`--get\` removes most of the \`jq\` shims agents reach for. Capture in
+a script, then display the final result back to the user:
 
 \`\`\`
-ITER=$(ish iteration create --url https://example.com --json | jq -r .alias)
-TESTERS=$(ish study run --iteration "$ITER" --sample 5 --country SE \\
-            --json | jq -r '.tester_aliases[]')
+# Capture — bare values, no jq needed:
+ITER=$(ish iteration create --url https://example.com --get alias)
+TESTERS=$(ish study run --iteration "$ITER" --sample 5 --country SE --get tester_aliases)
 for t in $TESTERS; do
   ish study wait "$t" --timeout 600
 done
-ish study results --json | jq .
+
+# Display the final results to the user, even though we're in a script:
+ish study results --human
 \`\`\`
+
+When you genuinely need multiple fields in one parse pass, \`--json\` is
+still the right tool — \`--get\` is for single-value capture, not for
+reshaping output.
 `;
 const GUIDE_FIRST_STUDY = `# guide: your first study, end to end
 
@@ -1098,7 +1270,9 @@ of scope: \`workspace\`, \`config\`, \`docs\`, \`init\`, \`login\`,
 ## Related
 
 - \`reference/aliases\` — the prefix scheme used by every entity.
-- \`reference/json-mode\` — output contracts for piping \`ish status\`.
+- \`reference/json-mode\` — output modes (display vs capture vs chain),
+  including \`--get workspace.alias\` to capture the active workspace
+  without piping \`ish status --json\` through \`jq\`.
 `;
 const REFERENCE_BILLING_LIMITS = `# reference: billing tier limits
 
@@ -1272,8 +1446,8 @@ const PAGES = [
     },
     {
         slug: "reference/json-mode",
-        title: "reference: JSON output for agents",
-        description: "JSON, --fields, --verbose, exit codes, pipe behaviour.",
+        title: "reference: output modes for agents (display, capture, chain)",
+        description: "Display vs capture vs chain: --human, --get, --json, --fields, exit codes, pipe behavior.",
         body: REFERENCE_JSON_MODE,
     },
     {

package/dist/lib/output.d.ts

@@ -9,6 +9,12 @@
 /** Set by withClient() based on global flags. */
 export declare function setVerbose(v: boolean): void;
 export declare function setFields(fields?: string[]): void;
+/**
+ * Pattern Ω capture mode: when set, jsonOutput() returns the bare value at
+ * the dotted path instead of the full JSON. Cleared between command runs by
+ * each invocation of `applyGlobals()`.
+ */
+export declare function setGetField(field?: string): void;
 /** Per-call output options for stable JSON contracts. */
 export interface OutputOptions {
     /**