@ishlabs/cli 0.8.4 → 0.8.5

package/README.md

@@ -55,7 +55,7 @@ Two top-level research primitives, both consume reusable tester profiles:
 Workspace (= product, top-level container)
 │
 ├── Tester Profiles        ← reusable audience personas
-│     └── Audience Sources (transcripts / audio / images that seed generation)
+│     └── Audience Sources (images/PDFs/audio/video/text transcripts that seed generation)
 │
 ├── Study  ─────────────── "structured research artifact"
 │     ├── modality (interactive | text | video | audio | image | document)

package/dist/auth.d.ts

@@ -21,6 +21,21 @@ export declare function login(appUrl?: string): Promise<{
     accessToken: string;
     refreshToken: string;
 }>;
+/**
+ * Thrown by `refreshTokens` when the refresh attempt failed permanently and
+ * the local config can't recover (e.g. Supabase `refresh_token_not_found`,
+ * `invalid_grant`, or any 400-class response). Callers should treat this as
+ * "user must run `ish login` again" — retrying won't help.
+ *
+ * Transient failures (network errors, 5xx, timeouts) are NOT this error and
+ * may be worth retrying.
+ */
+export declare class AuthRefreshPermanentError extends Error {
+    readonly httpStatus: number;
+    readonly errorCode: string | undefined;
+    readonly body: string;
+    constructor(httpStatus: number, body: string, errorCode: string | undefined);
+}
 export declare function refreshTokens(refreshToken: string, options?: {
     /** The (possibly expired) access token. Used to pick the correct Supabase project. */
     accessToken?: string;

package/dist/auth.js

@@ -139,6 +139,43 @@ export async function login(appUrl) {
     throw new Error("Login timed out. Please try again.");
 }
 // --- Token refresh ---
+/**
+ * Thrown by `refreshTokens` when the refresh attempt failed permanently and
+ * the local config can't recover (e.g. Supabase `refresh_token_not_found`,
+ * `invalid_grant`, or any 400-class response). Callers should treat this as
+ * "user must run `ish login` again" — retrying won't help.
+ *
+ * Transient failures (network errors, 5xx, timeouts) are NOT this error and
+ * may be worth retrying.
+ */
+export class AuthRefreshPermanentError extends Error {
+    httpStatus;
+    errorCode;
+    body;
+    constructor(httpStatus, body, errorCode) {
+        const detail = errorCode ? ` ${errorCode}` : "";
+        super(`Token refresh failed permanently (HTTP ${httpStatus}${detail}): ${body}`);
+        this.name = "AuthRefreshPermanentError";
+        this.httpStatus = httpStatus;
+        this.errorCode = errorCode;
+        this.body = body;
+    }
+}
+function parseRefreshErrorCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            if (typeof parsed.error_code === "string")
+                return parsed.error_code;
+            if (typeof parsed.error === "string")
+                return parsed.error;
+        }
+    }
+    catch {
+        // not JSON — fall through
+    }
+    return undefined;
+}
 export async function refreshTokens(refreshToken, options) {
     const project = options?.supabaseUrl && options?.anonKey
         ? { url: options.supabaseUrl, anonKey: options.anonKey }
@@ -154,6 +191,9 @@ export async function refreshTokens(refreshToken, options) {
     });
     if (!resp.ok) {
         const body = await resp.text().catch(() => "");
+        if (resp.status >= 400 && resp.status < 500) {
+            throw new AuthRefreshPermanentError(resp.status, body, parseRefreshErrorCode(body));
+        }
         throw new Error(`Token refresh failed (HTTP ${resp.status}): ${body}`);
     }
     const data = await resp.json();

package/dist/commands/ask.js

@@ -326,6 +326,10 @@ Minimal --questions JSON (server keys: "question" + "type"):
     { "question": "What stood out?", "type": "text" },
     { "question": "Rate it 1-5", "type": "slider" }
   ]
+
+Picks come back with a \`pick_confidence\` (0..1) score per tester when
+\`--wants-pick\` is set — read it off \`pick.confidence\` in the response. See
+\`ish docs get-page concepts/ask\` for interpretation.
 `)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -430,7 +434,14 @@ lookups.`)
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .option("--round <n>", "Show only round N (1-indexed; default: all rounds)")
-        .addHelpText("after", "\nExamples:\n  $ ish ask results a-6ec\n  $ ish ask results a-6ec --round 1 --json")
+        .addHelpText("after", `
+Examples:
+  $ ish ask results a-6ec
+  $ ish ask results a-6ec --round 1 --json
+
+Each pick has a \`pick_confidence\` field (0..1, when --wants-pick was set) —
+the model's self-reported confidence in its variant choice. See
+\`ish docs get-page concepts/ask\` for how to use it for ranking ties.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const aid = resolveAsk(pickAskRef(id, opts.ask));
@@ -539,13 +550,18 @@ lookups.`)
         .requiredOption("--round <n|round-id>", "Round number (1-indexed) or round id/alias")
         .requiredOption("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
         .option("--redispatch-all", "Clear prior phase-1 outputs (comment, pick, ratings) and re-run the entire round from scratch (legacy behavior). Default is additive — only the new questions are answered.", false)
+        .option("--wait", "Wait until the round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
 Examples:
   # Additive (default): preserves prior picks/ratings/comments.
   $ ish ask add-questions a-6ec --round 1 --questions ./qs.json
 
+  # Wait for the round to finish before returning.
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --wait
+
   # Legacy reset: re-runs the whole round; prior picks may shift.
-  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --redispatch-all
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --redispatch-all --wait
 
 Minimal valid --questions JSON:
   [
@@ -566,6 +582,16 @@ text, slider, likert, single-choice, multiple-choice, number.`)
                 ...(opts.redispatchAll && { redispatch_all: true }),
             };
             const updated = await client.post(`/asks/${aid}/rounds/${round.id}/questions`, body);
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                await pollUntilRoundDone(client, aid, updated.order_index, timeoutMs, !!globals.quiet);
+                const refreshed = await client.get(`/asks/${aid}`);
+                const target = refreshed.rounds.find((r) => r.id === updated.id);
+                if (target) {
+                    formatRoundDetail(target, globals.json);
+                    return;
+                }
+            }
             if (!globals.json || globals.verbose) {
                 formatRoundDetail(updated, globals.json);
                 return;

package/dist/commands/profile.js

@@ -40,7 +40,12 @@ Examples:
   $ ish profile list
   $ ish profile list --search "engineer" --country US
   $ ish profile list --gender female --gender male --country US --country GB
-  $ ish profile list --type all --json`)
+  $ ish profile list --type all --json
+
+  # Pagination — default --limit is 50; iterate with --offset:
+  $ ish profile list --limit 100
+  $ ish profile list --limit 100 --offset 100   # next page
+  # When more results exist, a stderr hint surfaces the next --offset / --limit.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const params = {
@@ -63,18 +68,26 @@ Examples:
             const data = await client.get("/tester-profiles", params);
             formatTesterProfileList(data, globals.json, parseInt(opts.limit, 10));
             // Pattern H1: when there's more data, surface a stderr hint so agents
-            // know `--limit / --offset` exist without re-reading help. Only when
-            // not in JSON mode and not silenced — JSON consumers read has_more
-            // off the envelope themselves; quiet suppresses progress chatter.
-            if (!globals.json && !globals.quiet && typeof data === "object" && data !== null) {
+            // know `--limit / --offset` exist without re-reading help. Stderr only,
+            // so it doesn't pollute machine-readable stdout — that means we DON'T
+            // gate on globals.json (auto-flips on pipe and would silence the hint
+            // exactly when the agent needs it most). --quiet is the explicit
+            // opt-out for progress chatter.
+            //
+            // The raw `/tester-profiles` envelope is `{items, total, limit, offset}`
+            // — `has_more` and `returned` are synthesized client-side by `wrapList`
+            // only when the response is rendered. Compute them locally here so the
+            // hint actually fires; reading `data.has_more` directly would always
+            // see undefined and silently skip.
+            if (!globals.quietExplicit && typeof data === "object" && data !== null) {
                 const d = data;
-                if (d.has_more === true) {
-                    const total = typeof d.total === "number" ? d.total : null;
-                    const returned = typeof d.returned === "number" ? d.returned : null;
-                    const offset = typeof d.offset === "number" ? d.offset : 0;
-                    if (total !== null && returned !== null) {
-                        console.error(`\n  showing ${offset + 1}–${offset + returned} of ${total}; pass --offset ${offset + returned} --limit ${returned} for more.`);
-                    }
+                const items = Array.isArray(d.items) ? d.items : [];
+                const returned = items.length;
+                const total = typeof d.total === "number" ? d.total : returned;
+                const offset = typeof d.offset === "number" ? d.offset : parseInt(opts.offset, 10) || 0;
+                const hasMore = total > offset + returned;
+                if (hasMore && returned > 0) {
+                    console.error(`\n  showing ${offset + 1}–${offset + returned} of ${total}; pass --offset ${offset + returned} --limit ${returned} for more.`);
                 }
             }
         });

package/dist/commands/study.js

@@ -2,7 +2,7 @@
  * ish study — Manage studies.
  */
 import { readFileSync } from "node:fs";
-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 { formatStudyList, formatStudyDetail, formatStudyResults, output, ValidationError } from "../lib/output.js";
@@ -152,6 +152,8 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             // or --url is provided, so a single `study create` produces a study
             // that's immediately runnable. Without these flags the backend
             // creates zero iterations and the first `iteration create` becomes A.
+            // The backend requires a non-empty `name` on the inline iteration; we
+            // default to "A" to match the iteration-naming convention.
             let inlineIteration;
             if (opts.contentText !== undefined) {
                 if (opts.modality && opts.modality !== "text") {
@@ -160,13 +162,14 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 const text = opts.contentText.startsWith("@")
                     ? readFileSync(opts.contentText.slice(1), "utf8")
                     : opts.contentText;
-                inlineIteration = { details: { type: "text", content_text: text } };
+                inlineIteration = { name: "A", details: { type: "text", content_text: text } };
             }
             else if (opts.url !== undefined) {
                 if (opts.modality && opts.modality !== "interactive") {
                     throw new Error(`--url is only valid with --modality interactive (got "${opts.modality}").`);
                 }
                 inlineIteration = {
+                    name: "A",
                     details: { type: "interactive", url: opts.url, platform: "browser" },
                 };
             }
@@ -374,10 +377,15 @@ Examples:
         .description("Delete a study")
         .argument("<id>", "Study ID")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
-        .addHelpText("after", "\nExamples:\n  $ ish study delete <id>")
-        .action(async (id, _opts, cmd) => {
+        .option("-y, --yes", "Skip confirmation prompt (required in --json or non-TTY contexts)")
+        .addHelpText("after", "\nExamples:\n  $ ish study delete <id>           # interactive — prompts for confirmation\n  $ ish study delete <id> --yes     # non-interactive\n  $ ish study delete <id> --json --yes")
+        .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const rid = resolveId(id);
+            await confirmDestructive(`Delete study ${tagAlias(ALIAS_PREFIX.study, rid)}? This cannot be undone.`, {
+                yes: opts.yes,
+                json: globals.json,
+            });
             await client.del(`/studies/${rid}`);
             output({ id: rid, alias: tagAlias(ALIAS_PREFIX.study, rid), message: "Study deleted" }, globals.json, { writePath: true });
         });

package/dist/connect.js

@@ -5,7 +5,7 @@ import { spawn, execSync } from "node:child_process";
 import { existsSync, mkdirSync, chmodSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, saveConfig } from "./config.js";
-import { refreshTokens, isTokenExpired, decodeJwtExp } from "./auth.js";
+import { refreshTokens, isTokenExpired, decodeJwtExp, AuthRefreshPermanentError } from "./auth.js";
 import { binDir, cloudflaredBin, simulationsDir } from "./lib/paths.js";
 import { c } from "./lib/colors.js";
 const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
@@ -402,7 +402,14 @@ async function registerTunnel(apiUrl, token, tunnelUrl, port) {
         return false;
     }
 }
-async function deregisterTunnel(apiUrl, token, json) {
+/**
+ * Best-effort deregister. When `suppressAuthFailures` is true (we're already
+ * shutting down because of an auth-permanent failure), 401/403 errors during
+ * deregister are silently swallowed — logging "Failed to deregister: HTTP 401"
+ * right after telling the user their auth expired is ironic and noisy.
+ * Non-auth failures are still logged.
+ */
+async function deregisterTunnel(apiUrl, token, json, suppressAuthFailures = false) {
     try {
         const resp = await fetch(`${apiUrl}${API_BASE}/connect`, {
             method: "DELETE",
@@ -419,9 +426,28 @@ async function deregisterTunnel(apiUrl, token, json) {
         }
     }
     catch (e) {
+        if (suppressAuthFailures && /HTTP (401|403)/.test(String(e)))
+            return;
         console.error(`Warning: Failed to deregister connection: ${e}`);
     }
 }
+/**
+ * Classify whether a thrown error from the auth refresh path is permanent.
+ * Permanent = "the local config can't recover, user must `ish login` again."
+ * Examples: Supabase `refresh_token_not_found`, `invalid_grant`, any 4xx on
+ * the refresh endpoint. Network blips and 5xx are NOT permanent.
+ *
+ * The typed sentinel from `src/auth.ts` is the primary signal. We also string-
+ * match legacy error messages in case something throws a plain Error.
+ */
+function isPermanentAuthFailure(err) {
+    if (err instanceof AuthRefreshPermanentError)
+        return true;
+    if (err instanceof Error) {
+        return /refresh_token_not_found|invalid_grant|Token refresh failed \(HTTP 4\d\d/i.test(err.message);
+    }
+    return false;
+}
 function processHeartbeatResponse(resp, renderCards) {
     resp.json().then((data) => {
         const sims = data.simulations ?? [];
@@ -437,7 +463,7 @@ function processHeartbeatResponse(resp, renderCards) {
         // Non-fatal: response parsing failed, silently continue
     });
 }
-function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal, json) {
+function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal, onAuthPermanent, json) {
     let consecutiveFailures = 0;
     let stopped = false;
     const interval = setInterval(async () => {
@@ -469,6 +495,15 @@ function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal,
                     return;
                 }
                 catch (refreshErr) {
+                    // Permanent refresh failure (refresh_token_not_found etc.) — no
+                    // amount of retrying will fix this. Bail out immediately with an
+                    // actionable message; don't waste the 3-strike countdown.
+                    if (isPermanentAuthFailure(refreshErr)) {
+                        stopped = true;
+                        clearInterval(interval);
+                        await onAuthPermanent(refreshErr);
+                        return;
+                    }
                     console.error(`Token refresh failed: ${refreshErr}`);
                 }
             }
@@ -499,7 +534,7 @@ function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal,
  * Schedule a proactive token refresh before the JWT expires.
  * Refreshes 10 minutes before expiry.
  */
-function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, json) {
+function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, onAuthPermanent, json) {
     if (!doRefresh)
         return { stop: () => { } };
     const exp = decodeJwtExp(token);
@@ -516,9 +551,15 @@ function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, json) {
             if (!json)
                 console.error("Token proactively refreshed.");
             // Schedule next refresh for the new token
-            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed, json);
+            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed, onAuthPermanent, json);
         }
         catch (e) {
+            // Permanent refresh failure: short-circuit to the actionable message
+            // path instead of letting the next heartbeat eat 3 strikes.
+            if (isPermanentAuthFailure(e)) {
+                await onAuthPermanent(e);
+                return;
+            }
             console.error(`Proactive token refresh failed: ${e}`);
         }
     }, delay);
@@ -572,20 +613,54 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         console.log(`Tunnel URL: ${tunnelUrl} → http://localhost:${port}\n`);
     }
     let shuttingDown = false;
-    const heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
+    // Holders for forward references — `onAuthPermanent` needs to stop these
+    // timers, but `startHeartbeat`/`scheduleProactiveRefresh` need
+    // `onAuthPermanent` to wire up. Declared as nullable, assigned just below.
+    let heartbeat = null;
+    let proactiveRefresh = null;
+    // Fast-fail path for non-recoverable auth failures (e.g. Supabase
+    // refresh_token_not_found). Skips the 3-strike heartbeat countdown and
+    // gives the user a single actionable next step.
+    const onAuthPermanent = async (cause) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        heartbeat?.stop();
+        proactiveRefresh?.stop();
+        if (json) {
+            console.error(JSON.stringify({
+                status: "auth_expired",
+                message: `Authentication expired. Run \`ish login\` and re-run \`ish connect ${port}\`.`,
+                detail: "refresh_token expired or revoked; the local config can't recover",
+            }));
+        }
+        else {
+            console.error(`\nAuthentication expired. Run \`ish login\` and re-run \`ish connect ${port}\`.`);
+            console.error("(refresh_token expired or revoked; the local config can't recover)");
+        }
+        if (cause instanceof Error && cause.message) {
+            // Keep the underlying detail discoverable for log scrapers / agents,
+            // without making it the headline.
+            console.error(`Cause: ${cause.message}`);
+        }
+        await deregisterTunnel(apiUrl, currentToken, json, true);
+        cfProcess.kill();
+        process.exit(3);
+    };
+    heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
         await deregisterTunnel(apiUrl, currentToken, json);
         cfProcess.kill();
         process.exit(1);
-    }, json);
-    const proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed, json);
+    }, onAuthPermanent, json);
+    proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed, onAuthPermanent, json);
     const shutdown = async () => {
         if (shuttingDown)
             process.exit(1);
         shuttingDown = true;
         if (!json)
             console.error("\nShutting down...");
-        heartbeat.stop();
-        proactiveRefresh.stop();
+        heartbeat?.stop();
+        proactiveRefresh?.stop();
         cfProcess.kill();
         await deregisterTunnel(apiUrl, currentToken, json);
         process.exit(0);
@@ -597,8 +672,8 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
     }
     cfProcess.on("exit", async () => {
         if (!shuttingDown) {
-            heartbeat.stop();
-            proactiveRefresh.stop();
+            heartbeat?.stop();
+            proactiveRefresh?.stop();
             await deregisterTunnel(apiUrl, currentToken, json);
             process.exit(0);
         }

package/dist/index.js

@@ -69,7 +69,10 @@ program
     .option("--token-file <path>", "Read auth token from a file (preferred over --token / ISH_TOKEN)")
     .option("--api-url <url>", "Backend API URL (default: ISH_API_URL or https://api.ishlabs.io)")
     .addOption(new Option("--dev", "Use local dev API (http://localhost:8000)").hideHelp())
+    .option("--workspace <id>", "Default workspace ID; per-subcommand --workspace overrides")
     .option("--json", "Output as JSON (auto-enabled when piped)")
+    .option("--get <field>", "Extract a single field from the JSON response and print only its value (implies --json internally; supports dotted paths e.g. tester_profile.name)")
+    .option("--human", "Force human-readable output even when stdout is piped (overrides JSON-when-piped auto-detection)")
     .option("--fields <fields>", "Comma-separated fields to include in JSON output (e.g. alias,name,status)")
     .option("--verbose", "Include full UUIDs and timestamps in JSON output")
     .option("--no-color", "Disable colored output (also honored: NO_COLOR env var)")

package/dist/lib/command-helpers.d.ts

@@ -58,6 +58,33 @@ export interface GlobalOpts {
     quiet: boolean;
     color: boolean;
     fields?: string[];
+    /**
+     * --get <field>: capture mode. Extracts a single field from the JSON
+     * response and prints its bare value. Implies --json internally so the
+     * renderer always has structured data to extract from.
+     */
+    get?: string;
+    /**
+     * --human: forces the human renderer regardless of TTY/pipe state.
+     * Mutually exclusive with --get (capture vs display).
+     */
+    human?: boolean;
+    /**
+     * Program-level --workspace from the root flag. Subcommand-level --workspace
+     * still wins via Commander's optsWithGlobals merge (subcommand opts override
+     * parent), so this is effectively the "default workspace for the invocation"
+     * agents reflexively pass at the program root.
+     */
+    workspace?: string;
+    /**
+     * True only when the user explicitly passed `--quiet` / `-q` (or `--get`).
+     * Distinct from `quiet`, which also flips on for auto-quiet (the
+     * piped-stdout/auto-JSON path). Use this for actionable hints (e.g. the
+     * `profile list` pagination hint) that should still surface when an agent
+     * pipes output but hasn't asked for silence — auto-quiet is for progress
+     * chatter, not diagnostic signals.
+     */
+    quietExplicit: boolean;
 }
 export declare function getGlobals(cmd: Command): GlobalOpts;
 /**
@@ -83,6 +110,16 @@ export declare function runInline(cmd: Command, fn: (globals: GlobalOpts) => Pro
 export declare function getWebUrl(globals: GlobalOpts, path: string): string;
 export declare function terminalLink(url: string, text: string): string;
 export declare function readJsonFileOrStdin(filePath?: string): Promise<unknown>;
+/**
+ * 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 declare function confirmDestructive(prompt: string, opts: {
+    yes?: boolean;
+    json?: boolean;
+}): Promise<void>;
 export declare function resolveWorkspace(explicit?: string): string;
 export declare function resolveStudy(explicit?: string): string;
 export declare function resolveAsk(explicit?: string): string;