@ishlabs/cli 0.8.1 → 0.8.2

package/dist/lib/ask-variants.js

@@ -0,0 +1,236 @@
+/**
+ * Parse `--variant` flags and `--variants <manifest.json>` into AskVariantInput[],
+ * uploading any local files to the asks variant-upload endpoint along the way.
+ *
+ * Flag form: `--variant <kind>:<value>[::label=<label>]`
+ *   text:"hello"                       → literal text
+ *   text:@./body.md                    → text loaded from file
+ *   ./logo.png                         → media; kind inferred from MIME
+ *   image:./logo.png                   → media; kind override
+ *   ./hero.png::label=B                → media with label
+ *
+ * Manifest form (--variants ./manifest.json): JSON array of
+ *   { kind: "text"|"image"|..., label?: string, content?: string, file?: string }
+ *   - kind="text": `content` holds the literal text (or `file` to load text from disk).
+ *   - kind=media:  `file` is a local path to upload, or `content` is an already-uploaded file_path.
+ */
+import { readFile, readFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { basename, resolve as resolvePath } from "node:path";
+import { detectMimeType, validateFile } from "./upload.js";
+import { ASK_VARIANT_KINDS } from "./types.js";
+const readFileAsync = promisify(readFile);
+const KIND_BY_MIME_PREFIX = [
+    [/^image\//, "image"],
+    [/^audio\//, "audio"],
+    [/^video\//, "video"],
+    [/^application\/pdf$/, "document"],
+    [/^application\/(msword|vnd\.ms-|vnd\.openxmlformats-)/, "document"],
+    [/^text\//, "document"],
+];
+function inferKindFromMime(mime) {
+    for (const [re, kind] of KIND_BY_MIME_PREFIX) {
+        if (re.test(mime))
+            return kind;
+    }
+    return undefined;
+}
+/** Strip a trailing `::label=...` suffix off a flag value, returning {value, label?}. */
+function splitLabelSuffix(raw) {
+    const idx = raw.lastIndexOf("::");
+    if (idx === -1)
+        return { value: raw };
+    const tail = raw.slice(idx + 2);
+    const m = /^label=(.*)$/i.exec(tail);
+    if (!m)
+        return { value: raw };
+    return { value: raw.slice(0, idx), label: m[1] };
+}
+const KIND_PREFIXES = ASK_VARIANT_KINDS;
+/** Parse a single `--variant` flag value. */
+export function parseVariantFlag(raw) {
+    if (!raw || !raw.trim()) {
+        throw new Error("Empty --variant value.");
+    }
+    const { value, label } = splitLabelSuffix(raw);
+    // Check for explicit kind prefix `text:`, `image:`, etc.
+    let explicitKind;
+    let body = value;
+    for (const k of KIND_PREFIXES) {
+        if (value.startsWith(`${k}:`)) {
+            explicitKind = k;
+            body = value.slice(k.length + 1);
+            break;
+        }
+    }
+    if (explicitKind === "text") {
+        if (body.startsWith("@")) {
+            const fp = body.slice(1);
+            if (!fp)
+                throw new Error("Missing file path after `text:@`.");
+            let text;
+            try {
+                text = readFileSync(resolvePath(fp), "utf-8");
+            }
+            catch {
+                throw new Error(`Cannot read text file: ${fp}`);
+            }
+            return { kind: "text", label, source: text, needsUpload: false };
+        }
+        return { kind: "text", label, source: body, needsUpload: false };
+    }
+    // Media (explicit or inferred). Body is a file path.
+    const path = body;
+    if (!path)
+        throw new Error(`--variant ${value}: missing file path.`);
+    // Resolve kind: explicit override wins, else infer from MIME.
+    let kind = explicitKind;
+    if (!kind) {
+        const mime = detectMimeType(path);
+        kind = inferKindFromMime(mime);
+        if (!kind) {
+            throw new Error(`Cannot infer variant kind from file: ${path}. ` +
+                `Use an explicit prefix like image:${path} or document:${path}.`);
+        }
+    }
+    return { kind, label, source: path, needsUpload: true };
+}
+export function parseVariantFlags(flags) {
+    return flags.map(parseVariantFlag);
+}
+/** Load a JSON manifest (an array of variant entries) from disk. */
+export function loadVariantManifest(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(resolvePath(filePath), "utf-8");
+    }
+    catch {
+        throw new Error(`Cannot read variants manifest: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in variants manifest: ${filePath}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(`Variants manifest must be a non-empty JSON array: ${filePath}`);
+    }
+    const out = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const entry = parsed[i];
+        const kind = entry.kind;
+        if (!kind || !ASK_VARIANT_KINDS.includes(kind)) {
+            throw new Error(`variants[${i}].kind must be one of ${ASK_VARIANT_KINDS.join(", ")}.`);
+        }
+        if (kind === "text") {
+            let text = entry.content;
+            if (entry.file) {
+                try {
+                    text = readFileSync(resolvePath(entry.file), "utf-8");
+                }
+                catch {
+                    throw new Error(`Cannot read text file referenced in variants[${i}].file: ${entry.file}`);
+                }
+            }
+            if (text === undefined || text === "") {
+                throw new Error(`variants[${i}] (text): provide either "content" or "file".`);
+            }
+            out.push({ kind: "text", label: entry.label, source: text, needsUpload: false });
+            continue;
+        }
+        if (entry.file) {
+            out.push({ kind, label: entry.label, source: entry.file, needsUpload: true });
+            continue;
+        }
+        if (entry.content) {
+            // Treat as already-uploaded file_path or content URL — pass through.
+            out.push({ kind, label: entry.label, source: entry.content, needsUpload: false });
+            continue;
+        }
+        throw new Error(`variants[${i}] (${kind}): provide "file" (to upload) or "content" (existing file_path/URL).`);
+    }
+    return out;
+}
+/**
+ * Walk the parsed variants, request signed upload URLs for the ones that need
+ * uploading, PUT each file to its signed URL, then return an AskVariantInput[]
+ * with the right `content` value (file_path for media, literal for text).
+ */
+export async function uploadAndBuildVariants(client, productId, parsed, opts) {
+    if (parsed.length === 0)
+        return [];
+    const log = (msg) => { if (!opts?.quiet)
+        process.stderr.write(msg); };
+    // Validate all media files up front so we fail fast before requesting URLs.
+    const uploads = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const v = parsed[i];
+        if (!v.needsUpload)
+            continue;
+        const { size, mime } = await validateFile(v.source);
+        uploads.push({ index: i, mime, size, path: v.source });
+    }
+    // Map index → resolved content_string (file_path for media, literal for text).
+    const resolved = new Map();
+    for (let i = 0; i < parsed.length; i++) {
+        const v = parsed[i];
+        if (!v.needsUpload)
+            resolved.set(i, v.source);
+    }
+    if (uploads.length > 0) {
+        const body = {
+            items: uploads.map((u) => ({ content_type: u.mime, file_size_bytes: u.size })),
+        };
+        const resp = await client.post(`/products/${productId}/asks/variants/upload-urls`, body);
+        if (!resp.items || resp.items.length !== uploads.length) {
+            throw new Error("Variant upload response did not match request size.");
+        }
+        for (let i = 0; i < uploads.length; i++) {
+            const u = uploads[i];
+            const slot = resp.items[i];
+            const sizeMB = (u.size / (1024 * 1024)).toFixed(2);
+            log(`Uploading ${basename(u.path)} (${sizeMB} MB)...`);
+            const buf = await readFileAsync(resolvePath(u.path));
+            const putResp = await fetch(slot.upload_info.signed_upload_url, {
+                method: "PUT",
+                headers: {
+                    "Content-Type": u.mime,
+                    "Content-Length": String(buf.byteLength),
+                },
+                body: buf,
+                signal: AbortSignal.timeout(300_000),
+            });
+            if (!putResp.ok) {
+                const errText = await putResp.text().catch(() => "");
+                throw new Error(`Upload failed for ${u.path} (HTTP ${putResp.status}): ${errText}`);
+            }
+            log(" done.\n");
+            resolved.set(u.index, slot.upload_info.file_path);
+        }
+    }
+    return parsed.map((v, i) => {
+        const content = resolved.get(i);
+        const out = { kind: v.kind, content };
+        if (v.label !== undefined && v.label !== "")
+            out.label = v.label;
+        return out;
+    });
+}
+/**
+ * Convenience: parse flags OR manifest, validate that they're not both set, and
+ * return the parsed list. Caller still has to call `uploadAndBuildVariants`.
+ */
+export function parseVariantInputs(opts) {
+    const hasFlags = opts.variant && opts.variant.length > 0;
+    const hasManifest = !!opts.variants;
+    if (hasFlags && hasManifest) {
+        throw new Error("Use either --variant flags or --variants <manifest.json>, not both.");
+    }
+    if (hasManifest)
+        return loadVariantManifest(opts.variants);
+    if (hasFlags)
+        return parseVariantFlags(opts.variant);
+    return [];
+}

package/dist/lib/auth.d.ts

@@ -5,4 +5,4 @@
 export declare const DEFAULT_API_URL = "https://api.ishlabs.io";
 export declare const API_BASE = "/api/v1";
 export declare function resolveApiUrl(apiUrlArg?: string, dev?: boolean): string;
-export declare function resolveToken(tokenArg: string | undefined, apiUrl: string): Promise<string>;
+export declare function resolveToken(tokenArg: string | undefined, apiUrl: string, tokenFileArg?: string): Promise<string>;

package/dist/lib/auth.js

@@ -2,6 +2,7 @@
  * Shared authentication and configuration utilities for CLI commands.
  * Uses the canonical config from src/config.ts and OAuth refresh from src/auth.ts.
  */
+import * as fs from "node:fs";
 import { loadConfig, saveConfig } from "../config.js";
 import { refreshTokens, isTokenExpired } from "../auth.js";
 export const DEFAULT_API_URL = "https://api.ishlabs.io";
@@ -28,22 +29,36 @@ async function verifyToken(token, apiUrl) {
         return true;
     }
 }
-export async function resolveToken(tokenArg, apiUrl) {
+export async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
     // 1. Explicit token argument
     if (tokenArg)
         return tokenArg;
-    // 2. Environment variable
+    // 2. Token file
+    if (tokenFileArg) {
+        let content;
+        try {
+            content = fs.readFileSync(tokenFileArg, "utf-8");
+        }
+        catch {
+            throw new Error(`Cannot read --token-file: ${tokenFileArg}`);
+        }
+        const token = content.trim();
+        if (!token)
+            throw new Error(`--token-file is empty: ${tokenFileArg}`);
+        return token;
+    }
+    // 3. Environment variable
     const envToken = process.env.ISH_TOKEN;
     if (envToken)
         return envToken;
-    // 3. Saved config with OAuth tokens (access_token + refresh_token)
+    // 4. Saved config with OAuth tokens (access_token + refresh_token)
     const config = loadConfig();
     if (config.access_token && config.refresh_token) {
         let accessToken = config.access_token;
         // Refresh if expired or close to expiry
         if (isTokenExpired(accessToken)) {
             try {
-                const tokens = await refreshTokens(config.refresh_token);
+                const tokens = await refreshTokens(config.refresh_token, { accessToken });
                 accessToken = tokens.accessToken;
                 config.access_token = tokens.accessToken;
                 config.refresh_token = tokens.refreshToken;
@@ -53,7 +68,8 @@ export async function resolveToken(tokenArg, apiUrl) {
                 if (err instanceof TypeError || (err instanceof Error && err.message.includes('fetch'))) {
                     throw new Error('Could not refresh session (network error). Check your connection or run "ish login".');
                 }
-                throw new Error('Session expired. Run "ish login" to re-authenticate.');
+                const detail = err instanceof Error && err.message.startsWith("Token refresh failed") ? ` (${err.message})` : "";
+                throw new Error(`Session expired. Run "ish login" to re-authenticate.${detail}`);
             }
         }
         if (await verifyToken(accessToken, apiUrl)) {
@@ -61,13 +77,13 @@ export async function resolveToken(tokenArg, apiUrl) {
         }
         throw new Error('Saved token is invalid. Run "ish login" to re-authenticate.');
     }
-    // 4. Legacy saved token (no refresh token)
+    // 5. Legacy saved token (no refresh token)
     if (config.token) {
         if (await verifyToken(config.token, apiUrl)) {
             return config.token;
         }
         throw new Error('Saved token is invalid. Run "ish login" to re-authenticate.');
     }
-    // 5. No token found
-    throw new Error('No auth token found. Run "ish login" or set ISH_TOKEN environment variable or pass --token <token>.');
+    // 6. No token found
+    throw new Error('No auth token found. Run "ish login", set ISH_TOKEN, or pass --token <token> / --token-file <path>.');
 }

package/dist/lib/colors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Color/escape-sequence handling.
+ *
+ * Honors the NO_COLOR (https://no-color.org) and FORCE_COLOR conventions
+ * plus a runtime `--no-color` flag. Defaults to enabled when stdout is a
+ * TTY and NO_COLOR is unset.
+ *
+ * Use the `c` object: every property is a getter that returns the literal
+ * escape sequence when colors are enabled and an empty string when they
+ * aren't, so concatenating them is always safe.
+ */
+/** Override the default. Wired up in withClient/runInline based on --no-color. */
+export declare function setColorsEnabled(enabled: boolean): void;
+export declare function colorsEnabled(): boolean;
+declare const SEQUENCES: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly red: "\u001B[31m";
+    readonly yellow: "\u001B[33m";
+    readonly cyan: "\u001B[36m";
+    readonly orange: "\u001B[38;2;212;117;78m";
+};
+type ColorMap = {
+    readonly [K in keyof typeof SEQUENCES]: string;
+};
+/** Color sequences. Reflect the current setColorsEnabled() state on each access. */
+export declare const c: ColorMap;
+export {};

package/dist/lib/colors.js

@@ -0,0 +1,48 @@
+/**
+ * Color/escape-sequence handling.
+ *
+ * Honors the NO_COLOR (https://no-color.org) and FORCE_COLOR conventions
+ * plus a runtime `--no-color` flag. Defaults to enabled when stdout is a
+ * TTY and NO_COLOR is unset.
+ *
+ * Use the `c` object: every property is a getter that returns the literal
+ * escape sequence when colors are enabled and an empty string when they
+ * aren't, so concatenating them is always safe.
+ */
+let _enabled = computeDefault();
+function computeDefault() {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    const force = process.env.FORCE_COLOR;
+    if (force === "0" || force === "false")
+        return false;
+    if (force !== undefined && force !== "")
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+/** Override the default. Wired up in withClient/runInline based on --no-color. */
+export function setColorsEnabled(enabled) {
+    _enabled = enabled;
+}
+export function colorsEnabled() {
+    return _enabled;
+}
+const SEQUENCES = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    orange: "\x1b[38;2;212;117;78m",
+};
+const colorObj = Object.create(null);
+for (const [key, value] of Object.entries(SEQUENCES)) {
+    Object.defineProperty(colorObj, key, {
+        get: () => (_enabled ? value : ""),
+        enumerable: true,
+    });
+}
+/** Color sequences. Reflect the current setColorsEnabled() state on each access. */
+export const c = colorObj;

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

@@ -4,16 +4,69 @@
  */
 import type { Command } from "commander";
 import { ApiClient } from "./api-client.js";
+export interface AudienceFilterOpts {
+    profile?: string[];
+    sample?: string;
+    all?: boolean;
+    search?: string;
+    gender?: string[];
+    country?: string[];
+    minAge?: string;
+    maxAge?: string;
+    visibility?: string;
+}
+export interface AudienceResolveOpts {
+    requireSimulatable?: boolean;
+    allFlagName?: string;
+    /** Profile IDs to exclude from the fetched pool (e.g. testers already on an ask). */
+    excludeProfileIds?: Set<string>;
+}
+/** True when any audience-selection flag is set on the command. */
+export declare function hasAudienceFlags(flags: AudienceFilterOpts): boolean;
+/**
+ * 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 declare function resolveAudienceProfileIds(client: ApiClient, workspace: string, flags: AudienceFilterOpts, opts?: AudienceResolveOpts): Promise<string[]>;
+/**
+ * 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 declare function addAudienceFilterFlags(cmd: Command, opts?: {
+    allFlagName?: string;
+    allFlagDescription?: string;
+}): Command;
 export interface GlobalOpts {
     token?: string;
+    tokenFile?: string;
     apiUrl?: string;
     dev?: boolean;
     json: boolean;
     verbose: boolean;
     quiet: boolean;
+    color: boolean;
     fields?: string[];
 }
 export declare function getGlobals(cmd: Command): GlobalOpts;
+/**
+ * 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 declare const EXIT_USAGE = 2;
 /**
  * Map errors to semantic exit codes.
  * 0=success, 1=general, 2=usage/validation, 3=auth, 4=not found, 5=transient
@@ -21,8 +74,29 @@ export declare function getGlobals(cmd: Command): GlobalOpts;
 export declare function exitCodeFromError(err: unknown): number;
 export declare function createClient(globals: GlobalOpts): Promise<ApiClient>;
 export declare function withClient(cmd: Command, fn: (client: ApiClient, globals: GlobalOpts) => Promise<void>): Promise<void>;
+/**
+ * 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 declare function runInline(cmd: Command, fn: (globals: GlobalOpts) => Promise<void>): Promise<void>;
 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>;
 export declare function resolveWorkspace(explicit?: string): string;
 export declare function resolveStudy(explicit?: string): string;
+export declare function resolveAsk(explicit?: string): string;
+/** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
+export declare function collectRepeatable(value: string, prev?: string[]): string[];
+/**
+ * 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 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;