@qverisai/cli 0.2.0 → 0.4.0

package/README.md

@@ -57,7 +57,7 @@ tool: weather_gov...  ·  id: 7ebcaf9d-...
 **One-liner (recommended):**
 
 ```bash
-curl -fsSL https://qveris.ai/install | bash
+curl -fsSL https://qveris.ai/cli/install | bash
 ```
 
 **Or via npm:**
@@ -104,9 +104,9 @@ qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
 
 | Command | Description |
 |---------|-------------|
-| `qveris login` | Authenticate with API key (opens browser or `--token` for direct input) |
+| `qveris login` | Authenticate with API key (interactive region selection, opens browser, or `--token` for direct input) |
 | `qveris logout` | Remove stored key |
-| `qveris whoami` | Show current auth status and key source |
+| `qveris whoami` | Show current auth status, key source, and region |
 | `qveris credits` | Check credit balance |
 
 ### Utilities
@@ -114,7 +114,7 @@ qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
 | Command | Description |
 |---------|-------------|
 | `qveris interactive` | Launch REPL mode (discover/inspect/call/codegen in one session) |
-| `qveris doctor` | Self-check: Node.js version, API key, connectivity |
+| `qveris doctor` | Self-check: Node.js version, API key, region, connectivity |
 | `qveris config <subcommand>` | Manage CLI settings (set, get, list, reset, path) |
 | `qveris completions <shell>` | Generate shell completions (bash/zsh/fish) |
 
@@ -251,13 +251,18 @@ The API region is auto-detected from your key prefix:
 | `sk-xxx` | Global | `https://qveris.ai/api/v1` |
 | `sk-cn-xxx` | China | `https://qveris.cn/api/v1` |
 
-No extra configuration needed. To override manually:
+No extra configuration needed. `qveris login` prompts for region selection interactively on first use.
+
+**Agent / script usage:** Use `--token` with a region-prefixed key, or set environment variables:
 
 ```bash
-# Via environment variable
+# Key prefix auto-detection (recommended)
+qveris login --token "sk-cn-xxx"
+
+# Or environment variable
 export QVERIS_REGION=cn
 
-# Or set a custom base URL
+# Or custom base URL
 export QVERIS_BASE_URL=https://custom.endpoint/api/v1
 
 # Or per-command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qverisai/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "QVeris CLI -- discover, inspect, and call 10,000+ capabilities",
   "type": "module",
   "bin": {

package/scripts/install.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # QVeris CLI Installer
-# Usage: curl -fsSL https://qveris.ai/install | bash
+# Usage: curl -fsSL https://qveris.ai/cli/install | bash
 set -euo pipefail
 
 BOLD='\033[1m'

package/src/commands/config.mjs

@@ -1,5 +1,6 @@
 import { getConfigPath, getConfigValue, setConfigValue, writeConfig } from "../config/store.mjs";
-import { resolveAll } from "../config/resolve.mjs";
+import { resolve, resolveAll } from "../config/resolve.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { bold, dim, cyan } from "../output/colors.mjs";
 import { outputJson } from "../output/json.mjs";
 
@@ -64,11 +65,17 @@ function configGet(key, flags) {
 
 function configList(flags) {
   const all = resolveAll();
+
+  // Resolve effective region
+  const { value: apiKey } = resolve("api_key", flags.apiKey);
+  const { region, source: regionSource, baseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
+
   if (flags.json) {
     const obj = {};
     for (const [k, v] of Object.entries(all)) {
       obj[k] = { value: k === "api_key" && v.value ? mask(v.value) : v.value, source: v.source };
     }
+    obj._region = { region, source: regionSource, baseUrl };
     outputJson(obj);
     return;
   }
@@ -78,6 +85,7 @@ function configList(flags) {
     const display = key === "api_key" && value ? mask(value) : String(value ?? dim("(not set)"));
     console.log(`  ${cyan(key.padEnd(20))}${display.padEnd(25)}${dim(source)}`);
   }
+  console.log(`\n  ${bold("Effective region:")} ${region} ${dim(`(${regionSource})`)} → ${dim(baseUrl)}`);
   console.log();
 }
 

package/src/commands/credits.mjs

@@ -1,11 +1,14 @@
 import { resolveApiKey } from "../client/auth.mjs";
 import { discoverTools } from "../client/api.mjs";
+import { resolveBaseUrl, getSiteUrl } from "../config/region.mjs";
 import { bold, dim, cyan, yellow, green } from "../output/colors.mjs";
 import { outputJson } from "../output/json.mjs";
 import { createSpinner } from "../output/spinner.mjs";
 
 export async function runCredits(flags) {
   const apiKey = resolveApiKey(flags.apiKey);
+  const { region, baseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
+  const accountUrl = `${getSiteUrl(region, baseUrl)}/account`;
 
   const spinner = flags.json ? { stop() {} } : createSpinner("Checking credits...");
 
@@ -20,10 +23,10 @@ export async function runCredits(flags) {
       outputJson({ remaining_credits: credits ?? null });
     } else if (credits !== undefined && credits !== null) {
       console.log(`\n  ${green("\u2713")} Credits remaining: ${bold(yellow(String(credits)))}`);
-      console.log(`  ${dim("Manage at:")} ${cyan("https://qveris.ai/account")}\n`);
+      console.log(`  ${dim("Manage at:")} ${cyan(accountUrl)}\n`);
     } else {
       console.log(`\n  ${dim("Credit balance not available in API response.")}`);
-      console.log(`  Check at: ${cyan("https://qveris.ai/account")}\n`);
+      console.log(`  Check at: ${cyan(accountUrl)}\n`);
     }
   } catch (err) {
     spinner.stop();

package/src/commands/discover.mjs

@@ -1,5 +1,6 @@
 import { resolveApiKey } from "../client/auth.mjs";
 import { discoverTools } from "../client/api.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { writeSession } from "../session/session.mjs";
 import { formatDiscoverResult } from "../output/formatter.mjs";
 import { outputJson } from "../output/json.mjs";
@@ -25,9 +26,12 @@ export async function runDiscover(query, flags) {
 
     // Store richer session data for index resolution
     const tools = result.results ?? [];
+    const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
     writeSession({
       discoveryId: result.search_id,
       query,
+      region,
+      baseUrl: resolvedBaseUrl,
       results: tools.map((t, i) => ({
         index: i + 1,
         tool_id: t.tool_id,

package/src/commands/doctor.mjs

@@ -1,5 +1,6 @@
 import { resolve } from "../config/resolve.mjs";
 import { discoverTools } from "../client/api.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { bold, green, red, dim, cyan } from "../output/colors.mjs";
 
 export async function runDoctor(flags) {
@@ -22,6 +23,10 @@ export async function runDoctor(flags) {
     const masked = apiKey.slice(0, 6) + "..." + apiKey.slice(-4);
     console.log(`  ${green("\u2713")} API key configured (${masked} via ${source})`);
 
+    // Show resolved region
+    const { baseUrl, region, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
+    console.log(`  ${green("\u2713")} Region: ${region} ${dim(`(${regionSource})`)} → ${dim(baseUrl)}`);
+
     // Test connectivity
     process.stderr.write(`  \u2026 Testing API connectivity...\r`);
     try {

package/src/commands/interactive.mjs

@@ -1,17 +1,21 @@
 import { createInterface } from "node:readline";
 import { resolveApiKey } from "../client/auth.mjs";
 import { discoverTools, inspectToolsByIds, callTool } from "../client/api.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { resolveParams } from "../utils/params.mjs";
 import { formatDiscoverResult, formatInspectResult, formatCallResult } from "../output/formatter.mjs";
 import { generateSnippet } from "../output/codegen.mjs";
 import { writeSession } from "../session/session.mjs";
+import { VERSION } from "../config/defaults.mjs";
 import { bold, dim, cyan } from "../output/colors.mjs";
+import { printWelcomeBanner } from "../output/banner.mjs";
 import { handleError } from "../errors/handler.mjs";
 import { createSpinner } from "../output/spinner.mjs";
 
 export async function runInteractive(flags) {
   const apiKey = resolveApiKey(flags.apiKey);
   const baseUrl = flags.baseUrl;
+  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: baseUrl, apiKey });
   const limit = parseInt(flags.limit, 10) || 5;
   const discoverTimeout = (parseInt(flags.timeout, 10) || 30) * 1000;
   const callTimeout = (parseInt(flags.timeout, 10) || 60) * 1000;
@@ -22,7 +26,11 @@ export async function runInteractive(flags) {
     lastCallContext: null,
   };
 
-  console.log(`\n  ${bold("QVeris Interactive Mode")}`);
+  if (!flags.json) {
+    printWelcomeBanner({ version: VERSION, noColor: flags.noColor, compact: true });
+  }
+
+  console.log(`  ${bold("QVeris Interactive Mode")}`);
   console.log(`  ${dim("Type 'help' for commands, 'exit' to quit.")}\n`);
 
   const rl = createInterface({
@@ -57,7 +65,7 @@ export async function runInteractive(flags) {
             index: i + 1, tool_id: t.tool_id, name: t.name, provider_name: t.provider_name,
           }));
           // Persist session so index shortcuts work in subsequent non-interactive calls
-          writeSession({ discoveryId: result.search_id, query, results: state.results });
+          writeSession({ discoveryId: result.search_id, query, region, baseUrl: resolvedBaseUrl, results: state.results });
           console.log(formatDiscoverResult(result));
           break;
         }

package/src/commands/login.mjs

@@ -4,9 +4,10 @@ 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 { VERSION } from "../config/defaults.mjs";
+import { resolveBaseUrl, getSiteUrl } from "../config/region.mjs";
 import { bold, green, red, dim, cyan } from "../output/colors.mjs";
-
-const ACCOUNT_URL = "https://qveris.ai/account?page=api-keys";
+import { printLoginBanner } from "../output/banner.mjs";
 
 function openBrowser(url) {
   const cmds = { darwin: "open", win32: "cmd", linux: "xdg-open" };
@@ -85,16 +86,84 @@ function prompt(question) {
   });
 }
 
+/**
+ * Prompt user to select region interactively.
+ * Skipped if region is already determined via --base-url, QVERIS_REGION, or QVERIS_BASE_URL.
+ */
+function promptRegion() {
+  return new Promise((pResolve, pReject) => {
+    console.log(`  ${bold("Select your region / 选择站点区域:")}\n`);
+    console.log(`    ${cyan("1)")} Global  — qveris.ai  (International users)`);
+    console.log(`    ${cyan("2)")} China   — qveris.cn  (中国大陆用户)\n`);
+
+    if (!process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.question("  Enter 1 or 2: ", (answer) => { rl.close(); pResolve(answer.trim()); });
+      return;
+    }
+
+    process.stderr.write("  Enter 1 or 2: ");
+
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      try { process.stdin.setRawMode(false); } catch {}
+      process.stdin.pause();
+    };
+    const onExit = () => { try { process.stdin.setRawMode(false); } catch {} };
+    process.once("exit", onExit);
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+
+    const onData = (chunk) => {
+      const ch = chunk[0];
+      if (ch === "\x03") { cleanup(); process.removeListener("exit", onExit); process.stderr.write("\n"); pReject(new Error("Aborted")); return; }
+      if (ch === "1" || ch === "2") {
+        cleanup();
+        process.removeListener("exit", onExit);
+        process.stderr.write(`${ch}\n`);
+        pResolve(ch);
+      }
+      // Ignore other keys
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
 export async function runLogin(flags) {
   if (flags.token) {
-    await validateAndSave(flags.token);
+    await validateAndSave(flags.token, flags.baseUrl);
     return;
   }
 
-  console.log(`\n  Get your API key at: ${cyan(ACCOUNT_URL)}\n`);
+  if (!flags.json) {
+    printLoginBanner({ version: VERSION, noColor: flags.noColor });
+  }
+
+  // Determine region: if already set via flag/env, use that; otherwise ask the user.
+  const { region: presetRegion, baseUrl: presetBaseUrl, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl });
+  let region;
+  let baseUrl = presetBaseUrl;
+  if (regionSource !== "default") {
+    // Region explicitly configured — use it directly
+    region = presetRegion;
+  } else {
+    // No explicit region — let user choose interactively
+    let choice;
+    try {
+      choice = await promptRegion();
+    } catch {
+      return; // Ctrl+C
+    }
+    region = choice === "2" ? "cn" : "global";
+  }
+
+  const accountUrl = `${getSiteUrl(region, baseUrl)}/account?page=api-keys`;
+  console.log(`\n  Get your API key at: ${cyan(accountUrl)}\n`);
 
   if (!flags.noBrowser) {
-    openBrowser(ACCOUNT_URL);
+    openBrowser(accountUrl);
   }
 
   let key;
@@ -110,18 +179,21 @@ export async function runLogin(flags) {
     return;
   }
 
-  await validateAndSave(key);
+  await validateAndSave(key, flags.baseUrl);
 }
 
-async function validateAndSave(key) {
+async function validateAndSave(key, baseUrlFlag) {
   process.stderr.write(`  Validating key...`);
 
+  const { baseUrl, region, source } = resolveBaseUrl({ baseUrlFlag, apiKey: key });
+
   try {
-    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    await discoverTools({ apiKey: key, baseUrl, 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("Region:")} ${region} ${dim(`(${source})`)}`);
     console.log(`  ${dim("Key saved to config.")}`);
   } catch {
     console.error(`\r\x1b[K`);
@@ -145,15 +217,17 @@ export async function runWhoami(flags) {
   }
 
   const masked = key.slice(0, 6) + "..." + key.slice(-4);
+  const { baseUrl, region, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey: key });
 
   process.stderr.write(`  Validating...`);
 
   try {
-    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    await discoverTools({ apiKey: key, baseUrl, 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)}`);
+    console.log(`  Region: ${region} ${dim(`(${regionSource})`)}`);
   } catch {
     console.error(`\r\x1b[K`);
     console.log(`\n  ${red("\u2718")} Key ${masked} is ${red("invalid")}`);

package/src/config/region.mjs

@@ -13,6 +13,26 @@ const REGION_URLS = {
   cn: "https://qveris.cn/api/v1",
 };
 
+const SITE_URLS = {
+  global: "https://qveris.ai",
+  cn: "https://qveris.cn",
+};
+
+/**
+ * Get the site URL (not API URL) for a given region.
+ * For custom regions, attempts to infer from the base URL domain.
+ * @param {string} region
+ * @param {string} [baseUrl] - The resolved API base URL (used to infer site for custom regions)
+ * @returns {string}
+ */
+export function getSiteUrl(region, baseUrl) {
+  if (region === "custom" && baseUrl) {
+    if (baseUrl.includes("qveris.cn")) return SITE_URLS.cn;
+    if (baseUrl.includes("qveris.ai")) return SITE_URLS.global;
+  }
+  return SITE_URLS[region] || SITE_URLS.global;
+}
+
 /**
  * Detect region from API key prefix.
  * @param {string} apiKey

package/src/main.mjs

@@ -2,6 +2,7 @@ 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";
+import { printWelcomeBanner } from "./output/banner.mjs";
 
 export async function main(argv) {
   const rawArgs = argv.slice(2);
@@ -12,6 +13,10 @@ export async function main(argv) {
   }
 
   const flags = extractGlobalFlags(args);
+  if (flags.noColor) {
+    process.env.NO_COLOR = "1";
+  }
+
   const positional = flags._positional;
   const command = positional[0];
   const rest = positional.slice(1);
@@ -22,7 +27,7 @@ export async function main(argv) {
   }
 
   if (!command || flags.help) {
-    printUsage();
+    printUsage(flags);
     return;
   }
 
@@ -202,9 +207,13 @@ function extractGlobalFlags(args) {
   return flags;
 }
 
-function printUsage() {
+function printUsage(flags = {}) {
+  if (!flags.json) {
+    printWelcomeBanner({ version: VERSION, noColor: flags.noColor, compact: false });
+  }
+
   console.log(`
-  ${bold("QVeris CLI")} ${dim(`v${VERSION}`)} -- discover, inspect, and call 10,000+ capabilities
+  ${bold("QVeris CLI")} — ${dim("discover, inspect, and call 10,000+ capabilities")}
 
   ${bold("Usage:")}
     qveris <command> [args] [flags]
@@ -232,12 +241,18 @@ function printUsage() {
   ${bold("Global Flags:")}
     --json, -j             Output raw JSON
     --api-key <key>        Override API key
+    --base-url <url>       Override API base URL
     --timeout <seconds>    Request timeout
     --no-color             Disable colors
     --verbose, -v          Show request details
     --version, -V          Print version
     --help, -h             Show help
 
+  ${bold("Environment Variables:")}
+    QVERIS_API_KEY         API key
+    QVERIS_REGION          Region override (global | cn)
+    QVERIS_BASE_URL        Custom API base URL
+
   ${bold("Examples:")}
     qveris discover "weather forecast API"
     qveris inspect 1
@@ -245,6 +260,6 @@ function printUsage() {
     qveris call 1 --params @params.json --codegen curl
     qveris interactive
 
-  ${dim("https://qveris.ai")}
+  ${dim("https://qveris.ai (global) / https://qveris.cn (China)")}
 `);
 }

package/src/output/banner.mjs

@@ -0,0 +1,241 @@
+/**
+ * Welcome / login banners: gradient on solid block letters (brand cyan → indigo).
+ * Figlet font "Banner3" (filled #), mapped to █ for stronger contrast.
+ */
+
+import { homedir } from "node:os";
+import { cwd as processCwd } from "node:process";
+import { dim, cyan, isColorEnabled } from "./colors.mjs";
+
+/** @type {readonly [number, number, number][]} brand stops: highlight → mid → shadow */
+const BRAND_STOPS = [
+  [0, 242, 255], // #00F2FF
+  [0, 153, 255], // #0099FF
+  [26, 0, 255], // #1A00FF
+];
+
+const RESET = "\x1b[0m";
+
+/** Figlet -f Banner3 QVERIS (53 cols × 7 rows). # → █ at render. */
+const ASCII_QVERIS_HASH = [
+  " #######  ##     ## ######## ########  ####  ######  ",
+  "##     ## ##     ## ##       ##     ##  ##  ##    ## ",
+  "##     ## ##     ## ##       ##     ##  ##  ##       ",
+  "##     ## ##     ## ######   ########   ##   ######  ",
+  "##  ## ##  ##   ##  ##       ##   ##    ##        ## ",
+  "##    ##    ## ##   ##       ##    ##   ##  ##    ## ",
+  " ##### ##    ###    ######## ##     ## ####  ######  ",
+].join("\n");
+
+function solidBlockLines() {
+  return ASCII_QVERIS_HASH.split("\n").map((line) => line.replace(/#/g, "█"));
+}
+
+function colorDepth() {
+  try {
+    return typeof process.stdout.getColorDepth === "function"
+      ? process.stdout.getColorDepth()
+      : 8;
+  } catch {
+    return 8;
+  }
+}
+
+function lerp(a, b, t) {
+  return Math.round(a + (b - a) * t);
+}
+
+/** RGB along multi-stop gradient, t in [0,1]. */
+function rgbAt(t) {
+  const n = BRAND_STOPS.length - 1;
+  const x = Math.min(1, Math.max(0, t)) * n;
+  const i = Math.min(Math.floor(x), n - 1);
+  const f = x - i;
+  const [r1, g1, b1] = BRAND_STOPS[i];
+  const [r2, g2, b2] = BRAND_STOPS[i + 1];
+  return [lerp(r1, r2, f), lerp(g1, g2, f), lerp(b1, b2, f)];
+}
+
+function truecolorFg(r, g, b) {
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+/**
+ * Map column index to gradient color (horizontal sweep across the banner).
+ * Spaces stay uncolored. Consecutive non-space chars with identical RGB share one SGR span.
+ */
+function paintLineTruecolor(line, maxCols) {
+  if (!line.length) return "";
+  const denom = Math.max(1, maxCols - 1);
+  let out = "";
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === " ") {
+      out += ch;
+      i++;
+      continue;
+    }
+    const t0 = i / denom;
+    const [r0, g0, b0] = rgbAt(t0);
+    let j = i + 1;
+    while (j < line.length) {
+      const chj = line[j];
+      if (chj === " ") break;
+      const t = j / denom;
+      const [r, g, b] = rgbAt(t);
+      if (r !== r0 || g !== g0 || b !== b0) break;
+      j++;
+    }
+    out += truecolorFg(r0, g0, b0) + line.slice(i, j) + RESET;
+    i = j;
+  }
+  return out;
+}
+
+/** 16-color fallback: batched SGR per band (cyan / bold cyan / dim cyan). */
+function paintLineFallback(line, maxCols) {
+  if (!isColorEnabled()) return line;
+  const denom = Math.max(1, maxCols - 1);
+  let out = "";
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === " ") {
+      out += ch;
+      i++;
+      continue;
+    }
+    const band0 = Math.min(2, Math.floor((i / denom) * 3));
+    let j = i + 1;
+    while (j < line.length) {
+      const chj = line[j];
+      if (chj === " ") break;
+      const band = Math.min(2, Math.floor((j / denom) * 3));
+      if (band !== band0) break;
+      j++;
+    }
+    const chunk = line.slice(i, j);
+    if (band0 === 0) out += `\x1b[36m${chunk}\x1b[0m`;
+    else if (band0 === 1) out += `\x1b[1;36m${chunk}\x1b[0m`;
+    else out += `\x1b[2;36m${chunk}\x1b[0m`;
+    i = j;
+  }
+  return out;
+}
+
+export function bannerColorAllowed(noColorFlag) {
+  if (noColorFlag) return false;
+  return isColorEnabled();
+}
+
+function shortenPath(p) {
+  const home = homedir();
+  if (p === home) return "~";
+  if (p.startsWith(home + "/")) return "~" + p.slice(home.length);
+  return p;
+}
+
+/** Strip SGR ANSI sequences (truecolor / 16-color). */
+function stripAnsi(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+const RE_HAN = /\p{Script=Han}/u;
+const RE_HANGUL = /\p{Script=Hangul}/u;
+
+/** Terminal display width: CJK/Hangul/fullwidth = 2 cols (matches typical monospace). */
+function displayWidth(str) {
+  let w = 0;
+  for (const ch of str) {
+    const cp = ch.codePointAt(0);
+    if (RE_HAN.test(ch) || RE_HANGUL.test(ch)) w += 2;
+    else if (cp >= 0xff01 && cp <= 0xff60) w += 2; // fullwidth forms
+    else w += 1;
+  }
+  return w;
+}
+
+function centerBlock(lines, termCols) {
+  const widths = lines.map((l) => displayWidth(stripAnsi(l)));
+  const maxW = Math.max(...widths, 1);
+  const pad = termCols >= maxW + 4 ? Math.max(0, Math.floor((termCols - maxW) / 2)) : 2;
+  const prefix = " ".repeat(pad);
+  return lines.map((l) => prefix + l);
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.version
+ * @param {boolean} [opts.noColor]
+ * @param {boolean} [opts.compact] — fewer blank lines (e.g. interactive)
+ */
+export function printWelcomeBanner(opts) {
+  const { version, noColor = false, compact = false } = opts;
+  if (!bannerColorAllowed(noColor)) {
+    printPlainBanner({ version, compact });
+    return;
+  }
+
+  const rawLines = solidBlockLines();
+  const maxW = Math.max(...rawLines.map((l) => l.length));
+  const termCols = process.stdout.columns || 80;
+  const useTc = colorDepth() >= 24;
+
+  const painted = rawLines.map((line) => {
+    const padded = line.padEnd(maxW);
+    return useTc ? paintLineTruecolor(padded, maxW) : paintLineFallback(padded, maxW);
+  });
+  const centered = centerBlock(painted, termCols);
+
+  const nl = compact ? "\n" : "\n\n";
+  console.log(nl + centered.join("\n"));
+
+  const tag = "✦ Discover · Inspect · Call · 10,000+ capabilities · intelligent orchestration ✦";
+  const meta = dim(`v${version} · ${shortenPath(processCwd())}`);
+  const tagLine = centerLine(dim(cyan(tag)), termCols);
+  const metaLine = centerLine(meta, termCols);
+
+  console.log("\n" + tagLine + "\n" + metaLine + (compact ? "\n" : "\n\n"));
+}
+
+function centerLine(text, termCols) {
+  const len = displayWidth(stripAnsi(text));
+  const pad = termCols >= len + 4 ? Math.max(0, Math.floor((termCols - len) / 2)) : 2;
+  return " ".repeat(pad) + text;
+}
+
+function printPlainBanner({ version, compact }) {
+  const rawLines = solidBlockLines();
+  const termCols = process.stdout.columns || 80;
+  const centered = centerBlock(rawLines, termCols);
+  const nl = compact ? "\n" : "\n\n";
+  console.log(nl + centered.join("\n"));
+  const tag = "✦ Discover · Inspect · Call · 10,000+ capabilities · intelligent orchestration ✦";
+  const meta = `v${version} · ${shortenPath(processCwd())}`;
+  const tagLine = centerLine(dim(tag), termCols);
+  const metaLine = centerLine(dim(meta), termCols);
+  console.log("\n" + tagLine + "\n" + metaLine + (compact ? "\n" : "\n\n"));
+}
+
+/**
+ * Login screen: banner + framed hint (cyan border).
+ */
+export function printLoginBanner(opts) {
+  const { version, noColor = false } = opts;
+  printWelcomeBanner({ version, noColor, compact: true });
+
+  if (!bannerColorAllowed(noColor)) {
+    console.log(dim("  ─ Secure login · paste your API key below"));
+    return;
+  }
+
+  const termCols = process.stdout.columns || 80;
+  const inner = " Secure login · API key ";
+  const maxInner = Math.min(inner.length + 4, termCols - 4);
+  const bar = "─".repeat(Math.max(8, maxInner));
+  const top = centerLine(cyan("╭" + bar + "╮"), termCols);
+  const mid = centerLine(cyan("│") + dim(inner) + cyan("│"), termCols);
+  const bot = centerLine(cyan("╰" + bar + "╯"), termCols);
+  console.log(top + "\n" + mid + "\n" + bot + "\n");
+}

package/src/output/colors.mjs

@@ -1,9 +1,13 @@
-const enabled =
-  !process.env.NO_COLOR &&
-  (process.env.FORCE_COLOR === "1" || (process.stdout.isTTY && process.stderr.isTTY));
+let memoizedEnabled;
+export const isColorEnabled = () => {
+  if (memoizedEnabled !== undefined) return memoizedEnabled;
+  memoizedEnabled = !process.env.NO_COLOR &&
+    (process.env.FORCE_COLOR === "1" || (process.stdout.isTTY && process.stderr.isTTY));
+  return memoizedEnabled;
+};
 
-const code = (open, close) =>
-  enabled ? (s) => `\x1b[${open}m${s}\x1b[${close}m` : (s) => s;
+const code = (open, close) => (s) =>
+  isColorEnabled() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
 
 export const bold = code("1", "22");
 export const dim = code("2", "22");
@@ -12,5 +16,3 @@ 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;