@qverisai/cli 0.1.0

package/src/commands/login.mjs

@@ -0,0 +1,163 @@
+import { createInterface } from "node:readline";
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { resolve } from "../config/resolve.mjs";
+import { setConfigValue, deleteConfigValue } from "../config/store.mjs";
+import { discoverTools } from "../client/api.mjs";
+import { bold, green, red, dim, cyan } from "../output/colors.mjs";
+
+const ACCOUNT_URL = "https://qveris.ai/account?page=api-keys";
+
+function openBrowser(url) {
+  const cmds = { darwin: "open", win32: "cmd", linux: "xdg-open" };
+  const cmd = cmds[platform()] || "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", "", url] : [url];
+  execFile(cmd, args, () => {});
+}
+
+/**
+ * Masked input prompt using raw mode.
+ * Handles Backspace, Ctrl+C, paste (multi-char chunks), and echoes * per character.
+ */
+function prompt(question) {
+  return new Promise((pResolve, pReject) => {
+    process.stderr.write(question);
+
+    // Fallback for non-TTY (piped input): read without masking
+    if (!process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.question("", (answer) => { rl.close(); pResolve(answer.trim()); });
+      return;
+    }
+
+    let buf = "";
+
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      try { process.stdin.setRawMode(false); } catch { /* already restored */ }
+      process.stdin.pause();
+    };
+
+    // Safety net: restore terminal if process exits unexpectedly
+    const onExit = () => { try { process.stdin.setRawMode(false); } catch {} };
+    process.once("exit", onExit);
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+
+    // Process each character in the chunk individually to handle paste correctly
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        // Ctrl+C
+        if (char === "\x03") {
+          cleanup();
+          process.removeListener("exit", onExit);
+          process.stderr.write("\n");
+          pReject(new Error("Aborted"));
+          return;
+        }
+        // Enter
+        if (char === "\r" || char === "\n") {
+          cleanup();
+          process.removeListener("exit", onExit);
+          process.stderr.write("\n");
+          pResolve(buf.trim());
+          return;
+        }
+        // Backspace / Delete
+        if (char === "\x7f" || char === "\b") {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            process.stderr.write("\b \b");
+          }
+          continue;
+        }
+        // Printable character
+        if (char.charCodeAt(0) >= 32) {
+          buf += char;
+          process.stderr.write("*");
+        }
+      }
+    };
+
+    process.stdin.on("data", onData);
+  });
+}
+
+export async function runLogin(flags) {
+  if (flags.token) {
+    await validateAndSave(flags.token);
+    return;
+  }
+
+  console.log(`\n  Get your API key at: ${cyan(ACCOUNT_URL)}\n`);
+
+  if (!flags.noBrowser) {
+    openBrowser(ACCOUNT_URL);
+  }
+
+  let key;
+  try {
+    key = await prompt("  Paste your API key: ");
+  } catch {
+    // Ctrl+C during prompt
+    return;
+  }
+  if (!key) {
+    console.error(`  ${red("\u2718")} No key provided.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await validateAndSave(key);
+}
+
+async function validateAndSave(key) {
+  process.stderr.write(`  Validating key...`);
+
+  try {
+    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    setConfigValue("api_key", key);
+    const masked = key.slice(0, 6) + "..." + key.slice(-4);
+    console.error(`\r\x1b[K`);
+    console.log(`  ${green("\u2713")} Authenticated as ${bold(masked)}`);
+    console.log(`  ${dim("Key saved to config.")}`);
+  } catch {
+    console.error(`\r\x1b[K`);
+    console.error(`  ${red("\u2718")} Invalid API key. Please check and try again.`);
+    process.exitCode = 1;
+  }
+}
+
+export async function runLogout() {
+  deleteConfigValue("api_key");
+  console.log(`  ${green("\u2713")} API key removed from config.`);
+}
+
+export async function runWhoami(flags) {
+  const { value: key, source } = resolve("api_key", flags.apiKey);
+
+  if (!key) {
+    console.log(`\n  Not authenticated. Run ${cyan("qveris login")} to set your API key.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const masked = key.slice(0, 6) + "..." + key.slice(-4);
+
+  process.stderr.write(`  Validating...`);
+
+  try {
+    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    process.stderr.write("\r\x1b[K");
+    console.log(`\n  ${green("\u2713")} Authenticated`);
+    console.log(`  Key:    ${bold(masked)}`);
+    console.log(`  Source: ${dim(source)}`);
+  } catch {
+    console.error(`\r\x1b[K`);
+    console.log(`\n  ${red("\u2718")} Key ${masked} is ${red("invalid")}`);
+    console.log(`  Source: ${dim(source)}`);
+    process.exitCode = 1;
+  }
+}

package/src/compat/aliases.mjs

@@ -0,0 +1,30 @@
+const COMMAND_ALIASES = {
+  search: "discover",
+  execute: "call",
+  invoke: "call",
+  "get-by-ids": "inspect",
+  repl: "interactive",
+};
+
+const FLAG_ALIASES = {
+  "--search-id": "--discovery-id",
+};
+
+export function normalizeLegacyArgs(args) {
+  const result = [...args];
+  const warnings = [];
+
+  if (result.length > 0 && COMMAND_ALIASES[result[0]]) {
+    warnings.push(`'${result[0]}' is deprecated; use '${COMMAND_ALIASES[result[0]]}' instead.`);
+    result[0] = COMMAND_ALIASES[result[0]];
+  }
+
+  for (let i = 0; i < result.length; i++) {
+    if (FLAG_ALIASES[result[i]]) {
+      warnings.push(`'${result[i]}' is deprecated; use '${FLAG_ALIASES[result[i]]}' instead.`);
+      result[i] = FLAG_ALIASES[result[i]];
+    }
+  }
+
+  return { args: result, warnings };
+}

package/src/config/defaults.mjs

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
+
+export const DEFAULTS = {
+  base_url: "https://qveris.ai/api/v1",
+  default_limit: 5,
+  default_max_size: 4096,
+  color: "auto",
+  output_format: "human",
+};
+
+export const VERSION = pkg.version;

package/src/config/resolve.mjs

@@ -0,0 +1,32 @@
+import { readConfig } from "./store.mjs";
+import { DEFAULTS } from "./defaults.mjs";
+
+const ENV_MAP = {
+  api_key: "QVERIS_API_KEY",
+  base_url: "QVERIS_BASE_URL",
+  default_limit: "QVERIS_DEFAULT_LIMIT",
+  default_max_size: "QVERIS_DEFAULT_MAX_SIZE",
+};
+
+export function resolve(key, flagValue) {
+  if (flagValue !== undefined && flagValue !== null) return { value: flagValue, source: "flag" };
+
+  const envVar = ENV_MAP[key];
+  if (envVar && process.env[envVar]) return { value: process.env[envVar], source: `env (${envVar})` };
+
+  const config = readConfig();
+  if (config[key] !== undefined) return { value: config[key], source: "config" };
+
+  if (DEFAULTS[key] !== undefined) return { value: DEFAULTS[key], source: "default" };
+
+  return { value: undefined, source: "none" };
+}
+
+export function resolveAll(flags = {}) {
+  const keys = new Set([...Object.keys(DEFAULTS), ...Object.keys(ENV_MAP), ...Object.keys(readConfig())]);
+  const result = {};
+  for (const key of keys) {
+    result[key] = resolve(key, flags[key]);
+  }
+  return result;
+}

package/src/config/store.mjs

@@ -0,0 +1,47 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+function configDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg || join(homedir(), ".config");
+  return join(base, "qveris");
+}
+
+function configPath() {
+  return join(configDir(), "config.json");
+}
+
+export function getConfigPath() {
+  return configPath();
+}
+
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config) {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+export function getConfigValue(key) {
+  return readConfig()[key];
+}
+
+export function setConfigValue(key, value) {
+  const config = readConfig();
+  config[key] = value;
+  writeConfig(config);
+}
+
+export function deleteConfigValue(key) {
+  const config = readConfig();
+  delete config[key];
+  writeConfig(config);
+}

package/src/errors/codes.mjs

@@ -0,0 +1,55 @@
+export const EX_OK = 0;
+export const EX_GENERAL = 1;
+export const EX_USAGE = 2;
+export const EX_UNAVAILABLE = 69;
+export const EX_TEMPFAIL = 75;
+export const EX_NOPERM = 77;
+export const EX_CONFIG = 78;
+
+export const ERROR_CODES = {
+  AUTH_MISSING_KEY: {
+    message: "No API key configured",
+    hint: "Run 'qveris login' or set QVERIS_API_KEY",
+    exit: EX_CONFIG,
+  },
+  AUTH_INVALID_KEY: {
+    message: "Authentication failed",
+    hint: "Check your key at https://qveris.ai/account",
+    exit: EX_NOPERM,
+  },
+  NET_TIMEOUT: {
+    message: "Request timed out",
+    hint: "Check connectivity or increase --timeout",
+    exit: EX_TEMPFAIL,
+  },
+  API_ERROR: {
+    message: "API error",
+    hint: null,
+    exit: EX_GENERAL,
+  },
+  PARAMS_INVALID_JSON: {
+    message: "Invalid JSON in --params",
+    hint: "Check JSON syntax in --params value",
+    exit: EX_USAGE,
+  },
+  TOOL_NOT_FOUND: {
+    message: "Tool not found",
+    hint: "Run 'qveris discover' to find available tools",
+    exit: EX_USAGE,
+  },
+  RATE_LIMITED: {
+    message: "Rate limited",
+    hint: "Wait and retry, or upgrade your plan",
+    exit: EX_TEMPFAIL,
+  },
+  CREDITS_INSUFFICIENT: {
+    message: "Insufficient credits",
+    hint: "Purchase credits at https://qveris.ai/pricing",
+    exit: EX_NOPERM,
+  },
+  SESSION_EXPIRED: {
+    message: "Session expired",
+    hint: "Run 'qveris discover' to start a new session",
+    exit: EX_USAGE,
+  },
+};

package/src/errors/handler.mjs

@@ -0,0 +1,35 @@
+import { red, bold, dim } from "../output/colors.mjs";
+import { outputJsonError } from "../output/json.mjs";
+import { ERROR_CODES, EX_GENERAL, EX_TEMPFAIL, EX_NOPERM } from "./codes.mjs";
+
+export class CliError extends Error {
+  constructor(code, detail) {
+    const template = ERROR_CODES[code] || { message: code, hint: null, exit: EX_GENERAL };
+    super(detail || template.message);
+    this.code = code;
+    this.hint = template.hint;
+    this.exitCode = template.exit;
+  }
+}
+
+export function handleError(err, jsonMode = false) {
+  const exitCode = err.exitCode || classifyHttpError(err) || EX_GENERAL;
+
+  if (jsonMode) {
+    outputJsonError(err, exitCode);
+  } else {
+    console.error(`\n  ${red("\u2718")}  ${bold("Error:")} ${err.message}`);
+    const hint = err.hint || ERROR_CODES[err.code]?.hint;
+    if (hint) console.error(`     ${dim(hint)}`);
+  }
+
+  process.exitCode = exitCode;
+}
+
+function classifyHttpError(err) {
+  const msg = err.message || "";
+  if (err.name === "AbortError" || msg.includes("abort")) return EX_TEMPFAIL;
+  if (msg.includes("401") || msg.includes("403")) return EX_NOPERM;
+  if (msg.includes("429")) return EX_TEMPFAIL;
+  return null;
+}

package/src/main.mjs

@@ -0,0 +1,250 @@
+import { normalizeLegacyArgs } from "./compat/aliases.mjs";
+import { handleError } from "./errors/handler.mjs";
+import { VERSION } from "./config/defaults.mjs";
+import { bold, dim, cyan } from "./output/colors.mjs";
+
+export async function main(argv) {
+  const rawArgs = argv.slice(2);
+  const { args, warnings } = normalizeLegacyArgs(rawArgs);
+
+  for (const w of warnings) {
+    console.error(`  ${dim("Deprecated:")} ${w}`);
+  }
+
+  const flags = extractGlobalFlags(args);
+  const positional = flags._positional;
+  const command = positional[0];
+  const rest = positional.slice(1);
+
+  if (flags.version) {
+    console.log(`qveris/${VERSION}`);
+    return;
+  }
+
+  if (!command || flags.help) {
+    printUsage();
+    return;
+  }
+
+  try {
+    switch (command) {
+      case "discover": {
+        const query = rest.join(" ");
+        if (!query) { console.error("  Usage: qveris discover <query>"); process.exitCode = 2; return; }
+        const { runDiscover } = await import("./commands/discover.mjs");
+        await runDiscover(query, flags);
+        break;
+      }
+      case "inspect": {
+        if (rest.length === 0) { console.error("  Usage: qveris inspect <tool_id|index> [...]"); process.exitCode = 2; return; }
+        const { runInspect } = await import("./commands/inspect.mjs");
+        await runInspect(rest, flags);
+        break;
+      }
+      case "call": {
+        if (rest.length === 0) { console.error("  Usage: qveris call <tool_id|index> [--params <json>]"); process.exitCode = 2; return; }
+        const { runCall } = await import("./commands/call.mjs");
+        await runCall(rest[0], flags);
+        break;
+      }
+      case "login": {
+        const { runLogin } = await import("./commands/login.mjs");
+        await runLogin(flags);
+        break;
+      }
+      case "logout": {
+        const { runLogout } = await import("./commands/login.mjs");
+        await runLogout();
+        break;
+      }
+      case "whoami": {
+        const { runWhoami } = await import("./commands/login.mjs");
+        await runWhoami(flags);
+        break;
+      }
+      case "credits": {
+        const { runCredits } = await import("./commands/credits.mjs");
+        await runCredits(flags);
+        break;
+      }
+      case "config": {
+        const subcommand = rest[0];
+        const subArgs = rest.slice(1);
+        if (!subcommand) { console.error("  Usage: qveris config <set|get|list|reset|path>"); process.exitCode = 2; return; }
+        const { runConfig } = await import("./commands/config.mjs");
+        await runConfig(subcommand, subArgs, flags);
+        break;
+      }
+      case "interactive":
+      case "repl": {
+        const { runInteractive } = await import("./commands/interactive.mjs");
+        await runInteractive(flags);
+        break;
+      }
+      case "doctor": {
+        const { runDoctor } = await import("./commands/doctor.mjs");
+        await runDoctor(flags);
+        break;
+      }
+      case "history": {
+        const { runHistory } = await import("./commands/history.mjs");
+        await runHistory(flags);
+        break;
+      }
+      case "completions": {
+        const { runCompletions } = await import("./commands/completions.mjs");
+        await runCompletions(rest[0]);
+        break;
+      }
+      default:
+        console.error(`  Unknown command: ${command}`);
+        console.error(`  Run ${cyan("qveris --help")} for available commands.`);
+        process.exitCode = 2;
+    }
+  } catch (err) {
+    handleError(err, flags.json);
+  }
+}
+
+// Boolean short flags: -j, -v, -V, -h
+const SHORT_BOOLS = { j: "json", v: "verbose", V: "version", h: "help" };
+
+// --key=value long flag mapping (flag name -> flags property)
+const VALUE_FLAGS = {
+  "api-key": "apiKey", "base-url": "baseUrl", timeout: "timeout",
+  limit: "limit", "discovery-id": "discoveryId", params: "params",
+  "max-size": "maxSize", codegen: "codegen", token: "token",
+};
+
+function takeNext(args, i, flag) {
+  const next = args[i + 1];
+  if (next === undefined || next.startsWith("--")) {
+    console.error(`  Error: ${flag} requires a value`);
+    process.exitCode = 2;
+    return undefined;
+  }
+  return next;
+}
+
+function extractGlobalFlags(args) {
+  const flags = { _positional: [] };
+
+  for (let i = 0; i < args.length; i++) {
+    let arg = args[i];
+
+    // -- signals end of options; everything after is positional
+    if (arg === "--") {
+      flags._positional.push(...args.slice(i + 1));
+      break;
+    }
+
+    // Handle --key=value syntax
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const eqIdx = arg.indexOf("=");
+      const key = arg.slice(2, eqIdx);
+      const val = arg.slice(eqIdx + 1);
+      if (VALUE_FLAGS[key]) { flags[VALUE_FLAGS[key]] = val; continue; }
+      // Boolean flags with =value (unusual but handle gracefully)
+      if (key === "json") { flags.json = true; continue; }
+    }
+
+    // Handle combined short flags: -jv → -j + -v
+    if (arg.startsWith("-") && !arg.startsWith("--") && arg.length > 2) {
+      const chars = arg.slice(1);
+      let allBool = true;
+      for (const ch of chars) { if (!SHORT_BOOLS[ch]) { allBool = false; break; } }
+      if (allBool) {
+        for (const ch of chars) flags[SHORT_BOOLS[ch]] = true;
+        continue;
+      }
+    }
+
+    switch (arg) {
+      case "--json": case "-j":
+        flags.json = true; break;
+      case "--no-color":
+        flags.noColor = true; break;
+      case "--verbose": case "-v":
+        flags.verbose = true; break;
+      case "--help": case "-h":
+        flags.help = true; break;
+      case "--version": case "-V":
+        flags.version = true; break;
+      case "--dry-run":
+        flags.dryRun = true; break;
+      case "--no-browser":
+        flags.noBrowser = true; break;
+      case "--clear":
+        flags.clear = true; break;
+      case "--api-key":
+        flags.apiKey = takeNext(args, i++, arg); break;
+      case "--base-url":
+        flags.baseUrl = takeNext(args, i++, arg); break;
+      case "--timeout":
+        flags.timeout = takeNext(args, i++, arg); break;
+      case "--limit":
+        flags.limit = takeNext(args, i++, arg); break;
+      case "--discovery-id":
+        flags.discoveryId = takeNext(args, i++, arg); break;
+      case "--params":
+        flags.params = takeNext(args, i++, arg); break;
+      case "--max-size":
+        flags.maxSize = takeNext(args, i++, arg); break;
+      case "--codegen":
+        flags.codegen = takeNext(args, i++, arg); break;
+      case "--token":
+        flags.token = takeNext(args, i++, arg); break;
+      default:
+        flags._positional.push(arg);
+    }
+  }
+
+  return flags;
+}
+
+function printUsage() {
+  console.log(`
+  ${bold("QVeris CLI")} ${dim(`v${VERSION}`)} -- discover, inspect, and call 10,000+ capabilities
+
+  ${bold("Usage:")}
+    qveris <command> [args] [flags]
+
+  ${bold("Core Commands:")}
+    ${cyan("discover")} <query>             Find capabilities by natural language
+    ${cyan("inspect")}  <tool_id|index>     View tool details, parameters, and stats
+    ${cyan("call")}     <tool_id|index>     Execute a capability
+
+  ${bold("Account:")}
+    ${cyan("login")}                        Authenticate with QVeris
+    ${cyan("logout")}                       Remove stored API key
+    ${cyan("whoami")}                       Show current auth status
+    ${cyan("credits")}                      Show credit balance
+
+  ${bold("Configuration:")}
+    ${cyan("config")}   set|get|list|reset  Manage CLI settings
+
+  ${bold("Utilities:")}
+    ${cyan("interactive")}                  Launch interactive REPL mode
+    ${cyan("history")}                      Show current session
+    ${cyan("doctor")}                       Self-check diagnostics
+    ${cyan("completions")} <shell>          Generate shell completions
+
+  ${bold("Global Flags:")}
+    --json, -j             Output raw JSON
+    --api-key <key>        Override API key
+    --timeout <seconds>    Request timeout
+    --no-color             Disable colors
+    --verbose, -v          Show request details
+    --version, -V          Print version
+    --help, -h             Show help
+
+  ${bold("Examples:")}
+    qveris discover "weather forecast API"
+    qveris inspect 1
+    qveris call 1 --params '{"city": "London"}'
+    qveris call 1 --params @params.json --codegen curl
+    qveris interactive
+
+  ${dim("https://qveris.ai")}
+`);
+}