@ishlabs/cli 0.8.3 → 0.8.4

package/dist/commands/study.js

@@ -1,6 +1,7 @@
 /**
  * ish study — Manage studies.
  */
+import { readFileSync } from "node:fs";
 import { withClient, getWebUrl, terminalLink, resolveWorkspace } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
@@ -76,7 +77,7 @@ Concept pages: ish docs get-page concepts/study
     });
     study
         .command("create")
-        .description("Create a new study (the persistent shape: modality, tasks, questionnaire)")
+        .description("Create a new study (the persistent shape: modality, tasks, questionnaire). Optionally creates iteration A inline when --content-text or --url is passed.")
         .option("--workspace <id>", "Workspace ID")
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
@@ -87,13 +88,15 @@ Concept pages: ish docs get-page concepts/study
         .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
         .option("--question <text>", "Add a text question to the questionnaire (repeatable; type=text, timing=after)", collectRepeatable, [])
         .option("--questionnaire <path>", "JSON file defining the questionnaire (supports text, slider, likert, single-choice, multiple-choice, number; timing=before|after)")
+        .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file. Creates iteration A inline (text modality only)")
+        .option("--url <url>", "URL to test. Creates iteration A inline (interactive modality only)")
         .addHelpText("after", `
 Note: --workspace is optional if set via \`ish workspace use <alias>\`.
 
 The questionnaire is the set of questions testers answer. Use \`--question\` to
 quickly add simple text questions, or \`--questionnaire <file.json>\` for richer
-types (slider, likert, choice) and custom timing. The two forms are mutually
-exclusive — pick one.
+types (slider, likert, single-choice, multiple-choice, number) and custom
+timing. The two forms are mutually exclusive — pick one.
 
 Examples:
   # Interactive study with one assignment and a single-question questionnaire:
@@ -145,6 +148,28 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                     throw new ValidationError(`Invalid content type "${opts.contentType}" for modality "${opts.modality}".`, validTypes);
                 }
             }
+            // Pattern E (cli half): build an inline iteration A when --content-text
+            // or --url is provided, so a single `study create` produces a study
+            // that's immediately runnable. Without these flags the backend
+            // creates zero iterations and the first `iteration create` becomes A.
+            let inlineIteration;
+            if (opts.contentText !== undefined) {
+                if (opts.modality && opts.modality !== "text") {
+                    throw new Error(`--content-text is only valid with --modality text (got "${opts.modality}").`);
+                }
+                const text = opts.contentText.startsWith("@")
+                    ? readFileSync(opts.contentText.slice(1), "utf8")
+                    : opts.contentText;
+                inlineIteration = { details: { type: "text", content_text: text } };
+            }
+            else if (opts.url !== undefined) {
+                if (opts.modality && opts.modality !== "interactive") {
+                    throw new Error(`--url is only valid with --modality interactive (got "${opts.modality}").`);
+                }
+                inlineIteration = {
+                    details: { type: "interactive", url: opts.url, platform: "browser" },
+                };
+            }
             const resolvedWs = resolveWorkspace(opts.workspace);
             const body = {
                 product_id: resolvedWs,
@@ -154,6 +179,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 ...(opts.contentType !== undefined && { content_type: opts.contentType }),
                 ...(assignments && { assignments }),
                 ...(interviewQuestions && { interview_questions: interviewQuestions }),
+                ...(inlineIteration && { iteration: inlineIteration }),
             };
             const data = await client.post(`/products/${resolvedWs}/studies`, body);
             if (data.id) {
@@ -198,20 +224,47 @@ Next: configure a run with \`ish iteration create --study <id>\`,
     });
     study
         .command("get")
-        .description("Get study overview (assignments, questions, testers)")
-        .argument("<id>", "Study ID")
-        .addHelpText("after", "\nExamples:\n  $ ish study get <id>\n  $ ish study get <id> --json")
-        .action(async (id, _opts, cmd) => {
+        .description("Get study overview (accepts multiple IDs for batched lookup)")
+        .argument("<ids...>", "Study ID(s) — one or more aliases/UUIDs (space- or comma-separated)")
+        .addHelpText("after", `
+Examples:
+  $ ish study get s-b2c
+  $ ish study get s-b2c --json
+  $ ish study get s-b2c s-d4e s-f0a
+  $ ish study get s-b2c,s-d4e --fields alias,name,modality,status
+
+With multiple IDs, returns a {items:[...], total:N} envelope and uses the
+list table layout in human mode.`)
+        .action(async (ids, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const rid = resolveId(id);
-            const data = await client.get(`/studies/${rid}`);
-            const result = data;
-            if (result.id)
-                result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
-            formatStudyDetail(result, globals.json);
-            if (!globals.json && data.product_id) {
-                const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
-                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            const flat = ids.flatMap((s) => s.split(",").map((x) => x.trim()).filter(Boolean));
+            if (flat.length === 0)
+                throw new Error("Provide at least one study id.");
+            if (flat.length === 1) {
+                const rid = resolveId(flat[0]);
+                const data = await client.get(`/studies/${rid}`);
+                const result = data;
+                if (result.id)
+                    result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+                formatStudyDetail(result, globals.json);
+                if (!globals.json && data.product_id) {
+                    const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                    console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                }
+                return;
+            }
+            const results = await Promise.all(flat.map(async (raw) => {
+                const data = await client.get(`/studies/${resolveId(raw)}`);
+                const r = data;
+                if (r.id)
+                    r.alias = tagAlias(ALIAS_PREFIX.study, String(r.id));
+                return r;
+            }));
+            if (globals.json) {
+                output({ items: results, total: results.length }, true);
+            }
+            else {
+                formatStudyList(results, false);
             }
         });
     });
@@ -219,6 +272,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
         .command("results")
         .description("View aggregated results: tester counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
         .argument("<id>", "Study ID")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .addHelpText("after", `
 Examples:
   $ ish study results <id>
@@ -319,6 +373,7 @@ Examples:
         .command("delete")
         .description("Delete a study")
         .argument("<id>", "Study ID")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .addHelpText("after", "\nExamples:\n  $ ish study delete <id>")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {

package/dist/connect.js

@@ -348,7 +348,7 @@ function manualInstallInstructions() {
 function startCloudflared(port, binPath, json) {
     return new Promise((resolve, reject) => {
         if (!json)
-            console.log(`Connecting to localhost:${port}...`);
+            console.error(`Connecting to localhost:${port}...`);
         const proc = spawn(binPath, ["tunnel", "--url", `http://localhost:${port}`], {
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -368,7 +368,7 @@ function startCloudflared(port, binPath, json) {
                 resolve({ process: proc, tunnelUrl });
             }
         });
-        proc.on("exit", (code) => {
+        proc.on("exit", () => {
             clearTimeout(timeout);
             if (!tunnelUrl) {
                 reject(new Error("cloudflared exited unexpectedly."));
@@ -415,7 +415,7 @@ async function deregisterTunnel(apiUrl, token, json) {
             console.log(JSON.stringify({ status: "disconnected" }));
         }
         else {
-            console.log("Disconnected");
+            console.error("Disconnected");
         }
     }
     catch (e) {
@@ -455,7 +455,7 @@ function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal,
                     const newToken = await doRefresh();
                     onTokenRefreshed(newToken);
                     if (!json)
-                        console.log("Token refreshed.");
+                        console.error("Token refreshed.");
                     // Retry heartbeat with new token
                     const retry = await fetch(`${apiUrl}${API_BASE}/connect/heartbeat`, {
                         method: "POST",
@@ -514,7 +514,7 @@ function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, json) {
             const newToken = await doRefresh();
             onTokenRefreshed(newToken);
             if (!json)
-                console.log("Token proactively refreshed.");
+                console.error("Token proactively refreshed.");
             // Schedule next refresh for the new token
             scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed, json);
         }
@@ -583,7 +583,7 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
             process.exit(1);
         shuttingDown = true;
         if (!json)
-            console.log("\nShutting down...");
+            console.error("\nShutting down...");
         heartbeat.stop();
         proactiveRefresh.stop();
         cfProcess.kill();
@@ -593,7 +593,7 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     if (!json && !quiet) {
-        console.log("Press Ctrl+C to disconnect.\n");
+        console.error("Press Ctrl+C to disconnect.\n");
     }
     cfProcess.on("exit", async () => {
         if (!shuttingDown) {

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program, Option } from "commander";
 import { runTunnel } from "./connect.js";
-import { login, getAppUrl } from "./auth.js";
+import { login, getAppUrl, decodeJwtClaims } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
@@ -14,8 +14,12 @@ 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 { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
+import { resolveApiUrl, resolveToken } from "./lib/auth.js";
+import { ApiClient } from "./lib/api-client.js";
+import { tagAlias, ALIAS_PREFIX } from "./lib/alias-store.js";
 import { output } from "./lib/output.js";
+import { ishDir } from "./lib/paths.js";
 import pkg from "../package.json" with { type: "json" };
 const { version } = pkg;
 program
@@ -98,6 +102,118 @@ program
         output({ message: "Logged out" }, globals.json);
     });
 });
+program
+    .command("status")
+    .alias("whoami")
+    .description("Show active session — user, workspace, study, ask")
+    .addHelpText("after", "\nFirst command to run when starting cold. Outputs the active workspace,\nstudy, and ask handles plus token validity. Doesn't error on no-token —\nreturns user: null with a hint instead. JSON safe for piping.")
+    .action(async (_opts, cmd) => {
+    await runInline(cmd, async (globals) => {
+        const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+        const config = loadConfig();
+        // Try to resolve a token; on auth failure, return a no-token status
+        // instead of throwing so the command works pre-login.
+        let token;
+        let tokenError;
+        try {
+            token = await resolveToken(globals.token, apiUrl, globals.tokenFile);
+        }
+        catch (err) {
+            tokenError = err instanceof Error ? err.message : String(err);
+        }
+        let user = null;
+        if (token) {
+            const claims = decodeJwtClaims(token);
+            const exp = typeof claims?.exp === "number" ? claims.exp : 0;
+            const expiresIn = exp ? Math.max(0, exp - Math.floor(Date.now() / 1000)) : 0;
+            user = {
+                email: typeof claims?.email === "string" ? claims.email : null,
+                token_valid: expiresIn > 0,
+                expires_in_seconds: expiresIn,
+            };
+        }
+        // Resolve names of active resources. Failures are non-fatal — we still
+        // return the saved IDs so the user knows what's configured.
+        const client = token ? new ApiClient({ apiUrl, token }) : null;
+        let workspace = null;
+        if (config.workspace) {
+            workspace = {
+                id: config.workspace,
+                alias: tagAlias(ALIAS_PREFIX.workspace, config.workspace),
+            };
+            if (client) {
+                try {
+                    const ws = await client.get(`/products/${config.workspace}`);
+                    if (ws?.name)
+                        workspace.name = ws.name;
+                }
+                catch { /* keep id+alias only */ }
+            }
+        }
+        let study = null;
+        if (config.study) {
+            study = {
+                id: config.study,
+                alias: tagAlias(ALIAS_PREFIX.study, config.study),
+            };
+            if (client) {
+                try {
+                    const s = await client.get(`/studies/${config.study}`);
+                    if (s?.name)
+                        study.name = s.name;
+                }
+                catch { /* keep id+alias only */ }
+            }
+        }
+        let ask = null;
+        if (config.ask) {
+            ask = {
+                id: config.ask,
+                alias: tagAlias(ALIAS_PREFIX.ask, config.ask),
+            };
+            if (client) {
+                try {
+                    const a = await client.get(`/asks/${config.ask}`);
+                    if (a?.name)
+                        ask.name = a.name;
+                }
+                catch { /* keep id+alias only */ }
+            }
+        }
+        const payload = {
+            user,
+            workspace,
+            study,
+            ask,
+            api_url: apiUrl,
+            home: ishDir(),
+        };
+        if (tokenError && !token)
+            payload.hint = `Run \`ish login\`. (${tokenError})`;
+        if (globals.json) {
+            output(payload, true);
+            return;
+        }
+        // Human output
+        const fmtSeconds = (s) => {
+            if (s <= 0)
+                return "expired";
+            const m = Math.floor(s / 60);
+            const h = Math.floor(m / 60);
+            if (h > 0)
+                return `${h}h${m % 60}m`;
+            return `${m}m`;
+        };
+        console.log(`User:       ${user ? `${user.email ?? "(no email)"}  (token ${user.token_valid ? "valid" : "expired"}, expires in ${fmtSeconds(user.expires_in_seconds)})` : "(not logged in — run `ish login`)"}`);
+        console.log(`Workspace:  ${workspace ? `${workspace.name ?? "(name unavailable)"} (${workspace.alias})` : "—"}`);
+        console.log(`Study:      ${study ? `${study.name ?? "(name unavailable)"} (${study.alias})` : "—"}`);
+        console.log(`Ask:        ${ask ? `${ask.name ?? "(name unavailable)"} (${ask.alias})` : "—"}`);
+        console.log(`Home:       ${ishDir()}`);
+        console.log(`API:        ${apiUrl}`);
+        if (tokenError && !token)
+            console.error(`\nHint: ${payload.hint}`);
+    });
+});
 program
     .command("connect")
     .description("Expose your localhost to Ish via a Cloudflare tunnel")
@@ -134,4 +250,5 @@ program
     .action(async (options) => {
     await upgrade(version, options.release);
 });
+injectGlobalWorkspaceOption(program);
 program.parse();

package/dist/lib/api-client.js

@@ -31,15 +31,30 @@ export class ApiError extends Error {
     error_code;
     retryable;
     constructor(status, statusText, body) {
-        const msg = typeof body === "object" && body !== null && "detail" in body
-            ? String(body.detail)
-            : `HTTP ${status} ${statusText}`;
+        // FastAPI HTTPException(detail=...) wraps detail under a top-level "detail" key.
+        // When detail is a structured object (our convention for typed errors),
+        // pull the message off detail.detail and prefer detail.error_code.
+        let detail;
+        let bodyErrorCode;
+        if (typeof body === "object" && body !== null && "detail" in body) {
+            detail = body.detail;
+            if (typeof detail === "object" && detail !== null && "error_code" in detail
+                && typeof detail.error_code === "string") {
+                bodyErrorCode = detail.error_code;
+            }
+        }
+        const detailMsg = typeof detail === "string"
+            ? detail
+            : (typeof detail === "object" && detail !== null && "detail" in detail
+                ? String(detail.detail)
+                : undefined);
+        const msg = detailMsg ?? `HTTP ${status} ${statusText}`;
         super(msg);
         this.status = status;
         this.statusText = statusText;
         this.body = body;
         this.name = "ApiError";
-        this.error_code = mapErrorCode(status);
+        this.error_code = bodyErrorCode ?? mapErrorCode(status);
         this.retryable = isRetryable(status);
     }
 }
@@ -176,7 +191,9 @@ export class ApiClient {
         return this.handleResponse(res);
     }
     async del(path, opts) {
-        const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+        // Deletes typically cascade (rounds → responses → testers → audience),
+        // so default to a longer timeout than the standard 15s.
+        const timeout = opts?.timeout ?? 60_000;
         const url = `${this.baseUrl}${path}`;
         let res;
         try {
@@ -187,8 +204,13 @@ export class ApiClient {
             });
         }
         catch (err) {
-            if (isAbortTimeout(err))
-                throw timeoutError("DELETE", timeout);
+            if (isAbortTimeout(err)) {
+                const seconds = Math.round(timeout / 1000);
+                throw new ApiError(408, "Request Timeout", {
+                    detail: `DELETE request timed out after ${seconds}s. The deletion may have completed server-side — ` +
+                        `re-fetch the resource (e.g. \`ish ask get <id>\`) before retrying to avoid a 404.`,
+                });
+            }
             if (err instanceof TypeError)
                 throw networkError(url);
             throw err;

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

@@ -100,3 +100,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

@@ -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).`);
     }
@@ -355,3 +358,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);
+    }
+}