feat: ask command (#61)

Co-authored-by: Hernan Clich <hernan.g.clich@gmail.com>

Author: fadeev

docs/index.md

@@ -1252,3 +1252,18 @@ Options:
   -h, --help  display help for command
 
 ```
+
+## zetachain ask
+
+```
+Usage: zetachain ask [options] [prompt...]
+
+Chat with ZetaChain Docs AI
+
+Arguments:
+  prompt      Prompt to send to AI
+
+Options:
+  -h, --help  display help for command
+
+```

package.json

@@ -34,15 +34,18 @@
   "dependencies": {
     "@zetachain/localnet": "12.0.3",
     "@zetachain/toolkit": "16.1.2",
+    "axios": "^1.7.7",
     "commander": "^13.1.0",
+    "cors": "^2.8.5",
     "fs-extra": "^11.3.0",
     "inquirer": "^12.3.2",
     "marked": "^15.0.6",
     "marked-terminal": "^7.2.1",
-    "node-fetch": "^3.3.2",
+    "ora": "^5.4.1",
     "posthog-node": "^5.8.1",
     "simple-git": "^3.27.0",
-    "uuid": "^11.1.0"
+    "uuid": "^11.1.0",
+    "zod": "^4.1.8"
   },
   "devDependencies": {
     "@types/clear": "^0.1.4",

src/commands/ask.ts

@@ -0,0 +1,68 @@
+import { Command } from "commander";
+import inquirer from "inquirer";
+
+import { DEFAULT_CHAT_API_URL, DEFAULT_CHATBOT_ID } from "../constants";
+import { streamChatResponse } from "./ask/streaming";
+import { createChatSpinner } from "./ask/ui";
+import { validateAndSanitizePrompt } from "./ask/validation";
+
+const main = async (promptParts: string[]): Promise<void> => {
+  let nextPrompt = promptParts.join(" ").trim();
+  while (true) {
+    let prompt = nextPrompt;
+    if (!prompt) {
+      try {
+        const { input } = await inquirer.prompt([
+          { message: "Ask ZetaChain", name: "input", type: "input" },
+        ]);
+        prompt = String(input ?? "").trim();
+      } catch (err) {
+        // Handle inquirer exit scenarios
+        if (err instanceof Error) {
+          if (
+            err.name === "ExitPromptError" ||
+            err.message.includes("User force closed the prompt")
+          ) {
+            return;
+          }
+        }
+        throw err;
+      }
+    }
+    const lower = (prompt || "").toLowerCase();
+    if (!prompt || lower === "exit" || lower === "quit" || lower === ":q") {
+      return;
+    }
+
+    try {
+      // Validate and sanitize input
+      const sanitizedPrompt = validateAndSanitizePrompt(prompt);
+
+      const payload = {
+        chatbotId: DEFAULT_CHATBOT_ID,
+        messages: [{ content: sanitizedPrompt, role: "user" }],
+        stream: true,
+      };
+
+      const spinner = createChatSpinner();
+      const onFirstOutput = () => {
+        spinner.stop();
+      };
+
+      await streamChatResponse(DEFAULT_CHAT_API_URL, payload, onFirstOutput);
+    } catch (securityError) {
+      const message =
+        securityError instanceof Error
+          ? securityError.message
+          : String(securityError);
+      console.error(`Error: ${message}`);
+      process.exitCode = 1;
+    }
+    nextPrompt = "";
+  }
+};
+
+export const askCommand = new Command("ask")
+  .description("Chat with ZetaChain Docs AI")
+  .argument("[prompt...]", "Prompt to send to AI")
+  .action(main);

src/commands/ask/http.ts

@@ -0,0 +1,78 @@
+import { AxiosHeaders, AxiosResponse, RawAxiosResponseHeaders } from "axios";
+
+import { ASK_BASE_DELAY_MS, ASK_MAX_RETRIES } from "../../constants";
+import { fetchWithRetry } from "../../utils/http";
+import { readStreamBody } from "../../utils/stream";
+import { ErrorResponseSchema } from "./schemas";
+
+// Ask command specific HTTP functionality
+
+export const fetchChatStream = async (
+  url: string,
+  body: unknown,
+  signal: AbortSignal,
+): Promise<AxiosResponse> => {
+  return fetchWithRetry(
+    url,
+    {
+      data: body,
+      headers: {
+        Accept: "text/event-stream",
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+      responseType: "stream",
+      signal,
+      timeout: 360_000,
+    },
+    {
+      baseDelay: ASK_BASE_DELAY_MS,
+      maxRetries: ASK_MAX_RETRIES,
+    },
+  );
+};
+
+export const parseErrorResponse = (
+  res: AxiosResponse,
+  text: string,
+): string | undefined => {
+  let contentType: string | undefined;
+  if (res?.headers instanceof AxiosHeaders) {
+    const v = res.headers.get?.("content-type");
+    contentType = typeof v === "string" ? v : undefined;
+  } else if (res?.headers) {
+    const raw = res.headers as RawAxiosResponseHeaders;
+    const v = raw["content-type"] ?? raw["Content-Type"];
+    contentType = typeof v === "string" ? v : undefined;
+  }
+
+  const isJson = contentType?.includes("application/json");
+  let parsed: unknown = text;
+  if (isJson) {
+    try {
+      parsed = JSON.parse(text);
+    } catch (_) {
+      parsed = null;
+    }
+  }
+
+  const errorResult = ErrorResponseSchema.safeParse(parsed);
+  if (errorResult.success) {
+    return errorResult.data.error || errorResult.data.message;
+  }
+  return undefined;
+};
+
+export const validateChatResponse = async (
+  res: AxiosResponse,
+): Promise<void> => {
+  if (res.status >= 200 && res.status < 300) {
+    return; // Success
+  }
+
+  const text = await readStreamBody(res);
+  const message = parseErrorResponse(res, text);
+  throw new Error(
+    `Chat API error ${res.status}: ${message || res.statusText || "Error"}`,
+  );
+};

src/commands/ask/schemas.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+// Ask command specific schemas for chat/AI APIs
+
+export const StreamChoiceSchema = z.object({
+  delta: z
+    .object({
+      content: z.string().optional(),
+    })
+    .optional(),
+});
+
+export const StreamResponseSchema = z.object({
+  choices: z.array(StreamChoiceSchema).optional(),
+});
+
+export const TextResponseSchema = z.object({
+  text: z.string(),
+});
+
+export const ErrorResponseSchema = z.object({
+  error: z.string().optional(),
+  message: z.string().optional(),
+});

src/commands/ask/sse.ts

@@ -0,0 +1,170 @@
+import { StreamLike } from "../../utils/stream";
+import { StreamResponseSchema, TextResponseSchema } from "./schemas";
+
+// Ask command specific SSE processing (could be reusable for other SSE APIs)
+
+export interface SSEProcessor {
+  onData: (chunk: unknown) => void;
+  onEnd: () => void;
+  onError: (err: unknown) => void;
+}
+
+export const createSSEProcessor = (onFirstOutput: () => void): SSEProcessor => {
+  let buffer = "";
+  let prebuffer = "";
+  let sawSseData = false;
+  let eventBuf: string[] = [];
+  let sawDone = false;
+  let notifiedFirstOutput = false;
+
+  const notifyFirstOutput = () => {
+    if (notifiedFirstOutput) return;
+    notifiedFirstOutput = true;
+    try {
+      onFirstOutput();
+    } catch (_) {
+      // ignore callback errors
+    }
+  };
+
+  const flushEvent = () => {
+    if (!eventBuf.length) return;
+    const payload = eventBuf.join("\n");
+    eventBuf = [];
+
+    if (payload === "[DONE]") {
+      sawDone = true;
+      return;
+    }
+
+    let json: unknown = null;
+    try {
+      json = JSON.parse(payload);
+    } catch (_) {
+      json = null;
+    }
+
+    let textOut: string | null = null;
+
+    // Try parsing as text response first
+    const textResult = TextResponseSchema.safeParse(json);
+    if (textResult.success) {
+      textOut = textResult.data.text;
+    } else {
+      // Try parsing as stream response
+      const streamResult = StreamResponseSchema.safeParse(json);
+      if (
+        streamResult.success &&
+        streamResult.data.choices?.[0]?.delta?.content
+      ) {
+        textOut = streamResult.data.choices[0].delta.content;
+      } else if (typeof json === "string") {
+        textOut = json;
+      }
+    }
+
+    notifyFirstOutput();
+    if (typeof textOut === "string") {
+      process.stdout.write(textOut);
+    } else if (payload && payload.trim() !== "[object Object]") {
+      process.stdout.write(payload);
+    }
+  };
+
+  const onData = (chunk: unknown) => {
+    if (sawDone) return;
+
+    const chunkStr = Buffer.isBuffer(chunk) ? chunk.toString() : String(chunk);
+
+    // Stream raw text immediately until we detect SSE lines (data: ...)
+    if (!sawSseData) {
+      const combined = prebuffer + chunkStr;
+      if (/(\r?\n|^)data:/.test(combined)) {
+        // Detected SSE, switch to SSE parsing mode
+        sawSseData = true;
+        buffer += combined;
+        prebuffer = "";
+      } else {
+        prebuffer = "";
+        notifyFirstOutput();
+        process.stdout.write(chunkStr);
+        return;
+      }
+    } else {
+      buffer += chunkStr;
+    }
+
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      const trimmed = line.trimStart();
+      if (trimmed === "") {
+        flushEvent();
+        continue;
+      }
+      if (trimmed.startsWith(":")) continue; // comment
+      if (trimmed.startsWith("event:")) continue; // ignore event name
+      if (trimmed.startsWith("data:")) {
+        const p = trimmed.slice(5).trimStart();
+        eventBuf.push(p);
+        continue;
+      }
+    }
+  };
+
+  const onEnd = () => {
+    if (!sawSseData && prebuffer) {
+      notifyFirstOutput();
+      process.stdout.write(prebuffer);
+      prebuffer = "";
+    }
+
+    if (buffer) {
+      const trimmed = buffer.trimStart();
+      if (!sawSseData || !/(\r?\n|^)data:/.test(trimmed)) {
+        notifyFirstOutput();
+        process.stdout.write(buffer);
+      } else {
+        // finalize any pending event
+        if (trimmed) {
+          const maybe = trimmed.startsWith("data:")
+            ? trimmed.slice(5).trimStart()
+            : trimmed;
+          if (maybe) {
+            eventBuf.push(maybe);
+          }
+        }
+        flushEvent();
+      }
+    }
+
+    process.stdout.write("\n");
+  };
+
+  const onError = (err: unknown) => {
+    throw err;
+  };
+
+  return { onData, onEnd, onError };
+};
+
+export const processStream = async (
+  stream: StreamLike,
+  processor: SSEProcessor,
+): Promise<void> => {
+  return new Promise<void>((resolve, reject) => {
+    stream.on("data", processor.onData);
+    stream.on("end", () => {
+      processor.onEnd();
+      resolve();
+    });
+    stream.on("error", (err: unknown) => {
+      try {
+        processor.onError(err);
+      } catch (processedError) {
+        reject(processedError);
+      }
+    });
+  });
+};