@ishlabs/cli 0.9.0 → 0.10.0

package/dist/lib/alias-hydrate.js

@@ -0,0 +1,175 @@
+/**
+ * Best-effort alias-cache hydration on alias-miss (Pattern F).
+ *
+ * The CLI persists aliases to ``~/.ish/aliases.json``, so the cache survives
+ * across processes. Where it bites: the file is missing/empty (fresh install,
+ * `rm ~/.ish/aliases.json`, agent running in a sandbox with a fresh
+ * `ISH_HOME`) and the agent has an alias from a prior process or the docs.
+ *
+ * ``resolveIdAsync(input, client, hints?)`` mirrors the sync ``resolveId``
+ * contract but, on alias-miss, attempts a single ``GET /list`` to repopulate
+ * the cache before retrying. The hydrate is BEST-EFFORT: a failing list
+ * call is swallowed and the canonical "Unknown alias" error fires with the
+ * actionable suggestion in the message.
+ *
+ * For prefixes whose list endpoint requires a parent ID (study/iteration/
+ * ask/etc), the caller passes ``hints`` carrying the parent (workspaceId,
+ * studyId). Without a parent we skip the hydrate — global N+1 fan-out is
+ * too expensive for a papercut.
+ */
+import { ALIAS_PREFIX, resolveId, tagAlias } from "./alias-store.js";
+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 ALIAS_RE = /^[a-z]+-[0-9a-f]{3,}$|^[a-z]+\d{2,}$/;
+function aliasPrefix(value) {
+    if (!ALIAS_RE.test(value))
+        return null;
+    const m = value.match(/^([a-z]+)/);
+    return m ? m[1] : null;
+}
+function isAliasShape(value) {
+    return ALIAS_RE.test(value);
+}
+function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/**
+ * Try to resolve a parent ID — accepts either a UUID or a known alias. Used
+ * to extract ``workspaceId`` / ``studyId`` from hints before we fan out to a
+ * scoped list endpoint. Returns ``null`` if the value can't be resolved
+ * cheaply (e.g. it's an alias that's also missing from the cache).
+ */
+function resolveParent(value) {
+    if (!value)
+        return null;
+    if (isUuid(value))
+        return value;
+    // Try the sync resolver but never throw.
+    try {
+        return resolveId(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hit a list endpoint and tag every returned ID under the given prefix.
+ * Silently swallows network/auth failures — we only ever block the
+ * underlying call when the alias is genuinely unknown after hydrate.
+ */
+async function hydrateList(client, prefix, path, params) {
+    let data;
+    try {
+        data = await client.get(path, params);
+    }
+    catch {
+        return;
+    }
+    let items = [];
+    if (Array.isArray(data)) {
+        items = data;
+    }
+    else if (typeof data === "object" && data !== null && "items" in data) {
+        const inner = data.items;
+        if (Array.isArray(inner))
+            items = inner;
+    }
+    for (const item of items) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const id = item.id;
+        if (typeof id === "string" && id.length > 0) {
+            try {
+                tagAlias(prefix, id);
+            }
+            catch {
+                // Ignore — bad UUIDs are not catastrophic.
+            }
+        }
+    }
+}
+/**
+ * Best-effort hydrate of the alias cache for ``alias``'s entity type. Returns
+ * silently on success or any failure — the caller checks the cache after
+ * this returns.
+ */
+export async function hydrateForAlias(client, alias, hints = {}) {
+    const prefix = aliasPrefix(alias);
+    if (!prefix)
+        return;
+    const ws = resolveParent(hints.workspaceId);
+    const study = resolveParent(hints.studyId);
+    switch (prefix) {
+        case ALIAS_PREFIX.workspace: {
+            // Top-level — no parent.
+            await hydrateList(client, ALIAS_PREFIX.workspace, "/products");
+            return;
+        }
+        case ALIAS_PREFIX.study: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.study, `/products/${ws}/studies`);
+            return;
+        }
+        case ALIAS_PREFIX.iteration: {
+            if (!study)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.iteration, `/studies/${study}/iterations`);
+            return;
+        }
+        case ALIAS_PREFIX.testerProfile: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.testerProfile, "/tester-profiles", { workspace_id: ws, type: "all", limit: "200" });
+            return;
+        }
+        case ALIAS_PREFIX.ask: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.ask, `/products/${ws}/asks`);
+            return;
+        }
+        case ALIAS_PREFIX.chatEndpoint: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.chatEndpoint, `/products/${ws}/chatbot-endpoints`);
+            return;
+        }
+        // No cheap single-call hydrate for the rest:
+        //   tester (`t-`)         — scoped to iteration
+        //   ask round (`r-`)      — nested on the ask
+        //   audience source (`tps-`) — fetched per-id
+        //   simulation config (`c-`) — no list endpoint yet
+        default:
+            return;
+    }
+}
+/**
+ * Async sibling of ``resolveId``: same UUID-or-alias contract, but on
+ * alias-miss attempts a best-effort hydrate via the matching list endpoint
+ * before retrying. Falls back to the canonical "Unknown alias" error
+ * (with named list-command suggestion) when the alias is still missing
+ * after the hydrate.
+ *
+ * Use this at command-handler entry points where the agent supplies an
+ * alias and the same call carries enough context (workspace / study) to
+ * scope the hydrate cheaply.
+ */
+export async function resolveIdAsync(input, client, hints = {}) {
+    if (isUuid(input))
+        return input;
+    if (!isAliasShape(input)) {
+        // Fall through to the sync resolver so the "Invalid ID" guidance fires.
+        return resolveId(input);
+    }
+    // Cheap-path: alias already in store.
+    try {
+        return resolveId(input);
+    }
+    catch {
+        // Cache miss — attempt best-effort hydrate.
+        await hydrateForAlias(client, input, hints);
+        // Retry — sync resolver re-reads ``aliases.json`` from disk on every
+        // call (see loadAliases), so the freshly tagged entries are visible.
+        return resolveId(input);
+    }
+}

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

@@ -17,6 +17,7 @@ export declare const ALIAS_PREFIX: {
     readonly job: "j";
     readonly ask: "a";
     readonly askRound: "r";
+    readonly chatEndpoint: "ep";
 };
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/alias-store.js

@@ -20,6 +20,7 @@ export const ALIAS_PREFIX = {
     job: "j",
     ask: "a",
     askRound: "r",
+    chatEndpoint: "ep",
 };
 /** Format a number with zero-padding (minimum 2 digits). */
 function padNum(n) {
@@ -110,6 +111,32 @@ export function deterministicAlias(prefix, uuid) {
 }
 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 ALIAS_RE = /^[a-z]+-[0-9a-f]{3,}$|^[a-z]+\d{2,}$/;
+/**
+ * Suggested `ish ... list` command per alias prefix. Surfaced in the
+ * unknown-alias error (Pattern F) so the agent doesn't have to guess
+ * which list command to run.
+ */
+const HYDRATE_HINT = {
+    w: "ish workspace list",
+    s: "ish study list",
+    i: "ish iteration list --study <study-id>",
+    tp: "ish profile list",
+    tps: "ish source list",
+    t: "ish tester get <tester-id>",
+    c: "ish config list",
+    a: "ish ask list",
+    r: "ish ask get <ask-id>",
+    ep: "ish chat endpoint list",
+    // Legacy two-letter prefixes the deterministic generator may have
+    // produced before; defaults below cover anything else.
+};
+function hintForPrefix(alias) {
+    // Pull the leading alpha run, which is the prefix.
+    const m = alias.match(/^([a-z]+)/);
+    if (!m)
+        return "the matching list command";
+    return HYDRATE_HINT[m[1]] ?? "the matching list command";
+}
 /**
  * Resolve a short alias to a full UUID, or validate and pass through a full UUID.
  *
@@ -130,7 +157,7 @@ export function resolveId(input) {
         const uuid = aliases[input];
         if (uuid)
             return uuid;
-        throw new Error(`Unknown alias "${input}". Run a list command first to generate aliases.`);
+        throw new Error(`Unknown alias "${input}". Run \`${hintForPrefix(input)}\` first to generate aliases.`);
     }
     // 3. Anything else — fail with helpful guidance
     throw new Error(`Invalid ID "${input}". Use a short alias (e.g. w-a3f, s-b2c) or a full UUID.\n` +

package/dist/lib/auth.js

@@ -24,8 +24,10 @@ async function verifyToken(token, apiUrl) {
         return resp.status !== 401 && resp.status !== 403;
     }
     catch {
-        // Network error — can't verify, assume ok
-        console.error("Warning: Could not verify token (network error). Proceeding anyway.");
+        // Network blip on the best-effort probe. The subsequent API call will
+        // surface the real auth failure (with a proper exit code 3) if there
+        // is one, so don't pollute stderr on every command — it fired on
+        // every successful run during Phase A (Pattern F / C4-finding-5).
         return true;
     }
 }

package/dist/lib/chat-endpoint-formatters.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lean-vs-verbose projection for ChatbotEndpointResponse.
+ *
+ * The backend returns a nested camelCase shape (id, name, productId, config,
+ * isTunnelBacked, createdAt, updatedAt). The lean projection keeps only the
+ * fields an agent typically branches on: id/alias/name, transport, the
+ * outgoing url + method, the incoming messagePath, the slot-path count, and
+ * isTunnelBacked. `--verbose` (or piped) passes the raw response.
+ */
+export interface OutgoingHttp {
+    url?: string;
+    method?: string;
+    mode?: string;
+    [key: string]: unknown;
+}
+export interface IncomingHttp {
+    messagePath?: string;
+    slotsContainerPaths?: string[];
+    [key: string]: unknown;
+}
+export interface ChatbotEndpointConfig {
+    transport?: string;
+    outgoing?: OutgoingHttp;
+    incoming?: IncomingHttp;
+    isTunnelBacked?: boolean;
+    [key: string]: unknown;
+}
+export interface ChatbotEndpointRow {
+    id?: string;
+    name?: string;
+    productId?: string;
+    config?: ChatbotEndpointConfig;
+    isTunnelBacked?: boolean;
+    [key: string]: unknown;
+}
+/** Return the round-trippable envelope used by `endpoint get --verbose`. */
+export declare function envelopeFromRow(row: ChatbotEndpointRow): Record<string, unknown>;
+export declare function formatChatEndpointList(rows: ChatbotEndpointRow[], json: boolean, verbose: boolean): void;
+export declare function formatChatEndpointDetail(row: ChatbotEndpointRow, json: boolean, verbose: boolean): void;

package/dist/lib/chat-endpoint-formatters.js

@@ -0,0 +1,104 @@
+/**
+ * Lean-vs-verbose projection for ChatbotEndpointResponse.
+ *
+ * The backend returns a nested camelCase shape (id, name, productId, config,
+ * isTunnelBacked, createdAt, updatedAt). The lean projection keeps only the
+ * fields an agent typically branches on: id/alias/name, transport, the
+ * outgoing url + method, the incoming messagePath, the slot-path count, and
+ * isTunnelBacked. `--verbose` (or piped) passes the raw response.
+ */
+import { tagAlias, ALIAS_PREFIX } from "./alias-store.js";
+import { output, printTable } from "./output.js";
+function leanRow(row) {
+    const cfg = row.config ?? {};
+    const out = {};
+    if (row.id)
+        out.alias = tagAlias(ALIAS_PREFIX.chatEndpoint, row.id);
+    if (row.id)
+        out.id = row.id;
+    if (row.name)
+        out.name = row.name;
+    if (cfg.transport)
+        out.transport = cfg.transport;
+    out.is_tunnel_backed = Boolean(row.isTunnelBacked);
+    if (cfg.outgoing?.url)
+        out.url = cfg.outgoing.url;
+    if (cfg.outgoing?.method)
+        out.method = cfg.outgoing.method;
+    if (cfg.outgoing?.mode)
+        out.mode = cfg.outgoing.mode;
+    if (cfg.incoming?.messagePath)
+        out.message_path = cfg.incoming.messagePath;
+    const slotsCount = Array.isArray(cfg.incoming?.slotsContainerPaths)
+        ? cfg.incoming.slotsContainerPaths.length
+        : 0;
+    out.slots_paths = slotsCount;
+    return out;
+}
+/** Return the round-trippable envelope used by `endpoint get --verbose`. */
+export function envelopeFromRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        isTunnelBacked: Boolean(row.isTunnelBacked),
+        config: row.config ?? {},
+    };
+}
+export function formatChatEndpointList(rows, json, verbose) {
+    if (json) {
+        if (verbose) {
+            output(rows, true);
+            return;
+        }
+        output(rows.map(leanRow), true);
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("No chatbot endpoints.");
+        return;
+    }
+    const lean = rows.map(leanRow);
+    printTable(["#", "NAME", "TRANSPORT", "URL", "METHOD", "MODE", "TUNNEL"], lean.map((r) => [
+        String(r.alias ?? r.id ?? ""),
+        String(r.name ?? ""),
+        String(r.transport ?? "-"),
+        String(r.url ?? "-"),
+        String(r.method ?? "-"),
+        String(r.mode ?? "-"),
+        r.is_tunnel_backed ? "yes" : "no",
+    ]));
+}
+export function formatChatEndpointDetail(row, json, verbose) {
+    if (json) {
+        if (verbose) {
+            output(envelopeFromRow(row), true);
+            return;
+        }
+        output(leanRow(row), true);
+        return;
+    }
+    const cfg = row.config ?? {};
+    const alias = row.id ? tagAlias(ALIAS_PREFIX.chatEndpoint, row.id) : "-";
+    console.log(`${row.name || "Untitled"} (${alias})`);
+    const meta = [];
+    if (cfg.transport)
+        meta.push(String(cfg.transport));
+    if (row.isTunnelBacked)
+        meta.push("tunnel-backed");
+    if (meta.length > 0)
+        console.log(meta.join(" · "));
+    if (cfg.outgoing) {
+        console.log("");
+        console.log(`  URL    ${cfg.outgoing.url ?? "-"}`);
+        console.log(`  Method ${cfg.outgoing.method ?? "-"}`);
+        console.log(`  Mode   ${cfg.outgoing.mode ?? "-"}`);
+    }
+    if (cfg.incoming) {
+        console.log("");
+        console.log(`  Message path  ${cfg.incoming.messagePath ?? "-"}`);
+        const slots = Array.isArray(cfg.incoming.slotsContainerPaths)
+            ? cfg.incoming.slotsContainerPaths.length
+            : 0;
+        console.log(`  Slot paths    ${slots}`);
+    }
+}

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

@@ -123,6 +123,12 @@ export declare function confirmDestructive(prompt: string, opts: {
 export declare function resolveWorkspace(explicit?: string): string;
 export declare function resolveStudy(explicit?: string): string;
 export declare function resolveAsk(explicit?: string): string;
+/**
+ * Resolve a chat endpoint id from (in order): the positional argument, the
+ * `--endpoint <id>` flag, the `ISH_CHAT_ENDPOINT` env var, or the active
+ * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
+ */
+export declare function resolveChatEndpoint(positional?: string, flag?: string): string;
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export declare function collectRepeatable(value: string, prev?: string[]): string[];
 /**
@@ -150,4 +156,16 @@ export declare function parseWaitTimeout(raw: string | undefined, defaultMs?: nu
  * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
  * unused values.
  */
+/**
+ * Read a `--*-config <file>` style flag value, treating "-" as "read from
+ * stdin" and any other value as a file path on disk. Trailing newlines on
+ * stdin input are stripped so the resulting string parses cleanly as JSON.
+ *
+ * Throws when "-" is passed but stdin is a TTY (no upstream pipe).
+ *
+ * Mirrors the readSecretFlag pattern in src/commands/workspace.ts; extracted
+ * so every `--<x>-config <file>` flag across commands shares one
+ * implementation.
+ */
+export declare function readFileOrStdin(path: string): Promise<string>;
 export declare function injectGlobalWorkspaceOption(program: Command): void;

package/dist/lib/command-helpers.js

@@ -348,6 +348,20 @@ export function exitCodeFromError(err) {
         // Client-side validation failures
         if (err.name === "ValidationError" || /^invalid |^cannot read |is empty:|--\w[\w-]* must be|pick an audience|use either /i.test(err.message))
             return 2;
+        // Errors that pre-declare their own retryability / error_code take
+        // precedence — WaitTimeoutError sets `error_code: "wait_timeout"`
+        // and `retryable: true`, so callers can branch on exit 5 (transient)
+        // distinct from the api-client's generic 408/timeout family.
+        const tagged = err;
+        if (tagged.error_code === "wait_timeout")
+            return 5;
+        if (typeof tagged.retryable === "boolean" && tagged.retryable)
+            return 5;
+        // Structured error_kind on the Error object (set by chat endpoint test/init,
+        // simulation routes, etc.). TunnelInactive is the canonical transient one.
+        const kind = err.error_kind;
+        if (typeof kind === "string" && kind === "TunnelInactive")
+            return 5;
     }
     return 1;
 }
@@ -439,6 +453,18 @@ export function readJsonFileOrStdin(filePath) {
         process.stdin.on("error", reject);
     });
 }
+/**
+ * Build the suggested re-invocation example by taking the live argv and
+ * appending `--yes` if it isn't already there. Strips the `node` /
+ * `dist/index.js` prefix so the example reads as a normal `ish` command.
+ */
+function buildConfirmationExample() {
+    const argv = process.argv.slice(2);
+    const args = argv.includes("--yes") || argv.includes("-y")
+        ? argv
+        : [...argv, "--yes"];
+    return ["ish", ...args].join(" ");
+}
 /**
  * Prompt for confirmation of a destructive action, or short-circuit when
  * `--yes` is set. In `--json` mode without `--yes` we refuse with a usage
@@ -451,11 +477,15 @@ export async function confirmDestructive(prompt, opts) {
     if (opts.json) {
         const err = new Error(`--yes is required for destructive actions in --json mode. Refusing to proceed without explicit confirmation.`);
         err.name = "ValidationError";
+        err.error_kind = "ConfirmationRequired";
+        err.example = buildConfirmationExample();
         throw err;
     }
     if (!process.stdin.isTTY) {
         const err = new Error(`--yes is required for destructive actions when stdin is not a TTY. Refusing to proceed without explicit confirmation.`);
         err.name = "ValidationError";
+        err.error_kind = "ConfirmationRequired";
+        err.example = buildConfirmationExample();
         throw err;
     }
     process.stderr.write(`${prompt} [y/N] `);
@@ -486,6 +516,23 @@ export async function confirmDestructive(prompt, opts) {
         throw err;
     }
 }
+/**
+ * Construct a structured "no active <thing>" Error so the JSON envelope from
+ * `outputError` carries `error_code` + `suggestions` rather than a generic
+ * `client_error`. Pattern A (Sprint 2): when the active study/workspace
+ * evaporates between commands, agents need to branch on the error code, not
+ * scrape prose. Without this, downstream modality validation in
+ * `iteration create` would surface a misleading "Image iterations require
+ * --image-urls" message instead of the real "no active study" cause.
+ */
+function noActiveContextError(message, errorCode, suggestions) {
+    const err = new Error(message);
+    err.name = "NoActiveContextError";
+    err.error_code = errorCode;
+    err.retryable = false;
+    err.suggestions = suggestions;
+    return err;
+}
 export function resolveWorkspace(explicit) {
     if (explicit)
         return resolveId(explicit);
@@ -500,7 +547,10 @@ export function resolveWorkspace(explicit) {
     const config = loadConfig();
     if (config.workspace)
         return config.workspace;
-    throw new Error('No workspace set. Use `ish workspace use <alias>` or pass --workspace.');
+    throw noActiveContextError('No active workspace. Run `ish workspace use <workspace-id>` or pass --workspace <id>.', "no_active_workspace", [
+        "ish workspace list",
+        "ish workspace use <workspace-id>",
+    ]);
 }
 export function resolveStudy(explicit) {
     if (explicit)
@@ -511,7 +561,10 @@ export function resolveStudy(explicit) {
     const config = loadConfig();
     if (config.study)
         return config.study;
-    throw new Error('No study set. Use `ish study use <alias>` or pass --study.');
+    throw noActiveContextError('No active study. Run `ish study use <study-id>` or pass --study <id>.', "no_active_study", [
+        "ish study use <study-id>",
+        "ish iteration create --study <study-id> ...",
+    ]);
 }
 export function resolveAsk(explicit) {
     if (explicit)
@@ -522,7 +575,28 @@ export function resolveAsk(explicit) {
     const config = loadConfig();
     if (config.ask)
         return config.ask;
-    throw new Error('No ask set. Use `ish ask use <alias>` or pass the ask ID as an argument.');
+    throw noActiveContextError('No active ask. Run `ish ask use <ask-id>` or pass the ask ID as an argument.', "no_active_ask", [
+        "ish ask list",
+        "ish ask use <ask-id>",
+    ]);
+}
+/**
+ * Resolve a chat endpoint id from (in order): the positional argument, the
+ * `--endpoint <id>` flag, the `ISH_CHAT_ENDPOINT` env var, or the active
+ * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
+ */
+export function resolveChatEndpoint(positional, flag) {
+    if (positional)
+        return resolveId(positional);
+    if (flag)
+        return resolveId(flag);
+    const env = process.env.ISH_CHAT_ENDPOINT;
+    if (env)
+        return resolveId(env);
+    const config = loadConfig();
+    if (config.chat_endpoint)
+        return config.chat_endpoint;
+    throw new Error('No chat endpoint set. Use `ish chat endpoint use <id>`, pass the endpoint id, or set --endpoint.');
 }
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export function collectRepeatable(value, prev = []) {
@@ -571,6 +645,34 @@ const WORKSPACE_SCOPED_GROUPS = new Set([
  * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
  * unused values.
  */
+/**
+ * Read a `--*-config <file>` style flag value, treating "-" as "read from
+ * stdin" and any other value as a file path on disk. Trailing newlines on
+ * stdin input are stripped so the resulting string parses cleanly as JSON.
+ *
+ * Throws when "-" is passed but stdin is a TTY (no upstream pipe).
+ *
+ * Mirrors the readSecretFlag pattern in src/commands/workspace.ts; extracted
+ * so every `--<x>-config <file>` flag across commands shares one
+ * implementation.
+ */
+export async function readFileOrStdin(path) {
+    if (path === "-") {
+        if (process.stdin.isTTY) {
+            throw new Error('Use "-" only when piping the value on stdin.');
+        }
+        return await new Promise((resolve, reject) => {
+            let data = "";
+            process.stdin.setEncoding("utf-8");
+            process.stdin.on("data", (chunk) => {
+                data += chunk;
+            });
+            process.stdin.on("end", () => resolve(data.replace(/\r?\n$/, "")));
+            process.stdin.on("error", reject);
+        });
+    }
+    return fs.readFileSync(path, "utf-8");
+}
 export function injectGlobalWorkspaceOption(program) {
     const walk = (cmd) => {
         if (cmd.commands.length === 0) {