@ishlabs/cli 0.8.1 → 0.8.3

package/dist/lib/command-helpers.js

@@ -7,8 +7,160 @@ 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 { setColorsEnabled, colorsEnabled } from "./colors.js";
 import { loadConfig } from "../config.js";
 import { resolveId } from "./alias-store.js";
+function isSimulatable(p) {
+    return Boolean(p.simulation_config_id) || Boolean(p.simulation_config);
+}
+function shuffleInPlace(arr) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+}
+function parseSampleSize(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = parseInt(raw, 10);
+    if (Number.isNaN(n) || n <= 0) {
+        throw new Error(`--sample must be a positive integer, got "${raw}".`);
+    }
+    return n;
+}
+function describeFilters(flags) {
+    const parts = [];
+    if (flags.search)
+        parts.push(`--search "${flags.search}"`);
+    if (flags.gender?.length)
+        parts.push(...flags.gender.map((g) => `--gender ${g}`));
+    if (flags.country?.length)
+        parts.push(...flags.country.map((c) => `--country ${c}`));
+    if (flags.minAge)
+        parts.push(`--min-age ${flags.minAge}`);
+    if (flags.maxAge)
+        parts.push(`--max-age ${flags.maxAge}`);
+    if (flags.visibility)
+        parts.push(`--visibility ${flags.visibility}`);
+    return parts.join(" ");
+}
+function hasFilterFlag(flags) {
+    return Boolean(flags.search
+        || (flags.gender && flags.gender.length > 0)
+        || (flags.country && flags.country.length > 0)
+        || flags.minAge
+        || flags.maxAge
+        || flags.visibility);
+}
+/** True when any audience-selection flag is set on the command. */
+export function hasAudienceFlags(flags) {
+    return Boolean((flags.profile && flags.profile.length > 0)
+        || flags.sample !== undefined
+        || flags.all
+        || hasFilterFlag(flags));
+}
+/**
+ * Resolve a tester-profile audience from CLI flags.
+ *
+ * Modes (mutually exclusive):
+ *   - explicit: `--profile <id>` (repeatable) — returns those IDs verbatim.
+ *   - sample:   `--sample N` + optional filter flags — fetches the matching
+ *               pool, randomly samples N.
+ *   - all:      caller's "all" flag + optional filter flags — returns every
+ *               matching profile.
+ *   - filtered: filter flags only — treated as "all matching".
+ *
+ * Always sends `type=ai` to the backend (simulations are AI-driven).
+ * If `requireSimulatable`, applies a client-side filter for profiles that
+ * have a simulation config attached.
+ */
+export async function resolveAudienceProfileIds(client, workspace, flags, opts = {}) {
+    const allFlagName = opts.allFlagName ?? "--all";
+    const explicit = (flags.profile ?? []).map(resolveId);
+    const sampleN = parseSampleSize(flags.sample);
+    const filtersUsed = hasFilterFlag(flags);
+    if (explicit.length > 0) {
+        if (sampleN !== undefined || flags.all || filtersUsed) {
+            throw new Error(`Use either explicit --profile flags or --sample/${allFlagName}/filter flags (--country, --gender, --min-age, --max-age, --search, --visibility), not both.`);
+        }
+        return explicit;
+    }
+    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).`);
+    }
+    const params = {
+        product_id: workspace,
+        type: "ai",
+        limit: "200",
+        offset: "0",
+    };
+    if (flags.search)
+        params.search = flags.search;
+    if (flags.gender && flags.gender.length > 0)
+        params.gender = flags.gender;
+    if (flags.country && flags.country.length > 0)
+        params.country = flags.country;
+    if (flags.minAge)
+        params.min_age = flags.minAge;
+    if (flags.maxAge)
+        params.max_age = flags.maxAge;
+    if (flags.visibility)
+        params.visibility = flags.visibility;
+    const data = await client.get("/tester-profiles", params);
+    const items = Array.isArray(data)
+        ? data
+        : Array.isArray(data?.items)
+            ? data.items
+            : [];
+    let pool = items;
+    if (opts.requireSimulatable) {
+        pool = pool.filter(isSimulatable);
+    }
+    if (opts.excludeProfileIds && opts.excludeProfileIds.size > 0) {
+        pool = pool.filter((p) => !opts.excludeProfileIds.has(p.id));
+    }
+    if (pool.length === 0) {
+        const filterDesc = describeFilters(flags);
+        const sim = opts.requireSimulatable ? "simulatable AI " : "AI ";
+        if (opts.excludeProfileIds && opts.excludeProfileIds.size > 0 && !filterDesc) {
+            throw new Error("All matching profiles are already in this audience.");
+        }
+        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 found in workspace ${workspace}.${opts.requireSimulatable ? " Create profiles with simulation configs first." : ""}`);
+    }
+    if (flags.all)
+        return pool.map((p) => p.id);
+    if (sampleN !== undefined) {
+        if (sampleN > pool.length) {
+            throw new Error(`--sample ${sampleN} requested but only ${pool.length} matching profile${pool.length === 1 ? "" : "s"} available.`);
+        }
+        return shuffleInPlace([...pool]).slice(0, sampleN).map((p) => p.id);
+    }
+    // Filters only, no --sample/--all → return every match.
+    return pool.map((p) => p.id);
+}
+/**
+ * Attach the audience-selection flag set to a Commander command.
+ * Pass `allFlagName: "--all-simulatable"` for ask commands to keep the
+ * established flag name; defaults to `--all` for study run.
+ */
+export function addAudienceFilterFlags(cmd, opts = {}) {
+    const allFlag = opts.allFlagName ?? "--all";
+    const allDesc = opts.allFlagDescription ?? "Use every profile matching the filters";
+    return cmd
+        .option("--profile <ids>", "Tester profile IDs/aliases (comma-separated or repeatable)", collectIds, [])
+        .option("--sample <N>", "Randomly sample N profiles from the matching pool")
+        .option(allFlag, allDesc)
+        .option("--search <text>", "Free-text search (matches profile name and bio)")
+        .option("--gender <gender>", "Filter by gender (repeatable)", collectRepeatable, [])
+        .option("--country <code>", "Filter by 2-letter country code (repeatable)", collectRepeatable, [])
+        .option("--min-age <n>", "Minimum age (inclusive)")
+        .option("--max-age <n>", "Maximum age (inclusive)")
+        .option("--visibility <v>", "Filter by visibility (private|public)");
+}
 export function getGlobals(cmd) {
     const opts = cmd.optsWithGlobals();
     // Auto-switch to JSON when stdout is piped (non-TTY)
@@ -17,16 +169,28 @@ export function getGlobals(cmd) {
     const fields = opts.fields
         ? String(opts.fields).split(",").map((f) => f.trim()).filter(Boolean)
         : undefined;
+    // Commander's negatable boolean: --no-color sets color=false, default is undefined.
+    // Fall back to the env-aware default from colors.ts.
+    const color = opts.color === false ? false : (json ? false : colorsEnabled());
     return {
         token: opts.token,
+        tokenFile: opts.tokenFile,
         apiUrl: opts.apiUrl,
         dev: opts.dev,
         json,
         verbose: opts.verbose ?? false,
         quiet: opts.quiet ?? (json && !opts.json), // auto-quiet when auto-json via pipe
+        color,
         fields,
     };
 }
+/**
+ * Semantic exit codes used across the CLI.
+ * 0=success, 1=general error, 2=usage/validation, 3=auth, 4=not found, 5=transient.
+ * `EXIT_USAGE` matches the POSIX convention for argv/usage errors and is
+ * what `program.exitOverride()` returns from Commander-level failures.
+ */
+export const EXIT_USAGE = 2;
 /**
  * Map errors to semantic exit codes.
  * 0=success, 1=general, 2=usage/validation, 3=auth, 4=not found, 5=transient
@@ -42,20 +206,29 @@ export function exitCodeFromError(err) {
         if (err.retryable)
             return 5;
     }
-    // Auth-related client errors (e.g. missing token)
-    if (err instanceof Error && /no auth token found|run "ish login"|saved token is invalid|session expired/i.test(err.message))
-        return 3;
+    if (err instanceof Error) {
+        // Auth-related client errors (e.g. missing token)
+        if (/no auth token found|run "ish login"|saved token is invalid|session expired/i.test(err.message))
+            return 3;
+        // 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;
+    }
     return 1;
 }
 export async function createClient(globals) {
     const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
-    const token = await resolveToken(globals.token, apiUrl);
+    const token = await resolveToken(globals.token, apiUrl, globals.tokenFile);
     return new ApiClient({ apiUrl, token });
 }
-export async function withClient(cmd, fn) {
-    const globals = getGlobals(cmd);
+function applyGlobals(globals) {
     setVerbose(globals.verbose);
     setFields(globals.fields);
+    setColorsEnabled(globals.color);
+}
+export async function withClient(cmd, fn) {
+    const globals = getGlobals(cmd);
+    applyGlobals(globals);
     try {
         const client = await createClient(globals);
         await fn(client, globals);
@@ -65,6 +238,22 @@ export async function withClient(cmd, fn) {
         process.exit(exitCodeFromError(err));
     }
 }
+/**
+ * Wrap an inline (non-API) command action with the same uniform error
+ * formatting + exit codes used by withClient. Use this for actions that
+ * don't need an ApiClient — login, logout, connect, etc.
+ */
+export async function runInline(cmd, fn) {
+    const globals = getGlobals(cmd);
+    applyGlobals(globals);
+    try {
+        await fn(globals);
+    }
+    catch (err) {
+        outputError(err, globals.json);
+        process.exit(exitCodeFromError(err));
+    }
+}
 export function getWebUrl(globals, path) {
     const base = globals.dev ? "http://localhost:3000" : getAppUrl();
     return `${base}${path}`;
@@ -129,3 +318,40 @@ export function resolveStudy(explicit) {
         return config.study;
     throw new Error('No study set. Use `ish study use <alias>` or pass --study.');
 }
+export function resolveAsk(explicit) {
+    if (explicit)
+        return resolveId(explicit);
+    const env = process.env.ISH_ASK;
+    if (env)
+        return resolveId(env);
+    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.');
+}
+/** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
+export function collectRepeatable(value, prev = []) {
+    return prev.concat([value]);
+}
+/**
+ * Commander collector for ID-list flags. Accepts a comma-separated value
+ * (`--profile a,b,c`) and also concatenates across repeated flags
+ * (`--profile a --profile b`). Trims whitespace and drops empty entries.
+ *
+ * Use this for flags whose values are IDs/aliases — never for free-form
+ * strings that may legitimately contain commas (those should use
+ * `collectRepeatable`).
+ */
+export function collectIds(value, prev = []) {
+    return prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean));
+}
+/** Parse a `--timeout <seconds>` flag into milliseconds, with validation. */
+export function parseWaitTimeout(raw, defaultMs = 5 * 60 * 1000) {
+    if (raw === undefined)
+        return defaultMs;
+    const n = parseInt(raw, 10);
+    if (Number.isNaN(n) || n <= 0) {
+        throw new Error(`--timeout must be a positive integer (seconds), got "${raw}".`);
+    }
+    return n * 1000;
+}

package/dist/lib/docs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ish docs — In-binary documentation aimed at AI coding agents.
+ *
+ * Pages ship as TypeScript string constants so they survive both the `tsc`
+ * build and the `bun build --compile` single-binary build. Slugs use
+ * forward-slashes so the surface mirrors a doc tree (`concepts/study`).
+ */
+export interface DocPage {
+    slug: string;
+    title: string;
+    /** One-line description shown in `ish docs list` and search. */
+    description: string;
+    body: string;
+}
+export declare function listPages(): DocPage[];
+export declare function getPage(slug: string): DocPage | undefined;
+/** Concise pointer printed at the bottom of `--help` outputs. */
+export declare const AGENT_HELP_FOOTER: string;
+export interface SearchHit {
+    slug: string;
+    title: string;
+    description: string;
+    /** Highest-scoring match snippet, max ~200 chars. */
+    snippet: string;
+    score: number;
+}
+/**
+ * Substring search over title + description + body. Title hits score
+ * highest, then description, then body. Returns at most `limit` hits
+ * sorted by score desc.
+ */
+export declare function searchPages(query: string, limit?: number): SearchHit[];