@ishlabs/cli 0.8.4 → 0.9.0

package/dist/commands/profile.js

@@ -40,7 +40,12 @@ Examples:
   $ ish profile list
   $ ish profile list --search "engineer" --country US
   $ ish profile list --gender female --gender male --country US --country GB
-  $ ish profile list --type all --json`)
+  $ ish profile list --type all --json
+
+  # Pagination — default --limit is 50; iterate with --offset:
+  $ ish profile list --limit 100
+  $ ish profile list --limit 100 --offset 100   # next page
+  # When more results exist, a stderr hint surfaces the next --offset / --limit.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const params = {
@@ -63,18 +68,26 @@ Examples:
             const data = await client.get("/tester-profiles", params);
             formatTesterProfileList(data, globals.json, parseInt(opts.limit, 10));
             // Pattern H1: when there's more data, surface a stderr hint so agents
-            // know `--limit / --offset` exist without re-reading help. Only when
-            // not in JSON mode and not silenced — JSON consumers read has_more
-            // off the envelope themselves; quiet suppresses progress chatter.
-            if (!globals.json && !globals.quiet && typeof data === "object" && data !== null) {
+            // know `--limit / --offset` exist without re-reading help. Stderr only,
+            // so it doesn't pollute machine-readable stdout — that means we DON'T
+            // gate on globals.json (auto-flips on pipe and would silence the hint
+            // exactly when the agent needs it most). --quiet is the explicit
+            // opt-out for progress chatter.
+            //
+            // The raw `/tester-profiles` envelope is `{items, total, limit, offset}`
+            // — `has_more` and `returned` are synthesized client-side by `wrapList`
+            // only when the response is rendered. Compute them locally here so the
+            // hint actually fires; reading `data.has_more` directly would always
+            // see undefined and silently skip.
+            if (!globals.quietExplicit && typeof data === "object" && data !== null) {
                 const d = data;
-                if (d.has_more === true) {
-                    const total = typeof d.total === "number" ? d.total : null;
-                    const returned = typeof d.returned === "number" ? d.returned : null;
-                    const offset = typeof d.offset === "number" ? d.offset : 0;
-                    if (total !== null && returned !== null) {
-                        console.error(`\n  showing ${offset + 1}–${offset + returned} of ${total}; pass --offset ${offset + returned} --limit ${returned} for more.`);
-                    }
+                const items = Array.isArray(d.items) ? d.items : [];
+                const returned = items.length;
+                const total = typeof d.total === "number" ? d.total : returned;
+                const offset = typeof d.offset === "number" ? d.offset : parseInt(opts.offset, 10) || 0;
+                const hasMore = total > offset + returned;
+                if (hasMore && returned > 0) {
+                    console.error(`\n  showing ${offset + 1}–${offset + returned} of ${total}; pass --offset ${offset + returned} --limit ${returned} for more.`);
                 }
             }
         });

package/dist/commands/source.js

@@ -7,8 +7,8 @@
  * generation runs, or to inspect processing status.
  */
 import { withClient, resolveWorkspace } from "../lib/command-helpers.js";
-import { resolveId } from "../lib/alias-store.js";
-import { formatAudienceSource } from "../lib/output.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { formatAudienceSource, output } from "../lib/output.js";
 import { inferSourceKind, uploadAndProcessSource, } from "../lib/profile-sources.js";
 const VALID_KINDS = ["text_file", "audio", "image"];
 export function registerSourceCommands(program) {
@@ -75,4 +75,26 @@ Examples:
             formatAudienceSource(src, globals.json);
         });
     });
+    source
+        .command("delete")
+        .description("Delete an audience source plus its uploaded file")
+        .argument("<id>", "Source ID or alias")
+        .addHelpText("after", `
+Removes both the database row and the underlying uploaded file. Profiles
+already generated from this source remain in place — they don't reference
+the source after generation.
+
+Examples:
+  $ ish source delete tps-3a4`)
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            await client.del(`/tester-profiles/sources/${rid}`);
+            output({
+                id: rid,
+                alias: tagAlias(ALIAS_PREFIX.testerProfileSource, rid),
+                message: "Source deleted",
+            }, globals.json, { writePath: true });
+        });
+    });
 }

package/dist/commands/study.js

@@ -2,7 +2,7 @@
  * ish study — Manage studies.
  */
 import { readFileSync } from "node:fs";
-import { withClient, getWebUrl, terminalLink, resolveWorkspace } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
 import { formatStudyList, formatStudyDetail, formatStudyResults, output, ValidationError } from "../lib/output.js";
@@ -81,7 +81,7 @@ Concept pages: ish docs get-page concepts/study
         .option("--workspace <id>", "Workspace ID")
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
-        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document)")
+        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
         .option("--content-type <type>", "Content type (varies by modality — see examples below)")
         .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
@@ -152,6 +152,8 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             // 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.
+            // The backend requires a non-empty `name` on the inline iteration; we
+            // default to "A" to match the iteration-naming convention.
             let inlineIteration;
             if (opts.contentText !== undefined) {
                 if (opts.modality && opts.modality !== "text") {
@@ -160,13 +162,14 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 const text = opts.contentText.startsWith("@")
                     ? readFileSync(opts.contentText.slice(1), "utf8")
                     : opts.contentText;
-                inlineIteration = { details: { type: "text", content_text: text } };
+                inlineIteration = { name: "A", 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 = {
+                    name: "A",
                     details: { type: "interactive", url: opts.url, platform: "browser" },
                 };
             }
@@ -314,7 +317,7 @@ When no runs have completed, the same envelope is returned with zero counts and
         .option("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--status <status>", "Study status (draft, running, completed)")
-        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document)")
+        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
         .option("--content-type <type>", "Content type")
         .option("--assignment <name:instructions>", "Replace all assignments with these (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
@@ -374,10 +377,15 @@ Examples:
         .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) => {
+        .option("-y, --yes", "Skip confirmation prompt (required in --json or non-TTY contexts)")
+        .addHelpText("after", "\nExamples:\n  $ ish study delete <id>           # interactive — prompts for confirmation\n  $ ish study delete <id> --yes     # non-interactive\n  $ ish study delete <id> --json --yes")
+        .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const rid = resolveId(id);
+            await confirmDestructive(`Delete study ${tagAlias(ALIAS_PREFIX.study, rid)}? This cannot be undone.`, {
+                yes: opts.yes,
+                json: globals.json,
+            });
             await client.del(`/studies/${rid}`);
             output({ id: rid, alias: tagAlias(ALIAS_PREFIX.study, rid), message: "Study deleted" }, globals.json, { writePath: true });
         });

package/dist/config.d.ts

@@ -5,6 +5,10 @@
 export interface IshConfig {
     access_token?: string;
     refresh_token?: string;
+    /** OAuth client_id minted by Supabase DCR at last login. Required to refresh
+     *  tokens issued by Supabase OAuth Server (public client → must include
+     *  client_id on refresh). Absent for legacy/non-OAuth tokens. */
+    oauth_client_id?: string;
     token?: string;
     workspace?: string;
     study?: string;

package/dist/connect.js

@@ -5,7 +5,7 @@ import { spawn, execSync } from "node:child_process";
 import { existsSync, mkdirSync, chmodSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, saveConfig } from "./config.js";
-import { refreshTokens, isTokenExpired, decodeJwtExp } from "./auth.js";
+import { refreshTokens, isTokenExpired, decodeJwtExp, AuthRefreshPermanentError } from "./auth.js";
 import { binDir, cloudflaredBin, simulationsDir } from "./lib/paths.js";
 import { c } from "./lib/colors.js";
 const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
@@ -233,8 +233,14 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
         let accessToken = config.access_token;
         // Refresh if expired or close to expiry
         if (isTokenExpired(accessToken)) {
+            if (!config.oauth_client_id) {
+                throw new Error('Saved tokens are missing oauth_client_id. Run "ish login" to re-authenticate.');
+            }
             try {
-                const tokens = await refreshTokens(config.refresh_token);
+                const tokens = await refreshTokens(config.refresh_token, {
+                    accessToken,
+                    clientId: config.oauth_client_id,
+                });
                 accessToken = tokens.accessToken;
                 config.access_token = tokens.accessToken;
                 config.refresh_token = tokens.refreshToken;
@@ -250,7 +256,12 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
                 const cfg = loadConfig();
                 if (!cfg.refresh_token)
                     throw new Error("No refresh token");
-                const tokens = await refreshTokens(cfg.refresh_token);
+                if (!cfg.oauth_client_id)
+                    throw new Error('Missing oauth_client_id; run "ish login" again.');
+                const tokens = await refreshTokens(cfg.refresh_token, {
+                    accessToken: cfg.access_token,
+                    clientId: cfg.oauth_client_id,
+                });
                 cfg.access_token = tokens.accessToken;
                 cfg.refresh_token = tokens.refreshToken;
                 saveConfig(cfg);
@@ -402,7 +413,14 @@ async function registerTunnel(apiUrl, token, tunnelUrl, port) {
         return false;
     }
 }
-async function deregisterTunnel(apiUrl, token, json) {
+/**
+ * Best-effort deregister. When `suppressAuthFailures` is true (we're already
+ * shutting down because of an auth-permanent failure), 401/403 errors during
+ * deregister are silently swallowed — logging "Failed to deregister: HTTP 401"
+ * right after telling the user their auth expired is ironic and noisy.
+ * Non-auth failures are still logged.
+ */
+async function deregisterTunnel(apiUrl, token, json, suppressAuthFailures = false) {
     try {
         const resp = await fetch(`${apiUrl}${API_BASE}/connect`, {
             method: "DELETE",
@@ -419,9 +437,28 @@ async function deregisterTunnel(apiUrl, token, json) {
         }
     }
     catch (e) {
+        if (suppressAuthFailures && /HTTP (401|403)/.test(String(e)))
+            return;
         console.error(`Warning: Failed to deregister connection: ${e}`);
     }
 }
+/**
+ * Classify whether a thrown error from the auth refresh path is permanent.
+ * Permanent = "the local config can't recover, user must `ish login` again."
+ * Examples: Supabase `refresh_token_not_found`, `invalid_grant`, any 4xx on
+ * the refresh endpoint. Network blips and 5xx are NOT permanent.
+ *
+ * The typed sentinel from `src/auth.ts` is the primary signal. We also string-
+ * match legacy error messages in case something throws a plain Error.
+ */
+function isPermanentAuthFailure(err) {
+    if (err instanceof AuthRefreshPermanentError)
+        return true;
+    if (err instanceof Error) {
+        return /refresh_token_not_found|invalid_grant|Token refresh failed \(HTTP 4\d\d/i.test(err.message);
+    }
+    return false;
+}
 function processHeartbeatResponse(resp, renderCards) {
     resp.json().then((data) => {
         const sims = data.simulations ?? [];
@@ -437,7 +474,7 @@ function processHeartbeatResponse(resp, renderCards) {
         // Non-fatal: response parsing failed, silently continue
     });
 }
-function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal, json) {
+function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal, onAuthPermanent, json) {
     let consecutiveFailures = 0;
     let stopped = false;
     const interval = setInterval(async () => {
@@ -469,6 +506,15 @@ function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal,
                     return;
                 }
                 catch (refreshErr) {
+                    // Permanent refresh failure (refresh_token_not_found etc.) — no
+                    // amount of retrying will fix this. Bail out immediately with an
+                    // actionable message; don't waste the 3-strike countdown.
+                    if (isPermanentAuthFailure(refreshErr)) {
+                        stopped = true;
+                        clearInterval(interval);
+                        await onAuthPermanent(refreshErr);
+                        return;
+                    }
                     console.error(`Token refresh failed: ${refreshErr}`);
                 }
             }
@@ -499,7 +545,7 @@ function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal,
  * Schedule a proactive token refresh before the JWT expires.
  * Refreshes 10 minutes before expiry.
  */
-function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, json) {
+function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, onAuthPermanent, json) {
     if (!doRefresh)
         return { stop: () => { } };
     const exp = decodeJwtExp(token);
@@ -516,9 +562,15 @@ function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, json) {
             if (!json)
                 console.error("Token proactively refreshed.");
             // Schedule next refresh for the new token
-            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed, json);
+            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed, onAuthPermanent, json);
         }
         catch (e) {
+            // Permanent refresh failure: short-circuit to the actionable message
+            // path instead of letting the next heartbeat eat 3 strikes.
+            if (isPermanentAuthFailure(e)) {
+                await onAuthPermanent(e);
+                return;
+            }
             console.error(`Proactive token refresh failed: ${e}`);
         }
     }, delay);
@@ -572,20 +624,54 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         console.log(`Tunnel URL: ${tunnelUrl} → http://localhost:${port}\n`);
     }
     let shuttingDown = false;
-    const heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
+    // Holders for forward references — `onAuthPermanent` needs to stop these
+    // timers, but `startHeartbeat`/`scheduleProactiveRefresh` need
+    // `onAuthPermanent` to wire up. Declared as nullable, assigned just below.
+    let heartbeat = null;
+    let proactiveRefresh = null;
+    // Fast-fail path for non-recoverable auth failures (e.g. Supabase
+    // refresh_token_not_found). Skips the 3-strike heartbeat countdown and
+    // gives the user a single actionable next step.
+    const onAuthPermanent = async (cause) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        heartbeat?.stop();
+        proactiveRefresh?.stop();
+        if (json) {
+            console.error(JSON.stringify({
+                status: "auth_expired",
+                message: `Authentication expired. Run \`ish login\` and re-run \`ish connect ${port}\`.`,
+                detail: "refresh_token expired or revoked; the local config can't recover",
+            }));
+        }
+        else {
+            console.error(`\nAuthentication expired. Run \`ish login\` and re-run \`ish connect ${port}\`.`);
+            console.error("(refresh_token expired or revoked; the local config can't recover)");
+        }
+        if (cause instanceof Error && cause.message) {
+            // Keep the underlying detail discoverable for log scrapers / agents,
+            // without making it the headline.
+            console.error(`Cause: ${cause.message}`);
+        }
+        await deregisterTunnel(apiUrl, currentToken, json, true);
+        cfProcess.kill();
+        process.exit(3);
+    };
+    heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
         await deregisterTunnel(apiUrl, currentToken, json);
         cfProcess.kill();
         process.exit(1);
-    }, json);
-    const proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed, json);
+    }, onAuthPermanent, json);
+    proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed, onAuthPermanent, json);
     const shutdown = async () => {
         if (shuttingDown)
             process.exit(1);
         shuttingDown = true;
         if (!json)
             console.error("\nShutting down...");
-        heartbeat.stop();
-        proactiveRefresh.stop();
+        heartbeat?.stop();
+        proactiveRefresh?.stop();
         cfProcess.kill();
         await deregisterTunnel(apiUrl, currentToken, json);
         process.exit(0);
@@ -597,8 +683,8 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
     }
     cfProcess.on("exit", async () => {
         if (!shuttingDown) {
-            heartbeat.stop();
-            proactiveRefresh.stop();
+            heartbeat?.stop();
+            proactiveRefresh?.stop();
             await deregisterTunnel(apiUrl, currentToken, json);
             process.exit(0);
         }

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, decodeJwtClaims } from "./auth.js";
+import { login, decodeJwtClaims } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
@@ -69,7 +69,10 @@ program
     .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("--workspace <id>", "Default workspace ID; per-subcommand --workspace overrides")
     .option("--json", "Output as JSON (auto-enabled when piped)")
+    .option("--get <field>", "Extract a single field from the JSON response and print only its value (implies --json internally; supports dotted paths e.g. tester_profile.name)")
+    .option("--human", "Force human-readable output even when stdout is piped (overrides JSON-when-piped auto-detection)")
     .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("--no-color", "Disable colored output (also honored: NO_COLOR env var)")
@@ -80,11 +83,11 @@ program
     .description("Authenticate with Ish via your browser")
     .action(async (_opts, cmd) => {
     await runInline(cmd, async (globals) => {
-        const appUrl = globals.dev ? "http://localhost:3000" : getAppUrl();
-        const tokens = await login(appUrl);
+        const tokens = await login();
         const config = loadConfig();
         config.access_token = tokens.accessToken;
         config.refresh_token = tokens.refreshToken;
+        config.oauth_client_id = tokens.clientId;
         saveConfig(config);
         output({ message: "Login successful" }, globals.json);
     });

package/dist/lib/auth.js

@@ -57,8 +57,14 @@ export async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
         let accessToken = config.access_token;
         // Refresh if expired or close to expiry
         if (isTokenExpired(accessToken)) {
+            if (!config.oauth_client_id) {
+                throw new Error('Saved tokens are missing oauth_client_id. Run "ish login" to re-authenticate.');
+            }
             try {
-                const tokens = await refreshTokens(config.refresh_token, { accessToken });
+                const tokens = await refreshTokens(config.refresh_token, {
+                    accessToken,
+                    clientId: config.oauth_client_id,
+                });
                 accessToken = tokens.accessToken;
                 config.access_token = tokens.accessToken;
                 config.refresh_token = tokens.refreshToken;

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

@@ -58,6 +58,33 @@ export interface GlobalOpts {
     quiet: boolean;
     color: boolean;
     fields?: string[];
+    /**
+     * --get <field>: capture mode. Extracts a single field from the JSON
+     * response and prints its bare value. Implies --json internally so the
+     * renderer always has structured data to extract from.
+     */
+    get?: string;
+    /**
+     * --human: forces the human renderer regardless of TTY/pipe state.
+     * Mutually exclusive with --get (capture vs display).
+     */
+    human?: boolean;
+    /**
+     * Program-level --workspace from the root flag. Subcommand-level --workspace
+     * still wins via Commander's optsWithGlobals merge (subcommand opts override
+     * parent), so this is effectively the "default workspace for the invocation"
+     * agents reflexively pass at the program root.
+     */
+    workspace?: string;
+    /**
+     * True only when the user explicitly passed `--quiet` / `-q` (or `--get`).
+     * Distinct from `quiet`, which also flips on for auto-quiet (the
+     * piped-stdout/auto-JSON path). Use this for actionable hints (e.g. the
+     * `profile list` pagination hint) that should still surface when an agent
+     * pipes output but hasn't asked for silence — auto-quiet is for progress
+     * chatter, not diagnostic signals.
+     */
+    quietExplicit: boolean;
 }
 export declare function getGlobals(cmd: Command): GlobalOpts;
 /**
@@ -83,6 +110,16 @@ export declare function runInline(cmd: Command, fn: (globals: GlobalOpts) => Pro
 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>;
+/**
+ * Prompt for confirmation of a destructive action, or short-circuit when
+ * `--yes` is set. In `--json` mode without `--yes` we refuse with a usage
+ * error rather than silently proceeding or hanging on a prompt — agents
+ * piping through CLI must be explicit about destructive intent.
+ */
+export declare function confirmDestructive(prompt: string, opts: {
+    yes?: boolean;
+    json?: boolean;
+}): Promise<void>;
 export declare function resolveWorkspace(explicit?: string): string;
 export declare function resolveStudy(explicit?: string): string;
 export declare function resolveAsk(explicit?: string): string;