@ishlabs/cli 0.8.5 → 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;
     }
 }
@@ -57,8 +59,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/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;