@ishlabs/cli 0.8.1

package/dist/lib/output.js

@@ -0,0 +1,675 @@
+/**
+ * Output formatting utilities.
+ * Supports both human-readable and JSON output modes.
+ *
+ * JSON output is lean by default (strips UUIDs, nulls, timestamps) to
+ * minimize context-window usage for AI agent consumers. Use --verbose
+ * for the full API response.
+ */
+import { ApiError } from "./api-client.js";
+import { deterministicAlias, getAliasMap, ALIAS_PREFIX } from "./alias-store.js";
+// --- Lean JSON: strip noise for agent-friendly output ---
+let _verbose = false;
+let _fields;
+/** Set by withClient() based on global flags. */
+export function setVerbose(v) { _verbose = v; }
+export function setFields(fields) { _fields = fields; }
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TIMESTAMP_KEYS = new Set(["created_at", "updated_at"]);
+/**
+ * Strip UUID-valued fields, null/undefined values, and timestamps.
+ * Preserves alias, name, label, status, and other meaningful fields.
+ */
+function leanJson(data) {
+    if (data === null || data === undefined)
+        return undefined;
+    if (Array.isArray(data)) {
+        return data.map(leanJson).filter((v) => v !== undefined);
+    }
+    if (typeof data !== "object")
+        return data;
+    const obj = data;
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        // Keep alias always
+        if (key === "alias") {
+            result[key] = value;
+            continue;
+        }
+        // Strip null/undefined
+        if (value === null || value === undefined)
+            continue;
+        // Strip timestamp fields
+        if (TIMESTAMP_KEYS.has(key))
+            continue;
+        // Strip UUID-valued fields (but keep non-UUID string fields)
+        if (typeof value === "string" && UUID_RE.test(value))
+            continue;
+        // Recurse into objects/arrays
+        if (typeof value === "object") {
+            const cleaned = leanJson(value);
+            if (cleaned !== undefined && !(Array.isArray(cleaned) && cleaned.length === 0)) {
+                result[key] = cleaned;
+            }
+            continue;
+        }
+        result[key] = value;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Pick only specified fields from an object. Applied after lean transform.
+ */
+function pickFields(data, fields) {
+    if (Array.isArray(data)) {
+        return data.map((item) => pickFields(item, fields));
+    }
+    if (typeof data === "object" && data !== null) {
+        const obj = data;
+        // Unwrap { items: [...] } wrapper before picking fields
+        if (Array.isArray(obj.items)) {
+            return pickFields(obj.items, fields);
+        }
+        const result = {};
+        for (const field of fields) {
+            if (field in obj)
+                result[field] = obj[field];
+        }
+        return result;
+    }
+    return data;
+}
+/** Serialize data as JSON, applying lean transform and field selection. */
+function jsonOutput(data) {
+    let out = _verbose ? data : leanJson(data);
+    if (_fields && _fields.length > 0) {
+        out = pickFields(out, _fields);
+    }
+    return JSON.stringify(out, null, 2);
+}
+/**
+ * Save aliases for a list of items and inject `alias` into each item.
+ * Call this before both JSON and human output so aliases are always available.
+ */
+function injectAliases(items, prefix, idField = "id") {
+    for (const item of items) {
+        const id = String(item[idField] || "");
+        if (id) {
+            item.alias = deterministicAlias(prefix, id);
+        }
+    }
+}
+// --- JSON mode ---
+export function output(data, json) {
+    if (json) {
+        console.log(jsonOutput(data));
+        return;
+    }
+    if (data === null || data === undefined)
+        return;
+    if (Array.isArray(data)) {
+        outputList(data, json);
+        return;
+    }
+    if (typeof data === "object") {
+        printKeyValue(data);
+        return;
+    }
+    console.log(String(data));
+}
+export function outputList(rows, json) {
+    if (json) {
+        console.log(jsonOutput(rows));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("No results.");
+        return;
+    }
+    // Generic list: show name + key fields
+    for (const row of rows) {
+        if (typeof row === "object" && row !== null) {
+            const obj = row;
+            const parts = [];
+            if (obj.name)
+                parts.push(String(obj.name));
+            if (obj.status)
+                parts.push(`[${obj.status}]`);
+            if (obj.modality)
+                parts.push(String(obj.modality));
+            console.log("  " + parts.join("  "));
+        }
+        else {
+            console.log("  " + String(row));
+        }
+    }
+}
+/**
+ * Error with valid options — used for content_type and similar validation.
+ * Surfaces valid_options in JSON so agents can self-correct.
+ */
+export class ValidationError extends Error {
+    valid_options;
+    constructor(message, valid_options) {
+        super(message);
+        this.valid_options = valid_options;
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Map error codes to actionable suggestions so agents can self-recover.
+ */
+function suggestionsForError(err) {
+    if (err instanceof ApiError) {
+        switch (err.error_code) {
+            case "auth_failed":
+                return ["Run `ish login` to authenticate"];
+            case "forbidden":
+                return ["Check that your account has access to this resource"];
+            case "not_found":
+                return [
+                    "Run a list command to see available resources",
+                    "Check that the alias or ID is correct",
+                ];
+            case "insufficient_credits":
+                return ["Purchase more credits at https://app.ishlabs.io"];
+            case "validation_error":
+                return ["Check the command help: add --help to see required options"];
+            case "rate_limited":
+                return ["Wait a moment and retry the command"];
+            default:
+                return err.retryable ? ["Retry the command in a moment"] : [];
+        }
+    }
+    if (err instanceof Error) {
+        if (/no auth token|run "ish login"|session expired/i.test(err.message)) {
+            return ["Run `ish login` to authenticate"];
+        }
+        if (/no workspace set/i.test(err.message)) {
+            return ["Run `ish workspace list` then `ish workspace use <alias>`"];
+        }
+        if (/no study set/i.test(err.message)) {
+            return ["Run `ish study list` then `ish study use <alias>`"];
+        }
+        if (/invalid id/i.test(err.message)) {
+            return ["Run a list command to see available aliases"];
+        }
+        if (/file not found|cannot read/i.test(err.message)) {
+            return ["Check that the file path exists and is readable"];
+        }
+    }
+    return [];
+}
+export function outputError(err, json) {
+    const suggestions = suggestionsForError(err);
+    if (err instanceof ApiError) {
+        if (json) {
+            console.error(JSON.stringify({
+                error: err.message,
+                error_code: err.error_code,
+                status: err.status,
+                retryable: err.retryable,
+                ...(suggestions.length > 0 && { suggestions }),
+            }));
+        }
+        else {
+            if (err.status === 402) {
+                console.error("Error: Insufficient credits. Purchase more at https://app.ishlabs.io");
+            }
+            else {
+                console.error(`Error: ${err.message}`);
+            }
+            for (const s of suggestions)
+                console.error(`  → ${s}`);
+        }
+    }
+    else if (err instanceof ValidationError) {
+        if (json) {
+            console.error(JSON.stringify({
+                error: err.message,
+                error_code: "validation_error",
+                retryable: false,
+                valid_options: err.valid_options,
+                ...(suggestions.length > 0 && { suggestions }),
+            }));
+        }
+        else {
+            console.error(`Error: ${err.message}`);
+            for (const s of suggestions)
+                console.error(`  → ${s}`);
+        }
+    }
+    else if (err instanceof Error) {
+        if (json) {
+            console.error(JSON.stringify({
+                error: err.message,
+                error_code: "client_error",
+                retryable: false,
+                ...(suggestions.length > 0 && { suggestions }),
+            }));
+        }
+        else {
+            console.error(`Error: ${err.message}`);
+            for (const s of suggestions)
+                console.error(`  → ${s}`);
+        }
+    }
+    else {
+        if (json) {
+            console.error(JSON.stringify({ error: String(err), error_code: "unknown_error", retryable: false }));
+        }
+        else {
+            console.error(`Error: ${err}`);
+        }
+    }
+}
+// --- Entity-specific formatters (human mode) ---
+export function printTable(headers, rows) {
+    const colWidths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] || "").length)));
+    console.log("  " + headers.map((h, i) => h.padEnd(colWidths[i])).join("  "));
+    for (const row of rows) {
+        console.log("  " + row.map((cell, i) => (cell || "").padEnd(colWidths[i])).join("  "));
+    }
+}
+export function printKeyValue(obj, indent = "  ") {
+    const entries = Object.entries(obj).filter(([, v]) => v !== null && v !== undefined);
+    if (entries.length === 0)
+        return;
+    const maxKeyLen = Math.max(...entries.map(([k]) => k.length));
+    for (const [key, value] of entries) {
+        const label = formatLabel(key);
+        const displayValue = typeof value === "object" && value !== null
+            ? JSON.stringify(value)
+            : String(value);
+        console.log(`${indent}${label.padEnd(maxKeyLen + 2)}${displayValue}`);
+    }
+}
+function formatLabel(key) {
+    return key
+        .replace(/_/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+// --- Workspace formatting ---
+export function formatWorkspaceList(workspaces, json) {
+    if (workspaces.length === 0) {
+        if (json)
+            console.log("[]");
+        else
+            console.log("No workspaces.");
+        return;
+    }
+    injectAliases(workspaces, ALIAS_PREFIX.workspace);
+    if (json) {
+        console.log(jsonOutput(workspaces));
+        return;
+    }
+    const aliasMap = getAliasMap(ALIAS_PREFIX.workspace);
+    printTable(["#", "NAME", "CREATED"], workspaces.map((w) => [
+        aliasMap.get(String(w.id)) || String(w.id || ""),
+        String(w.name || ""),
+        formatDate(w.created_at),
+    ]));
+}
+export function formatWorkspaceDetail(workspace, json) {
+    if (json) {
+        console.log(jsonOutput(workspace));
+        return;
+    }
+    const display = {
+        ID: workspace.id || "-",
+        Name: workspace.name,
+        Description: workspace.description || "-",
+        "Base URL": workspace.base_url || "-",
+        Created: formatDate(workspace.created_at),
+    };
+    printKeyValue(display);
+}
+// --- Study formatting ---
+export function formatStudyList(studies, json) {
+    if (studies.length === 0) {
+        if (json)
+            console.log("[]");
+        else
+            console.log("No studies.");
+        return;
+    }
+    injectAliases(studies, ALIAS_PREFIX.study);
+    if (json) {
+        console.log(jsonOutput(studies));
+        return;
+    }
+    const aliasMap = getAliasMap(ALIAS_PREFIX.study);
+    printTable(["#", "NAME", "MODALITY", "TYPE", "STATUS", "TESTERS"], studies.map((s) => [
+        aliasMap.get(String(s.id)) || String(s.id || ""),
+        String(s.name || ""),
+        String(s.modality || "-"),
+        String(s.content_type || "-"),
+        String(s.status || "draft"),
+        String(s.tester_count ?? "0"),
+    ]));
+}
+export function formatStudyDetail(study, json) {
+    if (json) {
+        console.log(jsonOutput(study));
+        return;
+    }
+    // Header
+    console.log(`${study.name || "Untitled"} (${study.id || ""})`);
+    if (study.description)
+        console.log(String(study.description));
+    const modalityParts = [study.modality || "-"];
+    if (study.content_type)
+        modalityParts.push(String(study.content_type));
+    modalityParts.push(String(study.status || "draft"), formatDate(study.created_at));
+    console.log(modalityParts.join(" · "));
+    // Assignments
+    const assignments = Array.isArray(study.assignments) ? study.assignments : [];
+    if (assignments.length > 0) {
+        console.log("\nAssignments:");
+        for (let i = 0; i < assignments.length; i++) {
+            const a = assignments[i];
+            console.log(`  ${i + 1}. ${a.name || "Untitled"}`);
+            if (a.instructions) {
+                console.log(`     ${truncate(String(a.instructions), 80)}`);
+            }
+        }
+    }
+    // Interview Questions
+    const questions = Array.isArray(study.interview_questions) ? study.interview_questions : [];
+    if (questions.length > 0) {
+        console.log("\nInterview Questions:");
+        for (let i = 0; i < questions.length; i++) {
+            const q = questions[i];
+            const typeStr = formatQuestionType(q);
+            console.log(`  ${i + 1}. ${q.question || "Untitled"} ${typeStr}`);
+        }
+    }
+    // Testers summary
+    const allTesters = collectTesters(study);
+    if (allTesters.length > 0) {
+        console.log(`\nTesters (${allTesters.length}):`);
+        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allTesters.map((t) => [
+            t.id ? deterministicAlias(ALIAS_PREFIX.tester, t.id) : t.id,
+            t.name,
+            t.iterationLabel,
+            t.status,
+            String(t.interactionCount),
+        ]));
+    }
+}
+export function formatStudyResults(study, json) {
+    if (json) {
+        console.log(jsonOutput(study));
+        return;
+    }
+    const allTesters = collectTesters(study);
+    const totalInteractions = allTesters.reduce((sum, t) => sum + t.interactionCount, 0);
+    // Header
+    console.log(`${study.name || "Untitled"} — Results`);
+    console.log(`${allTesters.length} tester${allTesters.length !== 1 ? "s" : ""} · ${totalInteractions} total interactions`);
+    // Sentiment summary
+    const totalSentiment = {};
+    for (const t of allTesters) {
+        for (const [label, count] of Object.entries(t.sentimentCounts)) {
+            totalSentiment[label] = (totalSentiment[label] || 0) + count;
+        }
+    }
+    const sentimentParts = Object.entries(totalSentiment).map(([label, count]) => `${count} ${label.toLowerCase()}`);
+    console.log(`\nSentiment: ${sentimentParts.length > 0 ? sentimentParts.join(", ") : "none"}`);
+    // Interview Answers grouped by question
+    const questions = Array.isArray(study.interview_questions) ? study.interview_questions : [];
+    if (questions.length > 0) {
+        console.log("\nInterview Answers:");
+        for (const q of questions) {
+            const qObj = q;
+            const typeStr = formatQuestionType(qObj);
+            console.log(`\n  "${qObj.question}" ${typeStr}`);
+            for (const t of allTesters) {
+                const answer = t.interviewAnswers.find((a) => a.questionId === qObj.id);
+                if (answer) {
+                    const answerStr = typeof answer.answer === "string"
+                        ? `"${truncate(answer.answer, 70)}"`
+                        : String(answer.answer);
+                    console.log(`    ${t.name} (${t.iterationLabel}):  ${answerStr}`);
+                }
+            }
+        }
+    }
+    // Testers table
+    if (allTesters.length > 0) {
+        console.log("\nTesters:");
+        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allTesters.map((t) => {
+            const parts = Object.entries(t.sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
+            return [
+                t.id ? deterministicAlias(ALIAS_PREFIX.tester, t.id) : t.id,
+                t.name,
+                t.iterationLabel,
+                t.status,
+                String(t.interactionCount),
+                parts.length > 0 ? parts.join(", ") : "-",
+            ];
+        }));
+        console.log("\nRun `ish tester get <id> --json` for full interaction details.");
+    }
+}
+function collectTesters(study) {
+    const iterations = Array.isArray(study.iterations) ? study.iterations : [];
+    const testers = [];
+    for (const iter of iterations) {
+        const it = iter;
+        const iterLabel = String(it.label || it.name || "-");
+        const iterTesters = Array.isArray(it.testers) ? it.testers : [];
+        for (const tester of iterTesters) {
+            const t = tester;
+            const profile = t.tester_profile;
+            const interactions = Array.isArray(t.interactions) ? t.interactions : [];
+            const sentimentCounts = {};
+            for (const interaction of interactions) {
+                const ix = interaction;
+                const sentiment = ix.sentiment;
+                if (sentiment?.label) {
+                    const label = String(sentiment.label);
+                    sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
+                }
+            }
+            const answers = Array.isArray(t.interview_answers) ? t.interview_answers : [];
+            testers.push({
+                id: String(t.id || ""),
+                name: String(profile?.name || t.instance_name || "Unknown"),
+                iterationLabel: iterLabel,
+                status: String(t.status || "-"),
+                interactionCount: interactions.length,
+                sentimentCounts,
+                interviewAnswers: answers.map((a) => ({
+                    questionId: String(a.question_id || ""),
+                    answer: a.answer,
+                })),
+            });
+        }
+    }
+    return testers;
+}
+function formatQuestionType(q) {
+    if (!q.type)
+        return "";
+    if (q.type === "slider" && q.min !== undefined && q.max !== undefined) {
+        return `[${q.type} ${q.min}-${q.max}]`;
+    }
+    return `[${q.type}]`;
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + "...";
+}
+// --- Iteration formatting ---
+export function formatIterationList(iterations, json) {
+    if (iterations.length === 0) {
+        if (json)
+            console.log("[]");
+        else
+            console.log("No iterations.");
+        return;
+    }
+    injectAliases(iterations, ALIAS_PREFIX.iteration);
+    if (json) {
+        console.log(jsonOutput(iterations));
+        return;
+    }
+    const aliasMap = getAliasMap(ALIAS_PREFIX.iteration);
+    printTable(["#", "LABEL", "NAME", "TESTERS", "CREATED"], iterations.map((it) => {
+        const testers = Array.isArray(it.testers) ? it.testers.length : 0;
+        return [
+            aliasMap.get(String(it.id)) || String(it.id || ""),
+            String(it.label || "-"),
+            String(it.name || ""),
+            String(testers),
+            formatDate(it.created_at),
+        ];
+    }));
+}
+// --- Tester formatting ---
+export function formatTesterDetail(tester, json) {
+    if (json) {
+        console.log(jsonOutput(tester));
+        return;
+    }
+    const profile = tester.tester_profile;
+    const profileName = profile?.name ? String(profile.name) : "Unknown";
+    const interactions = Array.isArray(tester.interactions) ? tester.interactions : [];
+    // Count sentiments
+    const sentimentCounts = {};
+    for (const interaction of interactions) {
+        const it = interaction;
+        const sentiment = it.sentiment;
+        if (sentiment?.label) {
+            const label = String(sentiment.label);
+            sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
+        }
+    }
+    const sentimentParts = Object.entries(sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
+    const display = {
+        ID: tester.id || "-",
+        Profile: profileName,
+        Status: tester.status || "-",
+        Platform: tester.platform || "-",
+        Language: tester.language || "-",
+        Interactions: `${interactions.length} interactions`,
+        ...(sentimentParts.length > 0 && {
+            Sentiment: sentimentParts.join(", "),
+        }),
+    };
+    printKeyValue(display);
+}
+// --- Tester Profile formatting ---
+export function formatTesterProfileList(profiles, json, limit) {
+    // The API may return { items: [...], total, limit, offset } or a flat array
+    const wrapper = profiles;
+    const fullList = Array.isArray(profiles) ? profiles
+        : Array.isArray(wrapper?.items) ? wrapper.items
+            : Array.isArray(wrapper?.profiles) ? wrapper.profiles
+                : null;
+    if (!Array.isArray(fullList) || fullList.length === 0) {
+        if (json)
+            console.log(JSON.stringify(profiles, null, 2));
+        else
+            console.log("No tester profiles.");
+        return;
+    }
+    // Client-side limit (server may not enforce it)
+    const list = limit ? fullList.slice(0, limit) : fullList;
+    injectAliases(list, ALIAS_PREFIX.testerProfile);
+    if (json) {
+        console.log(jsonOutput(profiles));
+        return;
+    }
+    printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
+        String(p.alias || p.id || ""),
+        String(p.name || ""),
+        String(p.occupation || "-"),
+        String(p.country || "-"),
+        String(p.gender || "-"),
+        formatAge(p.date_of_birth),
+    ]));
+    if (fullList.length > list.length) {
+        console.log(`\n  Showing ${list.length} of ${fullList.length} profiles. Use --limit and --offset for more.`);
+    }
+}
+// --- Simulation poll formatting ---
+export function formatSimulationPoll(results, json, isMedia = false) {
+    if (results.length === 0) {
+        if (json)
+            console.log(jsonOutput([]));
+        else
+            console.log("No simulations found.");
+        return;
+    }
+    injectAliases(results, ALIAS_PREFIX.tester);
+    if (json) {
+        console.log(jsonOutput(results));
+        return;
+    }
+    const aliasMap = getAliasMap(ALIAS_PREFIX.tester);
+    const countHeader = isMedia ? "SEGMENTS" : "INTERACTIONS";
+    printTable(["#", "TESTER", "STATUS", countHeader], results.map((r) => {
+        const id = String(r.id || r.tester_id || "");
+        return [
+            aliasMap.get(id) || id,
+            String(r.tester_name || "Unknown"),
+            String(r.status || "UNKNOWN"),
+            String(r.interaction_count ?? "0"),
+        ];
+    }));
+}
+// --- Config formatting ---
+export function formatConfigList(configs, json) {
+    if (configs.length === 0) {
+        if (json)
+            console.log("[]");
+        else
+            console.log("No simulation configs.");
+        return;
+    }
+    injectAliases(configs, ALIAS_PREFIX.config);
+    if (json) {
+        console.log(jsonOutput(configs));
+        return;
+    }
+    const aliasMap = getAliasMap(ALIAS_PREFIX.config);
+    printTable(["#", "NAME", "SOURCE", "CREATED"], configs.map((c) => [
+        aliasMap.get(String(c.id)) || String(c.id || ""),
+        String(c.name || ""),
+        String(c.source_type || "manual"),
+        formatDate(c.created_at),
+    ]));
+}
+// --- Helpers ---
+function formatAge(dob) {
+    if (!dob)
+        return "-";
+    try {
+        const birth = new Date(String(dob));
+        if (isNaN(birth.getTime()))
+            return "-";
+        const now = new Date();
+        let age = now.getFullYear() - birth.getFullYear();
+        const monthDiff = now.getMonth() - birth.getMonth();
+        if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < birth.getDate()))
+            age--;
+        return String(age);
+    }
+    catch {
+        return "-";
+    }
+}
+function formatDate(value) {
+    if (!value)
+        return "-";
+    const str = String(value);
+    try {
+        return new Date(str).toLocaleDateString("en-CA"); // YYYY-MM-DD
+    }
+    catch {
+        return str.slice(0, 10);
+    }
+}