@qverisai/cli 0.1.0

package/src/output/codegen.mjs

@@ -0,0 +1,75 @@
+import { resolve } from "../config/resolve.mjs";
+
+export function generateSnippet(lang, { toolId, discoveryId, parameters, maxResponseSize = 20480 }) {
+  const baseUrl = resolve("base_url").value;
+
+  switch (lang) {
+    case "curl":
+      return generateCurl({ baseUrl, toolId, discoveryId, parameters, maxResponseSize });
+    case "js":
+    case "javascript":
+      return generateJs({ baseUrl, toolId, discoveryId, parameters, maxResponseSize });
+    case "python":
+    case "py":
+      return generatePython({ baseUrl, toolId, discoveryId, parameters, maxResponseSize });
+    default:
+      return `Unsupported language: ${lang}. Use: curl, js, python`;
+  }
+}
+
+function generateCurl({ baseUrl, toolId, discoveryId, parameters, maxResponseSize }) {
+  const body = JSON.stringify({
+    search_id: discoveryId,
+    parameters,
+    max_response_size: maxResponseSize,
+  }, null, 2);
+
+  // Use heredoc to avoid single-quote escaping issues in parameters
+  return `curl -sS -X POST "${baseUrl}/tools/execute?tool_id=${toolId}" \\
+  -H "Authorization: Bearer $QVERIS_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d @- <<'EOF'
+${body}
+EOF`;
+}
+
+function generateJs({ baseUrl, toolId, discoveryId, parameters, maxResponseSize }) {
+  const paramsStr = JSON.stringify(parameters, null, 4);
+  return `const resp = await fetch(
+  "${baseUrl}/tools/execute?tool_id=${toolId}",
+  {
+    method: "POST",
+    headers: {
+      Authorization: \`Bearer \${process.env.QVERIS_API_KEY}\`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      search_id: "${discoveryId}",
+      parameters: ${paramsStr},
+      max_response_size: ${maxResponseSize},
+    }),
+  }
+);
+const data = await resp.json();
+console.log(data);`;
+}
+
+function generatePython({ baseUrl, toolId, discoveryId, parameters, maxResponseSize }) {
+  const paramsStr = JSON.stringify(parameters, null, 8);
+  return `import os
+import requests
+
+resp = requests.post(
+    "${baseUrl}/tools/execute",
+    params={"tool_id": "${toolId}"},
+    headers={"Authorization": f"Bearer {os.environ['QVERIS_API_KEY']}"},
+    json={
+        "search_id": "${discoveryId}",
+        "parameters": ${paramsStr},
+        "max_response_size": ${maxResponseSize},
+    },
+    timeout=60,
+)
+data = resp.json()
+print(data)`;
+}

package/src/output/colors.mjs

@@ -0,0 +1,16 @@
+const enabled =
+  !process.env.NO_COLOR &&
+  (process.env.FORCE_COLOR === "1" || (process.stdout.isTTY && process.stderr.isTTY));
+
+const code = (open, close) =>
+  enabled ? (s) => `\x1b[${open}m${s}\x1b[${close}m` : (s) => s;
+
+export const bold = code("1", "22");
+export const dim = code("2", "22");
+export const red = code("31", "39");
+export const green = code("32", "39");
+export const yellow = code("33", "39");
+export const cyan = code("36", "39");
+export const gray = code("90", "39");
+
+export const isColorEnabled = () => enabled;

package/src/output/formatter.mjs

@@ -0,0 +1,280 @@
+import { bold, cyan, dim, green, yellow, red } from "./colors.mjs";
+
+// ── discover ──────────────────────────────────────────────────────────
+
+export function formatDiscoverResult(result) {
+  const tools = result.results ?? [];
+  const total = result.total ?? tools.length;
+  const searchTime = result.elapsed_time_ms;
+  const remaining = result.remaining_credits;
+  const lines = [];
+
+  if (tools.length === 0) {
+    lines.push("No tools matched your query. Try a broader description.");
+    return lines.join("\n");
+  }
+
+  lines.push(`Found ${bold(String(total))} capabilities matching your query`);
+  lines.push("");
+
+  for (let i = 0; i < tools.length; i++) {
+    const t = tools[i];
+    const name = t.name ?? "N/A";
+    const toolId = t.tool_id ?? "";
+    const desc = stringifyDesc(t.description);
+    const provider = t.provider_name ?? "";
+    const categories = Array.isArray(t.categories) ? t.categories.join(", ") : "";
+    const region = t.region ?? "global";
+    const stats = t.stats ?? {};
+
+    // Relevance score
+    const score = t.final_score;
+    const scoreStr = typeof score === "number" ? `${(score * 100).toFixed(0)}%` : "";
+
+    // Quality metrics
+    let successRate = stats.success_rate;
+    successRate = typeof successRate === "number" ? `${(successRate * 100).toFixed(1)}%` : "N/A";
+    let avgTime = stats.avg_execution_time_ms;
+    avgTime = typeof avgTime === "number" ? `~${Math.round(avgTime)}ms` : "N/A";
+    const cost = stats.cost ?? "?";
+
+    // Verified indicator
+    const verified = t.has_last_execution ? green(" \u2713") : "";
+
+    // Line 1: index + name + provider
+    const providerPart = provider ? `  ${dim("by")} ${provider}` : "";
+    lines.push(`${bold(String(i + 1) + ".")} ${cyan(name)}${providerPart}${verified}`);
+
+    // Line 2: tool_id
+    lines.push(`   ${dim(toolId)}`);
+
+    // Line 3: description (truncated)
+    if (desc) {
+      lines.push(`   ${desc.length > 100 ? desc.slice(0, 100) + "..." : desc}`);
+    }
+
+    // Line 4: metrics row
+    const metricParts = [];
+    if (scoreStr) metricParts.push(`relevance: ${bold(scoreStr)}`);
+    metricParts.push(`success: ${green(successRate)}`);
+    metricParts.push(`latency: ${avgTime}`);
+    metricParts.push(`cost: ${yellow(String(cost))} cr`);
+    if (region !== "global") metricParts.push(`region: ${region}`);
+    lines.push(`   ${dim(metricParts.join("  \u00b7  "))}`);
+
+    // Line 5: categories (if present)
+    if (categories) {
+      lines.push(`   ${dim("tags:")} ${dim(categories)}`);
+    }
+
+    lines.push("");
+  }
+
+  // Footer
+  const footerParts = [`Discovery ID: ${result.search_id ?? "N/A"}`];
+  if (typeof searchTime === "number") footerParts.push(`${Math.round(searchTime)}ms`);
+  if (typeof remaining === "number") footerParts.push(`${remaining} credits remaining`);
+  lines.push(dim(footerParts.join("  \u00b7  ")));
+
+  return lines.join("\n");
+}
+
+// ── inspect ───────────────────────────────────────────────────────────
+
+export function formatInspectResult(tools) {
+  const list = Array.isArray(tools) ? tools : tools?.results ?? tools?.tools ?? [tools];
+  const remaining = tools?.remaining_credits;
+  const lines = [];
+
+  for (const t of list) {
+    const name = t.name ?? t.tool_id ?? "N/A";
+    const toolId = t.tool_id ?? "";
+    const desc = stringifyDesc(t.description);
+    const provider = t.provider_name ?? "";
+    const providerDesc = stringifyDesc(t.provider_description);
+    const categories = Array.isArray(t.categories) ? t.categories.join(", ") : "";
+    const region = t.region ?? "global";
+    const docsUrl = t.docs_url ?? "";
+    const stats = t.stats ?? {};
+
+    let successRate = stats.success_rate;
+    successRate = typeof successRate === "number" ? `${(successRate * 100).toFixed(1)}%` : "N/A";
+    let avgTime = stats.avg_execution_time_ms;
+    avgTime = typeof avgTime === "number" ? `~${Math.round(avgTime)}ms` : "N/A";
+    const cost = stats.cost ?? "?";
+
+    // Header
+    lines.push(bold(cyan(name)));
+    if (toolId && toolId !== name) lines.push(dim(toolId));
+    if (desc) lines.push(desc);
+    lines.push("");
+
+    // Metadata table
+    if (provider) {
+      const pLine = providerDesc ? `${provider}  ${dim("— " + providerDesc)}` : provider;
+      lines.push(`  Provider:   ${pLine}`);
+    }
+    if (categories) lines.push(`  Categories: ${categories}`);
+    lines.push(`  Region:     ${region}`);
+    lines.push(`  Latency:    ${bold(avgTime)}`);
+    lines.push(`  Success:    ${green(successRate)}`);
+    lines.push(`  Cost:       ${yellow(String(cost))} credits`);
+    if (t.has_last_execution) lines.push(`  Verified:   ${green("\u2713 has execution history")}`);
+    if (docsUrl) lines.push(`  Docs:       ${cyan(docsUrl)}`);
+
+    // Parameters
+    const params = t.params ?? [];
+    if (params.length > 0) {
+      lines.push("");
+      lines.push(bold("  Parameters:"));
+      for (const p of params) {
+        const req = p.required ? bold("required") : dim("optional");
+        const pType = dim(p.type ?? "string");
+        const pDesc = p.description ? stringifyDesc(p.description) : "";
+        lines.push(`    ${cyan(p.name)}  ${pType}  ${req}`);
+        if (pDesc) lines.push(`      ${dim(pDesc)}`);
+        if (Array.isArray(p.enum) && p.enum.length > 0) {
+          lines.push(`      ${dim("values:")} ${p.enum.map((v) => yellow(JSON.stringify(v))).join(", ")}`);
+        }
+      }
+    }
+
+    // Example
+    const examples = t.examples ?? {};
+    if (examples.sample_parameters) {
+      lines.push("");
+      lines.push(bold("  Example:"));
+      lines.push(`    ${JSON.stringify(examples.sample_parameters)}`);
+    }
+
+    // Last execution record
+    if (t.last_execution_record && typeof t.last_execution_record === "object") {
+      const rec = t.last_execution_record;
+      lines.push("");
+      lines.push(dim("  Last execution:"));
+      if (rec.success !== undefined) lines.push(`    Status: ${rec.success ? green("success") : red("failed")}`);
+      if (rec.execution_time) lines.push(`    Time: ${rec.execution_time}`);
+      if (rec.error_message) lines.push(`    Error: ${red(rec.error_message)}`);
+    }
+  }
+
+  // Footer
+  if (typeof remaining === "number") {
+    lines.push("");
+    lines.push(dim(`${remaining} credits remaining`));
+  }
+
+  return lines.join("\n");
+}
+
+// ── call ──────────────────────────────────────────────────────────────
+
+export function formatCallResult(result) {
+  const success = result.success ?? false;
+  const cost = result.cost ?? result.credits_used ?? 0;
+  const remaining = result.remaining_credits;
+  const executionId = result.execution_id;
+  const toolId = result.tool_id;
+  const lines = [];
+
+  // Status line
+  if (success) {
+    let timePart = "";
+    // elapsed_time_ms is in milliseconds; execution_time is in seconds
+    if (typeof result.elapsed_time_ms === "number") {
+      timePart = `${Math.round(result.elapsed_time_ms)}ms`;
+    } else if (typeof result.execution_time === "number") {
+      timePart = `${Math.round(result.execution_time * 1000)}ms`;
+    }
+    const parts = [`${green("\u2713")} ${bold("success")}`];
+    if (timePart) parts.push(dim(timePart));
+    if (cost) parts.push(`${yellow(String(cost))} credits`);
+    if (typeof remaining === "number") parts.push(dim(`(${remaining} remaining)`));
+    lines.push(parts.join("  \u00b7  "));
+  } else {
+    lines.push(`${red("\u2718")} ${bold("failed")}`);
+    const errMsg = result.error_message ?? "Unknown error";
+    lines.push(red(errMsg));
+  }
+
+  // Execution metadata
+  const metaParts = [];
+  if (toolId) metaParts.push(`tool: ${toolId}`);
+  if (executionId) metaParts.push(`id: ${executionId}`);
+  if (metaParts.length > 0) lines.push(dim(metaParts.join("  \u00b7  ")));
+
+  // Result data
+  const data = result.result ?? {};
+  const fullContentUrl = typeof data.full_content_file_url === "string" ? data.full_content_file_url : null;
+
+  if (fullContentUrl) {
+    // ── Truncated result ──
+    const msg = data.message;
+    if (msg) lines.push(`\n${yellow(msg)}`);
+
+    lines.push(`\n${bold("Full content (valid 120 min):")}`);
+    lines.push(`  ${cyan(fullContentUrl)}`);
+    lines.push(`  ${dim("Download:")} curl -o result.json '${fullContentUrl}'`);
+
+    // Schema: compact one-line summary of the data structure
+    if (data.content_schema) {
+      lines.push(`\n${bold("Schema:")}`);
+      lines.push(formatSchema(data.content_schema, "  "));
+    }
+
+    // Truncated content preview
+    if (data.truncated_content) {
+      lines.push(`\n${bold("Preview:")}`);
+      const raw = typeof data.truncated_content === "string"
+        ? data.truncated_content
+        : JSON.stringify(data.truncated_content, null, 2);
+      const previewLines = raw.slice(0, 800).split("\n").slice(0, 15);
+      for (const l of previewLines) lines.push(dim(`  ${l}`));
+      if (raw.length > 800) lines.push(dim("  ..."));
+      lines.push(`\n${dim("Use --max-size -1 for full output, or download the file above.")}`);
+    }
+  } else if (data.data !== undefined) {
+    // Standard result with data field
+    lines.push(`\n${JSON.stringify(data.data, null, 2)}`);
+  } else if (Object.keys(data).length > 0) {
+    // Fallback: raw result object
+    lines.push(`\n${JSON.stringify(data, null, 2)}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── helpers ───────────────────────────────────────────────────────────
+
+/** Format a JSON Schema into a compact readable tree. */
+function formatSchema(schema, indent = "", depth = 0) {
+  if (depth > 8 || !schema || typeof schema !== "object") return `${indent}${dim(schema?.type ?? "(unknown)")}`;
+  const lines = [];
+  if (schema.type === "object" && schema.properties) {
+    for (const [key, val] of Object.entries(schema.properties)) {
+      const type = val.type ?? "any";
+      if (type === "array" && val.items?.properties) {
+        lines.push(`${indent}${cyan(key)}: ${dim(type + " of")}`);
+        lines.push(formatSchema(val.items, indent + "  ", depth + 1));
+      } else if (type === "object" && val.properties) {
+        lines.push(`${indent}${cyan(key)}: ${dim(type)}`);
+        lines.push(formatSchema(val, indent + "  ", depth + 1));
+      } else {
+        lines.push(`${indent}${cyan(key)}: ${dim(type)}`);
+      }
+    }
+  } else {
+    lines.push(`${indent}${dim(schema.type ?? "any")}`);
+  }
+  return lines.join("\n");
+}
+
+/** Handle description that may be a string, i18n object {en: "...", zh: "..."}, or other. */
+function stringifyDesc(desc) {
+  if (!desc) return "";
+  if (typeof desc === "string") return desc;
+  if (typeof desc === "object") {
+    return desc.en || desc.zh || desc["zh-CN"] || Object.values(desc).find((v) => typeof v === "string") || "";
+  }
+  return String(desc);
+}

package/src/output/json.mjs

@@ -0,0 +1,11 @@
+export function outputJson(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+
+export function outputJsonError(error, exitCode = 1) {
+  const obj = { error: error.message || String(error) };
+  if (error.code) obj.code = error.code;
+  if (error.hint) obj.hint = error.hint;
+  obj.exit_code = exitCode;
+  process.stderr.write(JSON.stringify(obj) + "\n");
+}

package/src/output/spinner.mjs

@@ -0,0 +1,17 @@
+const FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+
+export function createSpinner(message) {
+  if (!process.stderr.isTTY) return { stop() {} };
+
+  let i = 0;
+  const timer = setInterval(() => {
+    process.stderr.write(`\r  ${FRAMES[i++ % FRAMES.length]} ${message}`);
+  }, 80);
+
+  return {
+    stop(clearLine = true) {
+      clearInterval(timer);
+      if (clearLine) process.stderr.write("\r\x1b[K");
+    },
+  };
+}

package/src/session/session.mjs

@@ -0,0 +1,53 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+const SESSION_TTL_MS = 30 * 60 * 1000;
+
+function sessionPath() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg || join(homedir(), ".config");
+  return join(base, "qveris", ".session.json");
+}
+
+export function readSession() {
+  try {
+    const data = JSON.parse(readFileSync(sessionPath(), "utf-8"));
+    if (data.timestamp && Date.now() - data.timestamp > SESSION_TTL_MS) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSession(data) {
+  const dir = dirname(sessionPath());
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(sessionPath(), JSON.stringify({ ...data, timestamp: Date.now() }, null, 2) + "\n", { mode: 0o600 });
+}
+
+export function resolveToolId(idOrIndex) {
+  if (!/^\d+$/.test(idOrIndex)) return { toolId: idOrIndex, fromSession: false };
+
+  const session = readSession();
+  if (!session || !session.results) return { toolId: idOrIndex, fromSession: false };
+
+  const index = parseInt(idOrIndex, 10) - 1;
+  if (index < 0 || index >= session.results.length) {
+    return { toolId: idOrIndex, fromSession: false };
+  }
+
+  return {
+    toolId: session.results[index].tool_id,
+    name: session.results[index].name,
+    discoveryId: session.discoveryId,
+    fromSession: true,
+  };
+}
+
+export function getSessionDiscoveryId() {
+  const session = readSession();
+  return session?.discoveryId || null;
+}

package/src/utils/params.mjs

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "../errors/handler.mjs";
+
+export function resolveParams(value) {
+  if (!value || value === "{}") return {};
+
+  let raw = value;
+
+  if (value === "-") {
+    if (process.stdin.isTTY) {
+      throw new CliError("PARAMS_INVALID_JSON", "No data piped to stdin. Usage: echo '{...}' | qveris call ... --params -");
+    }
+    try {
+      // Use fd 0 (stdin) which works cross-platform (Linux, macOS, Windows)
+      // Limit to 1MB to prevent excessive memory usage from large piped input
+      const MAX_STDIN = 1024 * 1024;
+      raw = readFileSync(0, "utf-8").slice(0, MAX_STDIN);
+    } catch {
+      throw new CliError("PARAMS_INVALID_JSON", "Failed to read from stdin");
+    }
+  } else if (value.startsWith("@")) {
+    const filePath = value.slice(1);
+    try {
+      raw = readFileSync(filePath, "utf-8");
+    } catch (err) {
+      throw new CliError("PARAMS_INVALID_JSON", `Cannot read params file: ${filePath}`);
+    }
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new CliError("PARAMS_INVALID_JSON", `${err.message}`);
+  }
+}