@ishlabs/cli 0.12.2 → 0.14.0

package/dist/commands/chat-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ish chat config — Manage chatbot configurations (agent shape).
+ *
+ * A configuration captures *what the chatbot is* (model, system prompt,
+ * tools, sub-agents, custom {key, value} fields) — distinct from the
+ * *wire envelope* on a chatbot endpoint. Configurations live N-per-
+ * endpoint; chat iterations reference one and freeze a snapshot at
+ * creation time so historical comparisons stay reproducible.
+ *
+ * Four-verb surface mirroring `ish secret`: `list / set / get /
+ * delete`. `set` is the create-or-update upsert (composite write —
+ * mirrors MCP `chatbot_config_set` and the `chatbot_setup` precedent).
+ * `get --view iterations` surfaces the cross-study aggregation.
+ */
+import type { Command } from "commander";
+interface CustomField {
+    key: string;
+    value: string;
+}
+export declare function parseCustomField(raw: string): CustomField;
+export declare function parseCustomFieldsFlag(values: string[] | undefined): CustomField[] | undefined;
+export declare function attachChatConfigCommands(parent: Command): void;
+export {};

package/dist/commands/chat-config.js

@@ -0,0 +1,289 @@
+/**
+ * ish chat config — Manage chatbot configurations (agent shape).
+ *
+ * A configuration captures *what the chatbot is* (model, system prompt,
+ * tools, sub-agents, custom {key, value} fields) — distinct from the
+ * *wire envelope* on a chatbot endpoint. Configurations live N-per-
+ * endpoint; chat iterations reference one and freeze a snapshot at
+ * creation time so historical comparisons stay reproducible.
+ *
+ * Four-verb surface mirroring `ish secret`: `list / set / get /
+ * delete`. `set` is the create-or-update upsert (composite write —
+ * mirrors MCP `chatbot_config_set` and the `chatbot_setup` precedent).
+ * `get --view iterations` surfaces the cross-study aggregation.
+ */
+import * as fs from "node:fs";
+import { ApiError } from "../lib/api-client.js";
+import { ALIAS_PREFIX, tagAlias } from "../lib/alias-store.js";
+import { collectRepeatable, confirmDestructive, resolveChatConfig, resolveChatEndpoint, withClient, } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function parseCustomField(raw) {
+    const idx = raw.indexOf("=");
+    if (idx <= 0) {
+        throw new Error(`--custom-field must be \`key=value\` (got "${raw}").`);
+    }
+    return { key: raw.slice(0, idx).trim(), value: raw.slice(idx + 1) };
+}
+export function parseCustomFieldsFlag(values) {
+    if (values === undefined)
+        return undefined;
+    const seen = new Set();
+    const out = [];
+    for (const raw of values) {
+        const f = parseCustomField(raw);
+        if (!f.key)
+            throw new Error("--custom-field key cannot be empty.");
+        if (seen.has(f.key)) {
+            throw new Error(`--custom-field key "${f.key}" is repeated; keys must be unique.`);
+        }
+        seen.add(f.key);
+        out.push(f);
+    }
+    return out;
+}
+function parseJsonListFlag(file, label) {
+    if (file === undefined)
+        return undefined;
+    const content = file === "-" ? fs.readFileSync(0, "utf-8") : fs.readFileSync(file, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        const m = err instanceof Error ? err.message : String(err);
+        throw new Error(`${label} is not valid JSON: ${m}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error(`${label} must be a JSON array.`);
+    return parsed;
+}
+function readSystemPrompt(systemPrompt, systemPromptFile) {
+    if (systemPrompt !== undefined && systemPromptFile !== undefined) {
+        throw new Error("Pass at most one of --system-prompt or --system-prompt-file.");
+    }
+    if (systemPrompt !== undefined)
+        return systemPrompt;
+    if (systemPromptFile !== undefined) {
+        return systemPromptFile === "-"
+            ? fs.readFileSync(0, "utf-8")
+            : fs.readFileSync(systemPromptFile, "utf-8");
+    }
+    return undefined;
+}
+function pruneUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+function attachList(parent) {
+    parent
+        .command("list")
+        .description("List configurations under a chatbot endpoint")
+        .option("--endpoint <id>", "Endpoint alias or UUID (defaults to active endpoint)")
+        .addHelpText("after", "\nExamples:\n  $ ish chat config list\n  $ ish chat config list --json | jq '.[] | {alias, name, isDefault, usageCount}'")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const epId = resolveChatEndpoint(undefined, opts.endpoint);
+            const rows = await client.get(`/chatbot-endpoints/${epId}/configurations`);
+            for (const row of rows) {
+                if (row.id)
+                    tagAlias(ALIAS_PREFIX.chatConfig, row.id);
+            }
+            if (globals.json) {
+                output(rows, true);
+                return;
+            }
+            if (rows.length === 0) {
+                console.log("No configurations yet. Run `ish chat config set --name <name>` to author one.");
+                return;
+            }
+            for (const row of rows) {
+                const alias = row.id ? tagAlias(ALIAS_PREFIX.chatConfig, row.id) : "?";
+                const def = row.isDefault ? " [default]" : "";
+                const ver = row.versionLabel ? ` (${row.versionLabel})` : "";
+                const model = row.model ? `  model=${row.model}` : "";
+                const usage = `  used=${row.usageCount ?? 0}`;
+                console.log(`${alias}  ${row.name}${ver}${def}${model}${usage}`);
+            }
+        });
+    });
+}
+function attachSet(parent) {
+    parent
+        .command("set")
+        .description("Create or update a chatbot configuration (composite upsert)")
+        .requiredOption("--name <name>", "Configuration name (unique per endpoint)")
+        .option("--endpoint <id>", "Endpoint alias or UUID (defaults to active endpoint; create only)")
+        .option("--config <id>", "Configuration alias or UUID — switches to update mode")
+        .option("--version-label <label>", "Optional version tag (e.g. v3, 1.2.0, git sha)")
+        .option("--description <text>", "Optional description")
+        .option("--model <id>", "Primary model identifier (e.g. claude-sonnet-4-6)")
+        .option("--system-prompt <text>", "System prompt text")
+        .option("--system-prompt-file <file>", 'Read system prompt from file (or "-" for stdin)')
+        .option("--tools-file <file>", 'JSON array of tools (or "-" for stdin)')
+        .option("--sub-agents-file <file>", 'JSON array of sub-agents (or "-" for stdin)')
+        .option("--custom-field <key=value>", "Custom field; repeat. Replaces all custom fields on update.", collectRepeatable)
+        .option("--default", "Mark as the endpoint's default configuration")
+        .addHelpText("after", `
+Without --config, POSTs a new configuration under the endpoint. With
+--config, PUTs an update. With --default, fires the set-default call
+after the write so a single command leaves the endpoint with the
+right default. Editing does NOT retroactively change historical
+iterations — each iteration froze a snapshot at creation.
+
+Examples:
+  $ ish chat config set --name v1-sonnet --model claude-sonnet-4-6 \\
+      --system-prompt-file ./prompt.txt --custom-field git_sha=abc --default
+  $ ish chat config set --config cc-abc --name v1.1-sonnet
+  $ cat tools.json | ish chat config set --name with-search --tools-file -`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const cid = opts.config ? resolveChatConfig(undefined, opts.config) : null;
+            const body = pruneUndefined({
+                name: opts.name,
+                versionLabel: opts.versionLabel,
+                description: opts.description,
+                model: opts.model,
+                systemPrompt: readSystemPrompt(opts.systemPrompt, opts.systemPromptFile),
+                tools: parseJsonListFlag(opts.toolsFile, "--tools-file"),
+                subAgents: parseJsonListFlag(opts.subAgentsFile, "--sub-agents-file"),
+                customFields: parseCustomFieldsFlag(opts.customField),
+            });
+            let saved;
+            if (cid === null) {
+                const epId = resolveChatEndpoint(undefined, opts.endpoint);
+                if (opts.default)
+                    body.isDefault = true;
+                saved = await client.post(`/chatbot-endpoints/${epId}/configurations`, body);
+            }
+            else {
+                saved = await client.put(`/chatbot-configurations/${cid}`, body);
+                if (opts.default) {
+                    saved = await client.post(`/chatbot-configurations/${cid}/set-default`);
+                }
+            }
+            if (saved.id)
+                tagAlias(ALIAS_PREFIX.chatConfig, saved.id);
+            if (!globals.quiet) {
+                const action = cid === null ? "Created" : "Updated";
+                const tag = saved.isDefault ? " (default)" : "";
+                const alias = saved.id ? tagAlias(ALIAS_PREFIX.chatConfig, saved.id) : "?";
+                console.error(`${action} configuration ${alias}${tag}`);
+            }
+            output(saved, globals.json);
+        });
+    });
+}
+function attachGet(parent) {
+    parent
+        .command("get")
+        .description("Get a chatbot configuration (or its referencing iterations)")
+        .argument("[id]", "Configuration alias or UUID")
+        .option("--config <id>", "Configuration alias or UUID (alternative to positional)")
+        .option("--view <view>", "default | iterations. `iterations` returns the cross-study aggregation list.", "default")
+        .addHelpText("after", `
+\`--view iterations\` returns every iteration referencing this
+configuration across studies, joined to study metadata. Mirrors
+\`study_get(view=...)\`.
+
+Examples:
+  $ ish chat config get cc-abc
+  $ ish chat config get cc-abc --view iterations --json | jq 'group_by(.studyName) | length'`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const cid = resolveChatConfig(id, opts.config);
+            if (opts.view === "iterations") {
+                const rows = await client.get(`/chatbot-configurations/${cid}/iterations`);
+                if (globals.json) {
+                    output(rows, true);
+                    return;
+                }
+                if (rows.length === 0) {
+                    console.log("No iterations reference this configuration yet.");
+                    return;
+                }
+                for (const r of rows) {
+                    console.log(`${r.iterationLabel}  ${r.studyName} — ${r.iterationName}  (${r.createdAt})`);
+                }
+                return;
+            }
+            if (opts.view !== "default") {
+                throw new Error(`--view must be 'default' or 'iterations' (got "${opts.view}").`);
+            }
+            const row = await client.get(`/chatbot-configurations/${cid}`);
+            if (row.id)
+                tagAlias(ALIAS_PREFIX.chatConfig, row.id);
+            output(row, globals.json);
+        });
+    });
+}
+function attachDelete(parent) {
+    parent
+        .command("delete")
+        .description("Delete a chatbot configuration (rejected when iterations reference it)")
+        .argument("[id]", "Configuration alias or UUID")
+        .option("--config <id>", "Configuration alias or UUID (alternative to positional)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .addHelpText("after", `
+Returns HTTP 409 (configuration_in_use) when iterations reference the
+configuration. Snapshots remain readable on those iterations but the
+live cross-study aggregation link breaks. Inspect \`usageCount\`
+via \`ish chat config get <id>\` first.
+
+Examples:
+  $ ish chat config delete cc-abc --yes`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const cid = resolveChatConfig(id, opts.config);
+            await confirmDestructive(`Delete chat configuration ${tagAlias(ALIAS_PREFIX.chatConfig, cid)}? This cannot be undone.`, { yes: opts.yes, json: globals.json });
+            try {
+                await client.del(`/chatbot-configurations/${cid}`);
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 409) {
+                    const detail = err.body;
+                    const ids = detail?.detail?.iteration_ids ?? [];
+                    const e = new Error(`Cannot delete: configuration is referenced by ${ids.length} iteration(s).`);
+                    e.error_kind =
+                        "configuration_in_use";
+                    e.iteration_ids = ids;
+                    throw e;
+                }
+                throw err;
+            }
+            output({
+                success: true,
+                deleted: true,
+                id: cid,
+                alias: tagAlias(ALIAS_PREFIX.chatConfig, cid),
+            }, globals.json, { writePath: true });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function attachChatConfigCommands(parent) {
+    const config = parent
+        .command("config")
+        .description("Manage chatbot configurations (agent shape: model, prompt, tools, sub-agents)")
+        .addHelpText("after", `
+Configurations live under a chatbot endpoint and are referenced by chat
+iterations. Each iteration freezes a snapshot at creation so editing a
+configuration does NOT retroactively change historical iterations. Use
+\`set --config <id>\` to update in place, or omit \`--config\` to create
+a new configuration. Aliases use the \`cc-\` prefix.`);
+    attachList(config);
+    attachSet(config);
+    attachGet(config);
+    attachDelete(config);
+}

package/dist/commands/chat.js

@@ -18,6 +18,7 @@ import { ApiError } from "../lib/api-client.js";
 import { output } from "../lib/output.js";
 import { formatChatEndpointList, formatChatEndpointDetail, envelopeFromRow, } from "../lib/chat-endpoint-formatters.js";
 import { getChatEndpointTemplate, TEMPLATE_NAMES, } from "../lib/chat-endpoint-templates.js";
+import { attachChatConfigCommands } from "./chat-config.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -57,25 +58,6 @@ function urlLooksLocal(url) {
         return false;
     }
 }
-function inferredToConfig(inferred) {
-    const cfg = {
-        transport: inferred.transport,
-        outgoing: {
-            url: inferred.outgoing.url ?? undefined,
-            method: inferred.outgoing.method,
-            headers: inferred.outgoing.headers ?? {},
-            bodyTemplate: inferred.outgoing.bodyTemplate ?? {},
-            mode: inferred.outgoing.mode,
-            roleAliases: inferred.outgoing.roleAliases ?? {},
-        },
-        incoming: inferred.incoming,
-        asyncPoll: inferred.asyncPoll ?? null,
-    };
-    if (inferred.streaming) {
-        cfg.streaming = inferred.streaming;
-    }
-    return cfg;
-}
 async function tunnelGuard(client) {
     try {
         await client.get("/connect/active");
@@ -355,12 +337,12 @@ endpoint, apply the override, and PUT the merged result. Field flags win over
     });
 }
 // ---------------------------------------------------------------------------
-// init — auto-detect-shape onboarding
+// init — test-and-map onboarding (auto-detect via /chat/test-and-map)
 // ---------------------------------------------------------------------------
 function attachChatEndpointInit(parent) {
     parent
         .command("init")
-        .description("Author an endpoint from a curl/JSON sample via auto-detect-shape, or from a known-good template")
+        .description("Author an endpoint from a curl/JSON sample via test-and-map, or from a known-good template")
         .option("--from-curl <file>", 'Path to a curl example file (or "-" for stdin)')
         .option("--from-json <file>", 'Path to a JSON request/response sample (or "-" for stdin)')
         .option("--template <name>", `Start from a known-good template (one of: ${TEMPLATE_NAMES.join(", ")})`)
@@ -446,22 +428,27 @@ Examples:
                 output(result, globals.json, { writePath: true });
                 return;
             }
-            // Auto-detect path (curl or JSON paste).
+            // Auto-detect path (curl or JSON paste). Drives the same
+            // /test-and-map endpoint the editor uses, so the CLI and editor
+            // stay aligned on inference behaviour and error vocabulary.
             const path = (opts.fromCurl ?? opts.fromJson);
             const paste = await readFileOrStdin(path);
-            const inferRes = await client.post(`/products/${ws}/chat/auto-detect-shape`, { paste }, { timeout: 120_000 });
-            if (!inferRes.ok) {
+            const mapRes = await client.post(`/products/${ws}/chat/test-and-map`, { documentation: paste }, { timeout: 120_000 });
+            if (mapRes.kind === "failure") {
                 // Surface as a structured failure envelope on stdout AND throw so
                 // the wrapper sets a non-zero exit. The thrown Error carries the
-                // shape's error_kind for the agent to branch on.
-                const err = new Error(inferRes.errorMessage ?? "auto-detect-shape failed.");
-                err.error_kind = inferRes.errorKind;
+                // backend's error_kind for the agent to branch on.
+                const err = new Error(mapRes.errorMessage ?? "test-and-map failed.");
+                err.error_kind = mapRes.errorKind;
                 throw err;
             }
-            const inferred = inferRes.inferred;
-            const config = inferredToConfig(inferred);
-            const inferredUrl = inferred.outgoing.url ?? null;
-            const detectedTunnel = urlLooksLocal(inferredUrl);
+            const config = mapRes.inferredConfig;
+            const inferredUrl = (typeof config.outgoing?.url === "string" && config.outgoing.url
+                ? config.outgoing.url
+                : null);
+            // Trust the backend's tunnel detection when present; fall back to
+            // the local heuristic only if the envelope didn't populate it.
+            const detectedTunnel = mapRes.tunnelBackedDetected ?? urlLooksLocal(inferredUrl);
             let tunnelBacked;
             if (opts.tunnelBacked === true)
                 tunnelBacked = true;
@@ -474,8 +461,9 @@ Examples:
             if (!inferredUrl) {
                 warnings.push("Inferred shape has no URL; set --url before testing.");
             }
-            if (inferred.confidence !== "high") {
-                warnings.push(`Auto-detect confidence: ${inferred.confidence} — verify the shape before running.`);
+            const confidence = mapRes.confidence ?? null;
+            if (confidence && confidence !== "high") {
+                warnings.push(`Auto-detect confidence: ${confidence} — verify the shape before running.`);
             }
             // Decide whether to save. --no-save short-circuits; otherwise save when
             // a name is available (--name wins; else fall back to the inferred
@@ -508,8 +496,8 @@ Examples:
                     }
                 }
             }
-            const missingSignals = Array.isArray(inferred.missingSignals)
-                ? inferred.missingSignals
+            const missingSignals = Array.isArray(mapRes.missingSignals)
+                ? mapRes.missingSignals
                 : [];
             const result = {
                 success: true,
@@ -519,8 +507,8 @@ Examples:
                 config,
                 tunnel_backed: tunnelBacked,
                 tunnel_backed_detected: detectedTunnel,
-                confidence: inferred.confidence,
-                explanation: inferred.explanation,
+                confidence,
+                explanation: mapRes.explanation ?? "",
                 missingSignals,
                 warnings,
             };
@@ -714,6 +702,7 @@ mirrors that editing model.`);
     attachChatEndpointInit(endpoint);
     attachChatEndpointTest(endpoint);
     attachChatEndpointMap(endpoint);
+    attachChatConfigCommands(chat);
 }
 // Re-exported for tests / external integration if needed.
 export { envelopeFromRow };