@ishlabs/cli 0.8.4 → 0.9.0

package/dist/lib/output.js

@@ -11,9 +11,105 @@ import { deterministicAlias, getAliasMap, ALIAS_PREFIX } from "./alias-store.js"
 // --- Lean JSON: strip noise for agent-friendly output ---
 let _verbose = false;
 let _fields;
+let _getField;
 /** Set by withClient() based on global flags. */
 export function setVerbose(v) { _verbose = v; }
 export function setFields(fields) { _fields = fields; }
+/**
+ * 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 function setGetField(field) { _getField = field; }
+/**
+ * Walk a dotted path through a JSON value. Returns the resolved value or
+ * `MISSING` if any step is undefined. Numeric segments index into arrays;
+ * non-numeric segments key into objects. When a segment is non-numeric and
+ * the current value is an array, the segment is mapped over the array
+ * (e.g. `items.alias` on `{items: [...]}` after `items` is unwrapped to the
+ * array yields the per-element `alias` values).
+ */
+const MISSING = Symbol("missing");
+function walkPath(data, segments) {
+    let cur = data;
+    for (const seg of segments) {
+        if (cur === null || cur === undefined)
+            return MISSING;
+        if (Array.isArray(cur)) {
+            // `seg` could be a numeric index, or a key to apply to each element.
+            const asIndex = /^\d+$/.test(seg) ? parseInt(seg, 10) : null;
+            if (asIndex !== null) {
+                if (asIndex < 0 || asIndex >= cur.length)
+                    return MISSING;
+                cur = cur[asIndex];
+                continue;
+            }
+            // Map across array: pick the key on each element. Skip elements that
+            // lack the key so `--get items.alias` on a list with one bad row
+            // still returns the rest.
+            const mapped = [];
+            for (const el of cur) {
+                if (el !== null && typeof el === "object" && seg in el) {
+                    mapped.push(el[seg]);
+                }
+            }
+            if (mapped.length === 0)
+                return MISSING;
+            cur = mapped;
+            continue;
+        }
+        if (typeof cur !== "object")
+            return MISSING;
+        const obj = cur;
+        if (!(seg in obj))
+            return MISSING;
+        cur = obj[seg];
+    }
+    return cur;
+}
+/**
+ * Resolve `_getField` against `data`. Auto-descends into a top-level
+ * `items: [...]` wrapper when the requested path doesn't start with `items`
+ * and the path resolves on items but not at top level — i.e.
+ * `--get alias` on a list response acts like `--get items.alias`.
+ */
+function extractGetField(data, path) {
+    const segments = path.split(".").map((s) => s.trim()).filter(Boolean);
+    if (segments.length === 0)
+        return MISSING;
+    const direct = walkPath(data, segments);
+    if (direct !== MISSING)
+        return direct;
+    // Auto-descend through {items: [...]} wrapper for paginated list responses.
+    if (segments[0] !== "items"
+        && data !== null
+        && typeof data === "object"
+        && !Array.isArray(data)
+        && Array.isArray(data.items)) {
+        const viaItems = walkPath(data, ["items", ...segments]);
+        if (viaItems !== MISSING)
+            return viaItems;
+    }
+    return MISSING;
+}
+/**
+ * Render an extracted value as a bare string for stdout. Rules:
+ *   - string/number/boolean: printed as-is (no JSON quotes).
+ *   - null: empty string.
+ *   - arrays: one element per line, each element rendered by the same rules
+ *     (objects within the array are compact JSON).
+ *   - objects: compact JSON on a single line.
+ */
+function renderBare(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (Array.isArray(value)) {
+        return value.map((v) => renderBare(v)).join("\n");
+    }
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const TIMESTAMP_KEYS = new Set(["created_at", "updated_at"]);
 const PAGINATION_KEYS = new Set(["items", "total", "returned", "limit", "offset", "has_more"]);
@@ -151,6 +247,19 @@ function jsonOutput(data, options = {}) {
     if (_fields && _fields.length > 0) {
         out = pickFields(out, _fields);
     }
+    // Pattern Ω capture mode: --get <field> returns bare values instead of
+    // structured JSON. We extract from the post-lean / post-fields data so the
+    // path the agent reasons about matches what they'd see on a normal --json
+    // call (e.g. UUIDs already replaced by aliases).
+    if (_getField) {
+        const extracted = extractGetField(out, _getField);
+        if (extracted === MISSING) {
+            const err = new Error(`--get: field "${_getField}" not found in response.`);
+            err.name = "ValidationError";
+            throw err;
+        }
+        return renderBare(extracted);
+    }
     return JSON.stringify(out, null, 2);
 }
 /**
@@ -166,9 +275,29 @@ function injectAliases(items, prefix, idField = "id") {
     }
 }
 // --- JSON mode ---
+/**
+ * Catch jsonOutput's --get extraction failure (a ValidationError thrown when
+ * the requested field is missing) and route it through outputError + exit 2,
+ * so commands that don't go through withClient/runInline (e.g. `ish docs *`)
+ * still surface a clean usage error instead of an uncaught stack trace.
+ */
+function safeJsonOutput(data, options = {}) {
+    try {
+        return jsonOutput(data, options);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "ValidationError") {
+            outputError(err, true);
+            process.exit(2);
+        }
+        throw err;
+    }
+}
 export function output(data, json, options = {}) {
     if (json) {
-        console.log(jsonOutput(data, options));
+        const text = safeJsonOutput(data, options);
+        if (text !== undefined)
+            console.log(text);
         return;
     }
     if (data === null || data === undefined)
@@ -185,7 +314,9 @@ export function output(data, json, options = {}) {
 }
 export function outputList(rows, json) {
     if (json) {
-        console.log(jsonOutput(rows));
+        const text = safeJsonOutput(rows);
+        if (text !== undefined)
+            console.log(text);
         return;
     }
     if (rows.length === 0) {

package/dist/lib/skill-content.js

@@ -77,7 +77,7 @@ Workspace (= product)
 ├── Tester Profiles (tp-…)   reusable audience personas
 │     └── Sources (tps-…)    transcripts/audio/images that seed generation
 ├── Study (s-…)              persistent research artifact
-│     ├── modality           interactive | text | video | audio | image | document
+│     ├── modality           interactive | text | video | audio | image | document | chat
 │     ├── assignments        tasks the tester does
 │     ├── questionnaire      questions the tester answers
 │     └── Iterations (i-…)   one configured run; carries the URL or media
@@ -140,10 +140,58 @@ See \`references/workflows.md\` in this skill for end-to-end transcripts:
 - Targeting a gated URL (basic auth, session cookie, login form)
 - Re-running a study with a fresh audience
 
+## Display vs. capture: the right output mode
+
+Three output modes — pick the one matching your intent, **don't reach
+for \`jq\` / \`python\` reflexively**:
+
+| Intent                                          | Use                  |
+|-------------------------------------------------|----------------------|
+| Show the user a list/table                      | bare command (TTY) or \`--human\` |
+| Capture one value to feed into the next command | \`--get <field>\`     |
+| Parse multiple fields / nested shape            | \`--json\`            |
+
+\`--get\` extracts a single field from the JSON response and prints its
+bare value. It supports dotted paths and auto-descends into list
+\`items\` so \`--get alias\` on a paginated list yields one alias per
+line. \`--human\` forces human output even when stdout is piped — use
+it when you want to \`tee\` a table to a file but still show it. The
+two flags are mutually exclusive (capture and display are different
+intents).
+
+### Worked example — capture in a script, display to the user
+
+\`\`\`bash
+# DON'T: shim around the CLI with jq just to grab one value.
+# ASK=$(ish ask create … --json | jq -r .alias)
+
+# DO: capture mode — bare value, exit 0.
+ASK=$(ish ask create --new --name demo \\
+        --prompt "Which?" --variant text:A --variant text:B \\
+        --sample 30 --get alias)
+
+# DON'T: pipe --json through jq when you want to show the user a table.
+# ish ask results "$ASK" --json | jq … | tee /tmp/x.txt
+
+# DO: --human keeps the table layout even through tee.
+ish ask results "$ASK" --human | tee /tmp/transcript.txt
+\`\`\`
+
+Missing field on \`--get\` → exit 2 with a usage error. \`--get\` also
+implies \`--quiet\` so the bare value is the only thing on stdout.
+
 ## Output handling
 
 - Every command supports \`--json\`. JSON mode is **auto-enabled when
   stdout is piped**, so an agent rarely needs \`--json\` explicitly.
+- **\`--get <field>\` is the right way to capture a single value.**
+  Dotted paths supported (\`tester_profile.name\`); on a paginated
+  \`{items: [...]}\` response, a leading non-\`items\` segment
+  auto-descends into items. Replaces the
+  \`--json | jq -r .field\` shim. Implies \`--json\` and \`--quiet\`.
+- **\`--human\` forces human output even when stdout is piped.** Use it
+  to \`tee\` a table without losing the layout. Mutually exclusive
+  with \`--get\`.
 - \`--fields a,b,c\` strips JSON output to the listed fields (saves
   tokens). \`--verbose\` adds full UUIDs and timestamps.
 - **Stdout is data only.** All progress, status, and "Open in browser"
@@ -175,10 +223,38 @@ See \`references/workflows.md\` in this skill for end-to-end transcripts:
   Top-level field with per-round picks/winner snapshots and
   \`picks_delta\` (R1 → last). Don't diff two \`ask results\` calls by
   hand.
-- **\`--workspace\` is accepted on every workspace-scoped subcommand.**
-  Pass it reflexively on any \`ask\`/\`study\`/\`iteration\`/\`profile\`/
-  \`source\` subcommand — when workspace is inferable from an ID alias
-  it's silently ignored.
+- **\`--workspace\` works at the program root AND every subcommand.**
+  \`ish --workspace w-6ec study list\` and \`ish study list --workspace
+  w-6ec\` are equivalent; if both are passed, the subcommand-level
+  flag wins. Without either, the CLI falls back to \`ISH_WORKSPACE\`
+  env then the active workspace in \`~/.ish/config.json\`.
+- **\`profile generate\` emits stderr progress.** \`generating N
+  profiles…\` then \`generated N profiles\` around the ~10–20s LLM
+  call. Suppress with \`--quiet\`. Generated bios reference the
+  brief's domain context naturally (occupation, daily work,
+  frustrations) — they no longer parrot vocabulary from the brief
+  verbatim. DOBs spread across the year instead of all-on-\`06-15\`.
+- **Empty-pool errors include a country-suggestion line.** When
+  \`study run\` / \`ask run --new\` rejects because \`--country XX\`
+  matched zero profiles, the error includes the top-3 populated
+  countries that satisfy your *other* filters. Pivot directly without
+  a second \`profile list\` round-trip.
+- **\`<entity> list\` emits a stderr pagination hint** when
+  \`has_more=true\` and \`--quiet\` is unset. Goes to stderr in **every
+  mode** (including \`--json\` and piped stdout) — it never pollutes
+  machine-readable stdout but is visible to any agent reading stderr.
+  Format: "showing N–M of TOTAL; pass --offset M --limit N for more."
+- **\`study delete\` requires explicit confirmation.** Interactive:
+  prompts on stderr. Non-interactive (\`--json\`, piped, non-TTY
+  stdin): pass \`-y\` / \`--yes\` to confirm. Without it, the CLI
+  exits with usage code 2.
+- **\`ask add-questions\` supports \`--wait\` / \`--timeout\`.** Match
+  the parity of \`ask create\` and \`ask run\`. Without \`--wait\` the
+  command returns after dispatch (round still running).
+- **\`pick_confidence\` (0..1) is on every \`--wants-pick\` response.**
+  The model's self-reported confidence in its variant choice. Use it
+  to break ties when nominal pick counts are close. See
+  \`ish docs get-page concepts/ask\`.
 - Exit codes carry meaning: 0 success, 2 usage/validation,
   3 auth, 4 not-found, 5 transient. See
   \`ish docs get-page reference/json-mode\`.
@@ -404,6 +480,35 @@ URL=$(jq -r 'select(.status=="connected") | .tunnel_url' /tmp/ish-tunnel.log | h
 ish iteration create --url "$URL"
 \`\`\`
 
+## 7. Display-vs-capture: a script that does both
+
+Goal: drive an A/B in a script, capture aliases without \`jq\`, and
+still show the human a readable result table at the end.
+
+\`\`\`bash
+# Capture mode — bare values, suitable for shell variables.
+ASK=$(ish ask create --new --name "tagline AB" \\
+        --prompt "Which sounds better?" \\
+        --variant text:"Short and punchy." \\
+        --variant text:"A longer, descriptive line." \\
+        --sample 30 --wants-pick --get alias)
+
+# Wait silently — exit code is what matters here.
+ish ask wait "$ASK" --timeout 600 --quiet
+
+# Capture the winner letter for downstream branching:
+WINNER=$(ish ask results "$ASK" --get rounds.aggregates.winner.letter)
+echo "Winning variant: $WINNER"
+
+# Display mode — show the user the full results table even though
+# we're inside a script (stdout is piped to tee).
+ish ask results "$ASK" --human | tee "/tmp/ask-\${ASK}.txt"
+\`\`\`
+
+The mental rule: **\`--get\` is for capture, bare commands / \`--human\`
+are for display, \`--json\` is for chaining (multiple fields at once).**
+If you find yourself reaching for \`jq -r .x\`, you wanted \`--get x\`.
+
 ## Tips for chaining commands as an agent
 
 - Capture aliases from JSON: \`ITER=$(ish iteration create --url … --json | jq -r .alias)\`
@@ -428,12 +533,16 @@ ish iteration create --url "$URL"
 
 | You want to…                              | Don't                                  | Do                                                                 |
 |-------------------------------------------|----------------------------------------|--------------------------------------------------------------------|
+| Capture a single value (alias, id, …)     | \`--json \\| jq -r .alias\`             | \`--get alias\`                                                      |
+| Capture a nested value                    | \`--json \\| jq -r .tester_profile.name\` | \`--get tester_profile.name\`                                        |
+| Capture every alias from a list           | \`--json \\| jq -r '.items[].alias'\`   | \`--get alias\` (auto-descends into \`items\`, one per line)            |
+| Force human output through tee/redirect   | none, output silently became JSON      | \`--human\`                                                          |
 | Look up 2-3 specific profiles             | \`profile list --json \\| jq '.items[] \\| select(...)'\` | \`ish profile get tp-1b9 tp-fc1 tp-2fc\`                             |
 | Show only some fields                     | \`--json \\| jq '{alias, name, country}'\` | \`--fields alias,name,country\`                                      |
 | Count testers on an ask                   | \`--json \\| jq '.testers \\| length'\`  | \`ish ask get a-… --fields alias,testers_count\`                     |
 | Count responses on a round                | \`--json \\| jq '.rounds[0].responses \\| length'\` | \`ish ask get a-… --fields alias,rounds,responses_complete,responses_total\` |
 | Pick the A/B winner                       | \`--json \\| jq '.rounds[0].responses…'\` | \`ish ask results a-… --json\` then read \`.rounds[].aggregates.winner\` |
-| List of testers from \`study run\`        | \`--json \\| jq '.testers[].id'\`        | \`--json\` already has \`tester_ids[]\` and \`tester_aliases[]\`        |
+| List of testers from \`study run\`        | \`--json \\| jq '.testers[].id'\`        | \`--get tester_aliases\` (or \`tester_ids\` for UUIDs)                |
 
 The bias here is intentional: \`ish\` ships shapes designed for agent
 consumption. If you find yourself reaching for \`jq\` or \`python\` to
@@ -496,6 +605,8 @@ is expected. Full UUIDs always work too. See
 
 | Flag             | Effect                                                   |
 |------------------|----------------------------------------------------------|
+| \`--get <field>\`  | **Capture mode.** Print the bare value at the dotted path; auto-descends into list \`items\`. Implies \`--json\` + \`--quiet\`. Replaces \`--json \\| jq -r .field\`. |
+| \`--human\`        | **Force display mode** even when stdout is piped (overrides JSON-when-piped). Mutually exclusive with \`--get\`. |
 | \`--json\`         | JSON output (auto-on when stdout is piped)               |
 | \`--fields a,b\`   | Keep only listed fields in JSON                          |
 | \`--verbose\`      | Include UUIDs + timestamps in JSON                       |
@@ -503,6 +614,9 @@ is expected. Full UUIDs always work too. See
 | \`-t, --token\`    | Auth token (else ISH_TOKEN env, else \`ish login\` saved)  |
 | \`--api-url\`      | Override backend (default https://api.ishlabs.io)        |
 
+See \`ish docs get-page reference/json-mode\` for the full display-vs-
+capture-vs-chain decision rule.
+
 ## Exit codes
 
 \`0\` ok · \`1\` general · \`2\` usage/validation · \`3\` auth ·

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.8.4",
-  "description": "The command-line interface for Ish",
+  "version": "0.9.0",
+  "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
     "ish": "./dist/index.js"
@@ -41,4 +41,4 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   }
-}
+}