@ishlabs/cli 0.8.5 → 0.10.0

package/dist/lib/command-helpers.js

@@ -45,6 +45,77 @@ function describeFilters(flags) {
         parts.push(`--visibility ${flags.visibility}`);
     return parts.join(" ");
 }
+/**
+ * Best-effort: surface the top-3 populated countries so an empty-audience
+ * error doesn't strand the agent without a pivot. Two tiers — tier 1 keeps
+ * non-country filters and drops `--country` (used when `--country` was the
+ * binding constraint); tier 2 fires when tier 1 returns empty (or when
+ * `--country` wasn't set at all) and drops every filter so the workspace's
+ * overall country distribution is the fallback. Returns the empty string on
+ * any failure — never replaces the primary error with a secondary one.
+ */
+async function suggestCountries(client, workspace, flags, opts) {
+    const countOf = (items) => {
+        const counts = new Map();
+        for (const p of items) {
+            const c = typeof p.country === "string" ? p.country : null;
+            if (c)
+                counts.set(c, (counts.get(c) ?? 0) + 1);
+        }
+        return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3);
+    };
+    const fetchFacet = async (keepOtherFilters) => {
+        try {
+            const broader = {
+                product_id: workspace,
+                type: "ai",
+                limit: "500",
+                offset: "0",
+            };
+            if (keepOtherFilters) {
+                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 data = await client.get("/tester-profiles", broader);
+            const items = Array.isArray(data)
+                ? data
+                : Array.isArray(data?.items)
+                    ? data.items
+                    : [];
+            const pool = opts.requireSimulatable ? items.filter(isSimulatable) : items;
+            return countOf(pool);
+        }
+        catch {
+            return [];
+        }
+    };
+    const countrySet = !!(flags.country && flags.country.length > 0);
+    // Tier 1: when --country is set, drop just country and keep other filters.
+    // When --country isn't set, skip straight to the unfiltered fallback —
+    // tier 1 with `keepOtherFilters=false` would re-issue the same query that
+    // already returned 0.
+    let top = [];
+    let label = "Populated countries";
+    if (countrySet) {
+        top = await fetchFacet(true);
+        label = "Populated countries with these other filters";
+    }
+    if (top.length === 0) {
+        top = await fetchFacet(false);
+        label = "Populated countries";
+    }
+    if (top.length === 0)
+        return "";
+    return ` ${label}: ${top.map(([c, n]) => `${c} (${n})`).join(", ")}.`;
+}
 function hasFilterFlag(flags) {
     return Boolean(flags.search
         || (flags.gender && flags.gender.length > 0)
@@ -129,56 +200,18 @@ 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.
-            }
-        }
+        // Country suggestion: surface the top populated countries so the agent
+        // doesn't have to round-trip through `ish profile list` to find one that
+        // matches. Two tiers — tier 1 drops `--country` only and retains other
+        // filters when `--country` was set (so the hint reflects "of countries
+        // that match your other filters, here are the populated ones"). Tier 2
+        // fires when tier 1 returns nothing *and* tier 1 was scoped, or when
+        // `--country` wasn't the constraint to begin with: drop every filter and
+        // surface the workspace's overall country distribution. Pure best-effort
+        // — any failure falls back to the original error.
+        const suggestion = await suggestCountries(client, workspace, flags, {
+            requireSimulatable: !!opts.requireSimulatable,
+        });
         if (filterDesc) {
             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.`);
         }
@@ -315,6 +348,20 @@ export function exitCodeFromError(err) {
         // Client-side validation failures
         if (err.name === "ValidationError" || /^invalid |^cannot read |is empty:|--\w[\w-]* must be|pick an audience|use either /i.test(err.message))
             return 2;
+        // Errors that pre-declare their own retryability / error_code take
+        // precedence — WaitTimeoutError sets `error_code: "wait_timeout"`
+        // and `retryable: true`, so callers can branch on exit 5 (transient)
+        // distinct from the api-client's generic 408/timeout family.
+        const tagged = err;
+        if (tagged.error_code === "wait_timeout")
+            return 5;
+        if (typeof tagged.retryable === "boolean" && tagged.retryable)
+            return 5;
+        // Structured error_kind on the Error object (set by chat endpoint test/init,
+        // simulation routes, etc.). TunnelInactive is the canonical transient one.
+        const kind = err.error_kind;
+        if (typeof kind === "string" && kind === "TunnelInactive")
+            return 5;
     }
     return 1;
 }
@@ -406,6 +453,18 @@ export function readJsonFileOrStdin(filePath) {
         process.stdin.on("error", reject);
     });
 }
+/**
+ * Build the suggested re-invocation example by taking the live argv and
+ * appending `--yes` if it isn't already there. Strips the `node` /
+ * `dist/index.js` prefix so the example reads as a normal `ish` command.
+ */
+function buildConfirmationExample() {
+    const argv = process.argv.slice(2);
+    const args = argv.includes("--yes") || argv.includes("-y")
+        ? argv
+        : [...argv, "--yes"];
+    return ["ish", ...args].join(" ");
+}
 /**
  * Prompt for confirmation of a destructive action, or short-circuit when
  * `--yes` is set. In `--json` mode without `--yes` we refuse with a usage
@@ -418,11 +477,15 @@ export async function confirmDestructive(prompt, opts) {
     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";
+        err.error_kind = "ConfirmationRequired";
+        err.example = buildConfirmationExample();
         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";
+        err.error_kind = "ConfirmationRequired";
+        err.example = buildConfirmationExample();
         throw err;
     }
     process.stderr.write(`${prompt} [y/N] `);
@@ -453,6 +516,23 @@ export async function confirmDestructive(prompt, opts) {
         throw err;
     }
 }
+/**
+ * Construct a structured "no active <thing>" Error so the JSON envelope from
+ * `outputError` carries `error_code` + `suggestions` rather than a generic
+ * `client_error`. Pattern A (Sprint 2): when the active study/workspace
+ * evaporates between commands, agents need to branch on the error code, not
+ * scrape prose. Without this, downstream modality validation in
+ * `iteration create` would surface a misleading "Image iterations require
+ * --image-urls" message instead of the real "no active study" cause.
+ */
+function noActiveContextError(message, errorCode, suggestions) {
+    const err = new Error(message);
+    err.name = "NoActiveContextError";
+    err.error_code = errorCode;
+    err.retryable = false;
+    err.suggestions = suggestions;
+    return err;
+}
 export function resolveWorkspace(explicit) {
     if (explicit)
         return resolveId(explicit);
@@ -467,7 +547,10 @@ export function resolveWorkspace(explicit) {
     const config = loadConfig();
     if (config.workspace)
         return config.workspace;
-    throw new Error('No workspace set. Use `ish workspace use <alias>` or pass --workspace.');
+    throw noActiveContextError('No active workspace. Run `ish workspace use <workspace-id>` or pass --workspace <id>.', "no_active_workspace", [
+        "ish workspace list",
+        "ish workspace use <workspace-id>",
+    ]);
 }
 export function resolveStudy(explicit) {
     if (explicit)
@@ -478,7 +561,10 @@ export function resolveStudy(explicit) {
     const config = loadConfig();
     if (config.study)
         return config.study;
-    throw new Error('No study set. Use `ish study use <alias>` or pass --study.');
+    throw noActiveContextError('No active study. Run `ish study use <study-id>` or pass --study <id>.', "no_active_study", [
+        "ish study use <study-id>",
+        "ish iteration create --study <study-id> ...",
+    ]);
 }
 export function resolveAsk(explicit) {
     if (explicit)
@@ -489,7 +575,28 @@ export function resolveAsk(explicit) {
     const config = loadConfig();
     if (config.ask)
         return config.ask;
-    throw new Error('No ask set. Use `ish ask use <alias>` or pass the ask ID as an argument.');
+    throw noActiveContextError('No active ask. Run `ish ask use <ask-id>` or pass the ask ID as an argument.', "no_active_ask", [
+        "ish ask list",
+        "ish ask use <ask-id>",
+    ]);
+}
+/**
+ * Resolve a chat endpoint id from (in order): the positional argument, the
+ * `--endpoint <id>` flag, the `ISH_CHAT_ENDPOINT` env var, or the active
+ * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
+ */
+export function resolveChatEndpoint(positional, flag) {
+    if (positional)
+        return resolveId(positional);
+    if (flag)
+        return resolveId(flag);
+    const env = process.env.ISH_CHAT_ENDPOINT;
+    if (env)
+        return resolveId(env);
+    const config = loadConfig();
+    if (config.chat_endpoint)
+        return config.chat_endpoint;
+    throw new Error('No chat endpoint set. Use `ish chat endpoint use <id>`, pass the endpoint id, or set --endpoint.');
 }
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export function collectRepeatable(value, prev = []) {
@@ -538,6 +645,34 @@ const WORKSPACE_SCOPED_GROUPS = new Set([
  * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
  * unused values.
  */
+/**
+ * Read a `--*-config <file>` style flag value, treating "-" as "read from
+ * stdin" and any other value as a file path on disk. Trailing newlines on
+ * stdin input are stripped so the resulting string parses cleanly as JSON.
+ *
+ * Throws when "-" is passed but stdin is a TTY (no upstream pipe).
+ *
+ * Mirrors the readSecretFlag pattern in src/commands/workspace.ts; extracted
+ * so every `--<x>-config <file>` flag across commands shares one
+ * implementation.
+ */
+export async function readFileOrStdin(path) {
+    if (path === "-") {
+        if (process.stdin.isTTY) {
+            throw new Error('Use "-" only when piping the value on stdin.');
+        }
+        return await new Promise((resolve, reject) => {
+            let data = "";
+            process.stdin.setEncoding("utf-8");
+            process.stdin.on("data", (chunk) => {
+                data += chunk;
+            });
+            process.stdin.on("end", () => resolve(data.replace(/\r?\n$/, "")));
+            process.stdin.on("error", reject);
+        });
+    }
+    return fs.readFileSync(path, "utf-8");
+}
 export function injectGlobalWorkspaceOption(program) {
     const walk = (cmd) => {
         if (cmd.commands.length === 0) {