@ishlabs/cli 0.8.1 → 0.8.2

package/dist/index.js

@@ -7,83 +7,131 @@ import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
 import { registerStudyCommands } from "./commands/study.js";
 import { registerIterationCommands } from "./commands/iteration.js";
-import { registerTesterProfileCommands } from "./commands/tester-profile.js";
-import { registerTesterCommands } from "./commands/tester.js";
-import { registerSimulationCommands } from "./commands/simulation.js";
+import { registerProfileCommands } from "./commands/profile.js";
+import { registerSourceCommands } from "./commands/source.js";
 import { registerConfigCommands } from "./commands/config.js";
+import { registerAskCommands } from "./commands/ask.js";
+import { registerDocsCommands } from "./commands/docs.js";
+import { registerInitCommands } from "./commands/init.js";
+import { AGENT_HELP_FOOTER } from "./lib/docs.js";
+import { runInline, EXIT_USAGE } from "./lib/command-helpers.js";
+import { output } from "./lib/output.js";
 import pkg from "../package.json" with { type: "json" };
 const { version } = pkg;
 program
     .name("ish")
-    .description("Ish CLI — manage workspaces, studies, simulations, and more")
-    .version(version);
+    .description("Ish CLI — run studies and asks against AI tester audiences")
+    .version(version)
+    .addHelpText("after", AGENT_HELP_FOOTER);
+// Unified error envelope for Commander-level failures (unknown command,
+// missing required option, etc.) so JSON consumers see the same shape
+// regardless of whether the error originated in the CLI argv parser or
+// the API. Without this, Commander would print plain text to stderr and
+// — for missingMandatoryOptionValue — exit 0, breaking shell pipelines.
+//
+// Suppress Commander's own error formatter so the only error line is the
+// envelope our exitOverride handler emits below.
+program.configureOutput({
+    outputError: () => { },
+});
+program.exitOverride((err) => {
+    // Help and --version are normal exit-0 paths, not errors.
+    if (err.code === "commander.helpDisplayed"
+        || err.code === "commander.version"
+        || err.code === "commander.help") {
+        process.exit(0);
+    }
+    // Detect --json without relying on parsed opts (parse may have failed).
+    const useJson = process.argv.includes("--json") || !process.stdout.isTTY;
+    const envelope = {
+        error: err.message,
+        error_code: "usage_error",
+        status: 0,
+        retryable: false,
+        suggestions: ["Run `ish <command> --help` for usage"],
+    };
+    if (useJson) {
+        console.error(JSON.stringify(envelope));
+    }
+    else {
+        console.error(`Error: ${err.message}`);
+        console.error("  → Run `ish <command> --help` for usage");
+    }
+    process.exit(EXIT_USAGE);
+});
 // Global options
 program
     .option("-t, --token <token>", "Auth token (or set ISH_TOKEN env var)")
+    .option("--token-file <path>", "Read auth token from a file (preferred over --token / ISH_TOKEN)")
     .option("--api-url <url>", "Backend API URL (default: ISH_API_URL or https://api.ishlabs.io)")
     .addOption(new Option("--dev", "Use local dev API (http://localhost:8000)").hideHelp())
     .option("--json", "Output as JSON (auto-enabled when piped)")
     .option("--fields <fields>", "Comma-separated fields to include in JSON output (e.g. alias,name,status)")
     .option("--verbose", "Include full UUIDs and timestamps in JSON output")
-    .option("-q, --quiet", "Suppress progress messages on stderr");
+    .option("--no-color", "Disable colored output (also honored: NO_COLOR env var)")
+    .option("-q, --quiet", "Suppress progress messages on stderr (no-op for read commands that emit none)");
 // --- Inline commands (from upstream) ---
 program
     .command("login")
     .description("Authenticate with Ish via your browser")
     .action(async (_opts, cmd) => {
-    try {
-        const globals = cmd.optsWithGlobals();
+    await runInline(cmd, async (globals) => {
         const appUrl = globals.dev ? "http://localhost:3000" : getAppUrl();
         const tokens = await login(appUrl);
         const config = loadConfig();
         config.access_token = tokens.accessToken;
         config.refresh_token = tokens.refreshToken;
         saveConfig(config);
-        console.log("\nLogin successful!");
-    }
-    catch (e) {
-        console.error(`Login failed: ${e instanceof Error ? e.message : e}`);
-        process.exit(1);
-    }
+        output({ message: "Login successful" }, globals.json);
+    });
 });
 program
     .command("logout")
     .description("Remove saved authentication credentials")
-    .action(() => {
-    const config = loadConfig();
-    delete config.access_token;
-    delete config.refresh_token;
-    delete config.token;
-    saveConfig(config);
-    console.log("Logged out.");
+    .action(async (_opts, cmd) => {
+    await runInline(cmd, async (globals) => {
+        const config = loadConfig();
+        delete config.access_token;
+        delete config.refresh_token;
+        delete config.token;
+        saveConfig(config);
+        output({ message: "Logged out" }, globals.json);
+    });
 });
 program
     .command("connect")
     .description("Expose your localhost to Ish via a Cloudflare tunnel")
     .argument("<port>", "Local port to connect (e.g. 3000)")
+    .addHelpText("after", "\nNote: --json emits structured one-line JSON for connected/disconnected events. --fields and --quiet have limited effect; use --json for machine-readable output.")
     .action(async (port, _opts, cmd) => {
-    const portNum = parseInt(port, 10);
-    if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
-        console.error(`Invalid port: ${port}`);
-        process.exit(1);
-    }
-    const globals = cmd.optsWithGlobals();
-    const apiUrl = globals.dev ? "http://localhost:8000" : globals.apiUrl;
-    await runTunnel(portNum, globals.token, apiUrl);
+    await runInline(cmd, async (globals) => {
+        const portNum = parseInt(port, 10);
+        if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+            throw new Error(`Invalid port: ${port}`);
+        }
+        const apiUrl = globals.dev ? "http://localhost:8000" : globals.apiUrl;
+        await runTunnel(portNum, globals.token, apiUrl, globals.tokenFile, {
+            json: globals.json,
+            quiet: globals.quiet,
+        });
+    });
 });
 // --- Modular command groups ---
 registerWorkspaceCommands(program);
 registerStudyCommands(program);
 registerIterationCommands(program);
-registerTesterProfileCommands(program);
-registerTesterCommands(program);
-registerSimulationCommands(program);
+registerProfileCommands(program);
+registerSourceCommands(program);
 registerConfigCommands(program);
+registerAskCommands(program);
+registerDocsCommands(program);
+registerInitCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")
-    .option("--version <version>", "Install a specific version")
+    .option("--release <version>", "Install a specific release (e.g. 0.8.1)")
+    .addHelpText("after", "\nPin a specific release with --release <version>. Note: --version is the global CLI-version flag; use --release here.")
     .action(async (options) => {
-    await upgrade(version, options.version);
+    await upgrade(version, options.release);
 });
 program.parse();

package/dist/lib/alias-store.d.ts

@@ -11,9 +11,12 @@ export declare const ALIAS_PREFIX: {
     readonly study: "s";
     readonly iteration: "i";
     readonly testerProfile: "tp";
+    readonly testerProfileSource: "tps";
     readonly tester: "t";
     readonly config: "c";
     readonly job: "j";
+    readonly ask: "a";
+    readonly askRound: "r";
 };
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/alias-store.js

@@ -7,17 +7,19 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as os from "node:os";
-const ALIASES_FILE = path.join(os.homedir(), ".ish", "aliases.json");
+import { aliasesPath } from "./paths.js";
 /** Entity type → alias prefix */
 export const ALIAS_PREFIX = {
     workspace: "w",
     study: "s",
     iteration: "i",
     testerProfile: "tp",
+    testerProfileSource: "tps",
     tester: "t",
     config: "c",
     job: "j",
+    ask: "a",
+    askRound: "r",
 };
 /** Format a number with zero-padding (minimum 2 digits). */
 function padNum(n) {
@@ -25,8 +27,8 @@ function padNum(n) {
 }
 function loadAliases() {
     try {
-        if (fs.existsSync(ALIASES_FILE)) {
-            return JSON.parse(fs.readFileSync(ALIASES_FILE, "utf-8"));
+        if (fs.existsSync(aliasesPath())) {
+            return JSON.parse(fs.readFileSync(aliasesPath(), "utf-8"));
         }
     }
     catch {
@@ -35,11 +37,11 @@ function loadAliases() {
     return {};
 }
 function persistAliases(aliases) {
-    const dir = path.dirname(ALIASES_FILE);
+    const dir = path.dirname(aliasesPath());
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const tmp = ALIASES_FILE + ".tmp";
+    const tmp = aliasesPath() + ".tmp";
     fs.writeFileSync(tmp, JSON.stringify(aliases, null, 2) + "\n", { mode: 0o600 });
-    fs.renameSync(tmp, ALIASES_FILE);
+    fs.renameSync(tmp, aliasesPath());
 }
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/api-client.d.ts

@@ -9,6 +9,9 @@ export declare class ApiError extends Error {
     retryable: boolean;
     constructor(status: number, statusText: string, body: unknown);
 }
+interface RequestOpts {
+    timeout?: number;
+}
 export declare class ApiClient {
     private baseUrl;
     private token;
@@ -18,12 +21,11 @@ export declare class ApiClient {
     });
     get accessToken(): string;
     private headers;
-    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
-    post<T = unknown>(path: string, body?: unknown, opts?: {
-        timeout?: number;
-    }): Promise<T>;
-    put<T = unknown>(path: string, body?: unknown): Promise<T>;
-    del(path: string): Promise<void>;
+    get<T = unknown>(path: string, params?: Record<string, string | string[]>, opts?: RequestOpts): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;
+    del(path: string, opts?: RequestOpts): Promise<void>;
     localSimInit(body: {
         tester_id: string;
         study_id: string;
@@ -56,3 +58,4 @@ export declare class ApiClient {
     }>;
     private handleResponse;
 }
+export {};

package/dist/lib/api-client.js

@@ -11,6 +11,8 @@ function mapErrorCode(status) {
         return "not_found";
     if (status === 402)
         return "insufficient_credits";
+    if (status === 408)
+        return "timeout";
     if (status === 422)
         return "validation_error";
     if (status === 429)
@@ -20,7 +22,7 @@ function mapErrorCode(status) {
     return "request_failed";
 }
 function isRetryable(status) {
-    return status === 429 || status >= 500;
+    return status === 408 || status === 429 || status >= 500;
 }
 export class ApiError extends Error {
     status;
@@ -41,6 +43,21 @@ export class ApiError extends Error {
         this.retryable = isRetryable(status);
     }
 }
+const DEFAULT_TIMEOUT_MS = 15_000;
+function timeoutError(method, timeoutMs) {
+    const seconds = Math.round(timeoutMs / 1000);
+    return new ApiError(408, "Request Timeout", { detail: `${method} request timed out after ${seconds}s. The server may be slow — try again.` });
+}
+function isAbortTimeout(err) {
+    return err instanceof DOMException
+        && (err.name === "TimeoutError" || err.name === "AbortError");
+}
+function networkError(url) {
+    const err = new ApiError(0, "Network Error", { detail: `Could not reach API at ${url}` });
+    err.error_code = "network_error";
+    err.retryable = true;
+    return err;
+}
 export class ApiClient {
     baseUrl;
     token;
@@ -57,34 +74,50 @@ export class ApiClient {
             "Content-Type": "application/json",
         };
     }
-    async get(path, params) {
+    async get(path, params, opts) {
         let url = `${this.baseUrl}${path}`;
         if (params) {
-            const filtered = Object.entries(params).filter(([, v]) => v !== undefined && v !== "");
-            if (filtered.length > 0) {
-                url += "?" + new URLSearchParams(filtered).toString();
+            const tuples = [];
+            for (const [k, v] of Object.entries(params)) {
+                if (v === undefined || v === "")
+                    continue;
+                if (Array.isArray(v)) {
+                    for (const item of v) {
+                        if (item !== undefined && item !== "")
+                            tuples.push([k, String(item)]);
+                    }
+                }
+                else {
+                    tuples.push([k, v]);
+                }
+            }
+            if (tuples.length > 0) {
+                url += "?" + new URLSearchParams(tuples).toString();
             }
         }
+        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
         let res;
         try {
             res = await fetch(url, {
                 headers: this.headers(),
-                signal: AbortSignal.timeout(15_000),
+                signal: AbortSignal.timeout(timeout),
             });
         }
         catch (err) {
-            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-                throw new Error('Request timed out after 15s. The server may be slow — try again.');
-            }
+            if (isAbortTimeout(err))
+                throw timeoutError("GET", timeout);
+            if (err instanceof TypeError)
+                throw networkError(url);
             throw err;
         }
         return this.handleResponse(res);
     }
     async post(path, body, opts) {
-        const timeout = opts?.timeout ?? 15_000;
+        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${path}`;
         let res;
         try {
-            res = await fetch(`${this.baseUrl}${path}`, {
+            res = await fetch(url, {
                 method: "POST",
                 headers: this.headers(),
                 body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -92,44 +125,72 @@ export class ApiClient {
             });
         }
         catch (err) {
-            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-                throw new Error(`Request timed out after ${timeout / 1000}s. The server may be slow — try again.`);
-            }
+            if (isAbortTimeout(err))
+                throw timeoutError("POST", timeout);
+            if (err instanceof TypeError)
+                throw networkError(url);
             throw err;
         }
         return this.handleResponse(res);
     }
-    async put(path, body) {
+    async put(path, body, opts) {
+        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${path}`;
         let res;
         try {
-            res = await fetch(`${this.baseUrl}${path}`, {
+            res = await fetch(url, {
                 method: "PUT",
                 headers: this.headers(),
                 body: body !== undefined ? JSON.stringify(body) : undefined,
-                signal: AbortSignal.timeout(15_000),
+                signal: AbortSignal.timeout(timeout),
             });
         }
         catch (err) {
-            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-                throw new Error('Request timed out after 15s. The server may be slow — try again.');
-            }
+            if (isAbortTimeout(err))
+                throw timeoutError("PUT", timeout);
+            if (err instanceof TypeError)
+                throw networkError(url);
             throw err;
         }
         return this.handleResponse(res);
     }
-    async del(path) {
+    async patch(path, body, opts) {
+        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${path}`;
         let res;
         try {
-            res = await fetch(`${this.baseUrl}${path}`, {
+            res = await fetch(url, {
+                method: "PATCH",
+                headers: this.headers(),
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(timeout),
+            });
+        }
+        catch (err) {
+            if (isAbortTimeout(err))
+                throw timeoutError("PATCH", timeout);
+            if (err instanceof TypeError)
+                throw networkError(url);
+            throw err;
+        }
+        return this.handleResponse(res);
+    }
+    async del(path, opts) {
+        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${path}`;
+        let res;
+        try {
+            res = await fetch(url, {
                 method: "DELETE",
                 headers: this.headers(),
-                signal: AbortSignal.timeout(15_000),
+                signal: AbortSignal.timeout(timeout),
             });
         }
         catch (err) {
-            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-                throw new Error('Request timed out after 15s. The server may be slow — try again.');
-            }
+            if (isAbortTimeout(err))
+                throw timeoutError("DELETE", timeout);
+            if (err instanceof TypeError)
+                throw networkError(url);
             throw err;
         }
         if (!res.ok) {

package/dist/lib/ask-questions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Loader/validator for `--questions <file.json>`.
+ *
+ * Accepts a JSON array of InterviewQuestion entries. Mirrors the loose validation
+ * used by `ish study create --questions`: requires `question: string` on every entry,
+ * passes the rest through. The backend is the source of truth for the full schema.
+ */
+import type { InterviewQuestion } from "./types.js";
+export declare function loadQuestionsManifest(filePath: string): InterviewQuestion[];

package/dist/lib/ask-questions.js

@@ -0,0 +1,35 @@
+/**
+ * Loader/validator for `--questions <file.json>`.
+ *
+ * Accepts a JSON array of InterviewQuestion entries. Mirrors the loose validation
+ * used by `ish study create --questions`: requires `question: string` on every entry,
+ * passes the rest through. The backend is the source of truth for the full schema.
+ */
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+export function loadQuestionsManifest(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(resolvePath(filePath), "utf-8");
+    }
+    catch {
+        throw new Error(`Cannot read questions file: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in questions file: ${filePath}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(`Questions file must be a non-empty JSON array: ${filePath}`);
+    }
+    for (let i = 0; i < parsed.length; i++) {
+        const q = parsed[i];
+        if (!q || typeof q !== "object" || typeof q.question !== "string" || !q.question.trim()) {
+            throw new Error(`questions[${i}].question must be a non-empty string.`);
+        }
+    }
+    return parsed;
+}

package/dist/lib/ask-variants.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 type { ApiClient } from "./api-client.js";
+import type { AskVariantInput, AskVariantKind } from "./types.js";
+/** Internal representation of a parsed variant before any upload happens. */
+export interface ParsedVariant {
+    kind: AskVariantKind;
+    label?: string;
+    /** For kind=text: the literal text. For media: a local file path or an already-set file_path. */
+    source: string;
+    /** Whether `source` is a local file that still needs to be uploaded. */
+    needsUpload: boolean;
+}
+/** Parse a single `--variant` flag value. */
+export declare function parseVariantFlag(raw: string): ParsedVariant;
+export declare function parseVariantFlags(flags: string[]): ParsedVariant[];
+/** Load a JSON manifest (an array of variant entries) from disk. */
+export declare function loadVariantManifest(filePath: string): ParsedVariant[];
+/**
+ * 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 declare function uploadAndBuildVariants(client: ApiClient, productId: string, parsed: ParsedVariant[], opts?: {
+    quiet?: boolean;
+}): Promise<AskVariantInput[]>;
+/**
+ * Convenience: parse flags OR manifest, validate that they're not both set, and
+ * return the parsed list. Caller still has to call `uploadAndBuildVariants`.
+ */
+export declare function parseVariantInputs(opts: {
+    variant?: string[];
+    variants?: string;
+}): ParsedVariant[];