@ishlabs/cli 0.8.4 → 0.9.0

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";
@@ -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,8 +200,20 @@ 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.");
         }
+        // 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}. 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 +248,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 +308,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 +356,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 +389,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 +439,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);