@ishlabs/cli 0.8.3 → 0.8.5

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;
@@ -100,3 +137,17 @@ export declare function collectRepeatable(value: string, prev?: string[]): strin
 export declare function collectIds(value: string, prev?: string[]): string[];
 /** Parse a `--timeout <seconds>` flag into milliseconds, with validation. */
 export declare function parseWaitTimeout(raw: string | undefined, defaultMs?: number): number;
+/**
+ * Inject `--workspace <id>` on every leaf subcommand under the workspace-scoped
+ * groups that doesn't already declare it. Run once after all `registerXxxCommands`
+ * calls have populated the program tree. Agents reflexively pass `--workspace`
+ * on any command — without this, Commander rejects it with a generic "unknown
+ * option" on read-side commands like `ask delete`, `ask get`, `study get`,
+ * `profile get`, etc.
+ *
+ * The injected option is documentation-only on commands where the workspace is
+ * inferred from an ID alias; it's accepted and then discarded by the action
+ * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
+ * unused values.
+ */
+export declare function injectGlobalWorkspaceOption(program: Command): void;

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";
@@ -86,6 +86,9 @@ export async function resolveAudienceProfileIds(client, workspace, flags, opts =
         }
         return explicit;
     }
+    if (sampleN !== undefined && flags.all) {
+        throw new Error(`Use either --sample <N> or ${allFlagName}, not both. --sample picks a random subset; ${allFlagName} returns every match.`);
+    }
     if (sampleN === undefined && !flags.all && !filtersUsed) {
         throw new Error(`Pick an audience: pass --profile <id> (repeatable), --sample <N>, ${allFlagName}, or filter flags (--country, --gender, --min-age, --max-age, --search, --visibility).`);
     }
@@ -126,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." : ""}`);
     }
@@ -162,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)
@@ -179,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,
     };
 }
 /**
@@ -221,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);
@@ -245,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);
     }
@@ -296,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);
@@ -355,3 +517,40 @@ export function parseWaitTimeout(raw, defaultMs = 5 * 60 * 1000) {
     }
     return n * 1000;
 }
+/** Top-level command groups whose subcommands should accept `--workspace`. */
+const WORKSPACE_SCOPED_GROUPS = new Set([
+    "ask",
+    "study",
+    "iteration",
+    "profile",
+    "source",
+]);
+/**
+ * Inject `--workspace <id>` on every leaf subcommand under the workspace-scoped
+ * groups that doesn't already declare it. Run once after all `registerXxxCommands`
+ * calls have populated the program tree. Agents reflexively pass `--workspace`
+ * on any command — without this, Commander rejects it with a generic "unknown
+ * option" on read-side commands like `ask delete`, `ask get`, `study get`,
+ * `profile get`, etc.
+ *
+ * The injected option is documentation-only on commands where the workspace is
+ * inferred from an ID alias; it's accepted and then discarded by the action
+ * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
+ * unused values.
+ */
+export function injectGlobalWorkspaceOption(program) {
+    const walk = (cmd) => {
+        if (cmd.commands.length === 0) {
+            const hasWorkspace = cmd.options.some((o) => o.long === "--workspace");
+            if (!hasWorkspace) {
+                cmd.option("--workspace <id>", "Workspace ID; accepted for consistency (inferred from alias / active context)");
+            }
+        }
+        for (const sub of cmd.commands)
+            walk(sub);
+    };
+    for (const top of program.commands) {
+        if (WORKSPACE_SCOPED_GROUPS.has(top.name()))
+            walk(top);
+    }
+}