@0dai-dev/cli 4.1.0 → 4.3.4

package/lib/utils/mcp-auth.js

@@ -0,0 +1,607 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const DEFAULT_MCP_HOST = "https://mcp.0dai.dev";
+const DEFAULT_CLOUD_SERVER_NAME = "claude.ai 0dai";
+const DEFAULT_CLOUD_SERVER_ID = "claude_ai_0dai";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+const EMBEDDED_TEMPLATE = `{
+  "mcpServers": {
+    "0dai": {
+      "command": "python3",
+      "args": ["{{ODAI_MCP_SERVER_SCRIPT}}", "--target", "{{PROJECT_PATH}}"],
+      "env": {"ODAI_PROJECT_PATH": "{{PROJECT_PATH}}"}
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{PROJECT_PATH}}"]
+    },
+    "claude.ai 0dai": {
+      "type": "http",
+      "url": "{{MCP_HOST}}/mcp"
+    }
+  }
+}
+`;
+
+function argAfter(args, names) {
+  const wanted = new Set(Array.isArray(names) ? names : [names]);
+  for (let i = 0; i < args.length; i++) {
+    const arg = String(args[i] || "");
+    if (wanted.has(arg) && args[i + 1]) return String(args[i + 1]);
+    for (const name of wanted) {
+      if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+    }
+  }
+  return "";
+}
+
+function parseMcpArgs(args = [], env = process.env) {
+  return {
+    reset: args.includes("--reset"),
+    noAuth: args.includes("--no-mcp-auth"),
+    yes: args.includes("--yes") || args.includes("-y"),
+    host: normalizeMcpHost(argAfter(args, ["--mcp-host"]) || env.ODAI_MCP_HOST || DEFAULT_MCP_HOST),
+  };
+}
+
+function normalizeMcpHost(raw) {
+  let value = String(raw || DEFAULT_MCP_HOST).trim();
+  if (!value) value = DEFAULT_MCP_HOST;
+  if (!/^https?:\/\//i.test(value)) value = `https://${value}`;
+  return value.replace(/\/+$/, "");
+}
+
+function escapeTemplateValue(value) {
+  return JSON.stringify(String(value)).slice(1, -1);
+}
+
+function renderTemplate(template, values) {
+  return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_m, key) => {
+    if (!(key in values)) return "";
+    return escapeTemplateValue(values[key]);
+  });
+}
+
+function repoRootFromPackage() {
+  return path.resolve(__dirname, "..", "..", "..", "..");
+}
+
+function resolveTemplatePath() {
+  const explicit = process.env.ODAI_MCP_TEMPLATE;
+  if (explicit) return { path: path.resolve(explicit), required: true };
+  const repoRoot = repoRootFromPackage();
+  const candidates = [
+    path.join(process.cwd(), "templates", "mcp", "mcp.json.template"),
+    path.join(repoRoot, "templates", "mcp", "mcp.json.template"),
+    path.join(__dirname, "..", "..", "templates", "mcp", "mcp.json.template"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return { path: candidate, required: false };
+  }
+  return { path: "", required: false };
+}
+
+function loadTemplate() {
+  const found = resolveTemplatePath();
+  if (found.path) {
+    if (!fs.existsSync(found.path)) {
+      throw new Error(`MCP template not found: ${found.path}`);
+    }
+    return { text: fs.readFileSync(found.path, "utf8"), source: found.path };
+  }
+  return { text: EMBEDDED_TEMPLATE, source: "embedded" };
+}
+
+function resolveMcpServerScript(target) {
+  const repoRoot = repoRootFromPackage();
+  const candidates = [
+    path.join(target, "scripts", "mcp_server.py"),
+    path.join(process.cwd(), "scripts", "mcp_server.py"),
+    path.join(repoRoot, "scripts", "mcp_server.py"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return "scripts/mcp_server.py";
+}
+
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    throw new Error(`${filePath} is not valid JSON: ${err.message}`);
+  }
+}
+
+function writeJsonIfChanged(filePath, value) {
+  const text = JSON.stringify(value, null, 2) + "\n";
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, "utf8") === text) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, text, "utf8");
+  return true;
+}
+
+function targetFromArgs(args) {
+  if (!Array.isArray(args)) return "";
+  for (let i = 0; i < args.length; i++) {
+    if (String(args[i]) === "--target" && args[i + 1]) return String(args[i + 1]);
+  }
+  return "";
+}
+
+function envTarget(config) {
+  const env = config && config.env && typeof config.env === "object" && !Array.isArray(config.env)
+    ? config.env
+    : {};
+  return typeof env.ODAI_PROJECT_PATH === "string" ? env.ODAI_PROJECT_PATH : "";
+}
+
+function normalizeConfigPath(value, base) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  const expanded = raw === "~" || raw.startsWith("~/")
+    ? path.join(os.homedir(), raw.slice(2))
+    : raw;
+  return path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+}
+
+function pathsDiffer(existingValue, incomingValue, base) {
+  if (!existingValue || !incomingValue) return false;
+  return normalizeConfigPath(existingValue, base) !== normalizeConfigPath(incomingValue, base);
+}
+
+function filesystemTarget(config) {
+  const args = Array.isArray(config && config.args) ? config.args : [];
+  if (args.length < 1) return "";
+  return String(args[args.length - 1] || "");
+}
+
+function shouldUpdateManagedServer(name, existingConfig, incomingConfig, options = {}) {
+  if (options.reset) return true;
+  const base = options.target ? path.resolve(options.target) : process.cwd();
+  if (name === "0dai") {
+    const existingArgTarget = targetFromArgs(existingConfig && existingConfig.args);
+    const incomingArgTarget = targetFromArgs(incomingConfig && incomingConfig.args);
+    const existingEnvTarget = envTarget(existingConfig);
+    const incomingEnvTarget = envTarget(incomingConfig);
+    if ((incomingArgTarget && !existingArgTarget) || pathsDiffer(existingArgTarget, incomingArgTarget, base)) {
+      return true;
+    }
+    if ((incomingEnvTarget && !existingEnvTarget) || pathsDiffer(existingEnvTarget, incomingEnvTarget, base)) {
+      return true;
+    }
+    return false;
+  }
+  if (name === "filesystem") {
+    const existingTarget = filesystemTarget(existingConfig);
+    const incomingTarget = filesystemTarget(incomingConfig);
+    return (incomingTarget && !existingTarget) || pathsDiffer(existingTarget, incomingTarget, base);
+  }
+  if (name === DEFAULT_CLOUD_SERVER_NAME) {
+    const existingUrl = existingConfig && typeof existingConfig.url === "string" ? existingConfig.url : "";
+    const incomingUrl = incomingConfig && typeof incomingConfig.url === "string" ? incomingConfig.url : "";
+    return !!incomingUrl && existingUrl !== incomingUrl;
+  }
+  return false;
+}
+
+function mergeMcpConfig(existing, incoming, options = {}) {
+  const out = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  const existingServers = out.mcpServers && typeof out.mcpServers === "object" && !Array.isArray(out.mcpServers)
+    ? { ...out.mcpServers }
+    : {};
+  const incomingServers = incoming && incoming.mcpServers && typeof incoming.mcpServers === "object"
+    ? incoming.mcpServers
+    : {};
+  const added = [];
+  const updated = [];
+
+  for (const [name, config] of Object.entries(incomingServers)) {
+    if (!(name in existingServers)) {
+      existingServers[name] = config;
+      added.push(name);
+      continue;
+    }
+    if (shouldUpdateManagedServer(name, existingServers[name], config, options)) {
+      existingServers[name] = config;
+      updated.push(name);
+    }
+  }
+
+  out.mcpServers = existingServers;
+  return { config: out, added, updated };
+}
+
+function ensureMcpConfig(target, options = {}) {
+  const resolvedTarget = path.resolve(target);
+  const { text, source } = loadTemplate();
+  const rendered = renderTemplate(text, {
+    PROJECT_PATH: resolvedTarget,
+    MCP_HOST: options.host || DEFAULT_MCP_HOST,
+    ODAI_MCP_SERVER_SCRIPT: resolveMcpServerScript(resolvedTarget),
+  });
+  let incoming;
+  try {
+    incoming = JSON.parse(rendered);
+  } catch (err) {
+    throw new Error(`MCP template rendered invalid JSON: ${err.message}`);
+  }
+
+  const mcpPath = path.join(resolvedTarget, ".mcp.json");
+  const existing = readJsonFile(mcpPath);
+  const merged = mergeMcpConfig(existing, incoming, { reset: !!options.reset, target: resolvedTarget });
+  const changed = writeJsonIfChanged(mcpPath, merged.config);
+  return { path: mcpPath, changed, template: source, added: merged.added, updated: merged.updated };
+}
+
+function ensureClaudeSettings(target) {
+  const settingsPath = path.join(path.resolve(target), ".claude", "settings.json");
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    settings = readJsonFile(settingsPath);
+  }
+  if (settings.enableAllProjectMcpServers === true) {
+    return { path: settingsPath, changed: false };
+  }
+  settings.enableAllProjectMcpServers = true;
+  const changed = writeJsonIfChanged(settingsPath, settings);
+  return { path: settingsPath, changed };
+}
+
+function secretConfigHome(env = process.env) {
+  return env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(os.homedir(), ".config");
+}
+
+function mcpTokenPath(serverId = DEFAULT_CLOUD_SERVER_ID, env = process.env) {
+  const override = env.ODAI_MCP_TOKEN_PATH;
+  if (override) return path.resolve(override);
+  return path.join(secretConfigHome(env), "secrets", "mcp", `${serverId}.token`);
+}
+
+function hasToken(filePath) {
+  try {
+    return fs.existsSync(filePath) && fs.statSync(filePath).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function writeTokenFile(filePath, tokenPayload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const payload = {
+    ...tokenPayload,
+    updated_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
+function writeMcpAuthTokenFromAccount(accessToken, options = {}) {
+  const clean = String(accessToken || "").trim();
+  if (!clean) throw new Error("0dai account access token required");
+  const tokenPath = options.tokenPath || mcpTokenPath(DEFAULT_CLOUD_SERVER_ID);
+  writeTokenFile(tokenPath, {
+    server_id: DEFAULT_CLOUD_SERVER_ID,
+    server_name: DEFAULT_CLOUD_SERVER_NAME,
+    mcp_host: options.host || DEFAULT_MCP_HOST,
+    token_type: "Bearer",
+    access_token: clean,
+    email: options.email || "",
+    plan: options.plan || "",
+    source: options.source || "0dai-account-token",
+  });
+  return { status: "written", tokenPath };
+}
+
+function base64Url(buffer) {
+  return Buffer.from(buffer).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function randomState() {
+  return base64Url(crypto.randomBytes(24));
+}
+
+function codeChallenge(verifier) {
+  return base64Url(crypto.createHash("sha256").update(verifier).digest());
+}
+
+function isInteractive() {
+  return !!(process.stdin && process.stdin.isTTY && process.stdout && process.stdout.isTTY);
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let command;
+  let args;
+  if (platform === "darwin") {
+    command = "open"; args = [url];
+  } else if (platform === "win32") {
+    command = "cmd"; args = ["/c", "start", "", url];
+  } else {
+    command = "xdg-open"; args = [url];
+  }
+  const result = spawnSync(command, args, { stdio: "ignore", timeout: 5000 });
+  return result.status === 0;
+}
+
+function requestJson(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const mod = parsed.protocol === "https:" ? https : http;
+    const body = options.body || null;
+    const req = mod.request({
+      method: options.method || (body ? "POST" : "GET"),
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      headers: {
+        "Accept": "application/json",
+        "User-Agent": "0dai-cli-mcp-auth",
+        ...(body ? {
+          "Content-Type": options.contentType || "application/x-www-form-urlencoded",
+          "Content-Length": Buffer.byteLength(body),
+        } : {}),
+        ...(options.headers || {}),
+      },
+      timeout: options.timeout || 15000,
+    }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const raw = Buffer.concat(chunks).toString("utf8");
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          reject(new Error(`HTTP ${res.statusCode}: ${raw.slice(0, 200)}`));
+          return;
+        }
+        try {
+          resolve(raw ? JSON.parse(raw) : {});
+        } catch (err) {
+          reject(new Error(`invalid JSON from ${url}: ${err.message}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy(new Error(`request timed out: ${url}`));
+    });
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+async function discoverOAuth(host) {
+  const candidates = [
+    `${host}/.well-known/oauth-authorization-server`,
+    `${host}/.well-known/oauth-authorization-server/mcp`,
+  ];
+  for (const url of candidates) {
+    try {
+      const meta = await requestJson(url, { timeout: 5000 });
+      if (meta && meta.authorization_endpoint && meta.token_endpoint) return meta;
+    } catch {}
+  }
+  return {
+    authorization_endpoint: `${host}/.well-known/oauth-authorize`,
+    token_endpoint: `${host}/.well-known/oauth-token`,
+  };
+}
+
+async function startCallbackServer(timeoutMs, expectedState) {
+  let codeResolve;
+  let codeReject;
+  const codePromise = new Promise((resolve, reject) => {
+    codeResolve = resolve;
+    codeReject = reject;
+  });
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || "/", "http://127.0.0.1");
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (state !== expectedState) {
+      res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("State mismatch. You can close this tab and rerun 0dai init --reset.");
+      return;
+    }
+    if (!code) {
+      res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("No OAuth code was returned.");
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("0dai MCP authentication complete. You can close this tab.");
+    codeResolve(code);
+  });
+  const port = await new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve(server.address().port));
+  });
+  setTimeout(() => codeReject(new Error("MCP OAuth timed out")), timeoutMs).unref();
+  return { server, port, codePromise };
+}
+
+async function exchangeCodeForToken(tokenEndpoint, params) {
+  const body = new URLSearchParams(params).toString();
+  return requestJson(tokenEndpoint, { method: "POST", body, timeout: 15000 });
+}
+
+async function runOAuthHandshake(options) {
+  const host = options.host || DEFAULT_MCP_HOST;
+  const state = randomState();
+  const verifier = base64Url(crypto.randomBytes(32));
+  const challenge = codeChallenge(verifier);
+  const callback = await startCallbackServer(options.timeoutMs || DEFAULT_TIMEOUT_MS, state);
+  const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
+
+  try {
+    const metadata = await discoverOAuth(host);
+    const authUrl = new URL(metadata.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", options.clientId || "0dai-cli");
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("resource", `${host}/mcp`);
+    if (options.scope) authUrl.searchParams.set("scope", options.scope);
+
+    if (typeof options.onAuthUrl === "function") options.onAuthUrl(authUrl.toString());
+    if (options.openBrowser !== false) {
+      const opened = openBrowser(authUrl.toString());
+      if (!opened && typeof options.onBrowserOpenFailed === "function") {
+        options.onBrowserOpenFailed(authUrl.toString());
+      }
+    }
+
+    const code = await callback.codePromise;
+    const token = await exchangeCodeForToken(metadata.token_endpoint, {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: options.clientId || "0dai-cli",
+      code_verifier: verifier,
+    });
+    return token;
+  } finally {
+    callback.server.close();
+  }
+}
+
+async function authenticateCloudMcp(options = {}) {
+  const tokenPath = options.tokenPath || mcpTokenPath(DEFAULT_CLOUD_SERVER_ID);
+  if (!options.reset && hasToken(tokenPath)) {
+    return { status: "preserved", tokenPath };
+  }
+  const envToken = process.env.ODAI_MCP_AUTH_TOKEN || process.env.CLAUDE_AI_0DAI_TOKEN;
+  if (envToken) {
+    writeTokenFile(tokenPath, {
+      server_id: DEFAULT_CLOUD_SERVER_ID,
+      server_name: DEFAULT_CLOUD_SERVER_NAME,
+      mcp_host: options.host || DEFAULT_MCP_HOST,
+      token_type: "Bearer",
+      access_token: envToken,
+      source: "env",
+    });
+    return { status: "written", tokenPath };
+  }
+  if (process.env.ODAI_MCP_AUTH_MOCK === "1") {
+    writeTokenFile(tokenPath, {
+      server_id: DEFAULT_CLOUD_SERVER_ID,
+      server_name: DEFAULT_CLOUD_SERVER_NAME,
+      mcp_host: options.host || DEFAULT_MCP_HOST,
+      token_type: "Bearer",
+      access_token: "mock-mcp-token",
+      source: "mock",
+    });
+    return { status: "written", tokenPath };
+  }
+  const token = await runOAuthHandshake(options);
+  const accessToken = token.access_token || token.token;
+  if (!accessToken) throw new Error("OAuth token response did not include access_token");
+  writeTokenFile(tokenPath, {
+    server_id: DEFAULT_CLOUD_SERVER_ID,
+    server_name: DEFAULT_CLOUD_SERVER_NAME,
+    mcp_host: options.host || DEFAULT_MCP_HOST,
+    ...token,
+  });
+  return { status: "written", tokenPath };
+}
+
+async function shouldAuthenticateCloud(args, options = {}) {
+  if (options.noAuth) return false;
+  if (process.env.ODAI_MCP_AUTH_TOKEN || process.env.CLAUDE_AI_0DAI_TOKEN || process.env.ODAI_MCP_AUTH_MOCK === "1") {
+    return true;
+  }
+  if (options.yes) return true;
+  if (!isInteractive()) return false;
+  try {
+    const prompts = require("@clack/prompts");
+    const answer = await prompts.confirm({
+      message: "Authenticate 0dai cloud MCP now?",
+      initialValue: true,
+    });
+    if (prompts.isCancel(answer)) return false;
+    return answer !== false;
+  } catch {
+    return true;
+  }
+}
+
+async function bootstrapMcp(target, args = [], logger = console.log) {
+  const options = parseMcpArgs(args);
+  const result = {
+    ok: true,
+    config: null,
+    settings: null,
+    auth: null,
+    warnings: [],
+  };
+
+  try {
+    result.config = ensureMcpConfig(target, { host: options.host, reset: options.reset });
+  } catch (err) {
+    result.ok = false;
+    result.warnings.push(err.message);
+    return result;
+  }
+
+  try {
+    result.settings = ensureClaudeSettings(target);
+  } catch (err) {
+    result.warnings.push(`Claude settings MCP enablement skipped: ${err.message}`);
+  }
+
+  const doAuth = await shouldAuthenticateCloud(args, { noAuth: options.noAuth, yes: options.yes });
+  if (!doAuth) {
+    result.auth = { status: options.noAuth ? "disabled" : "skipped", tokenPath: mcpTokenPath(DEFAULT_CLOUD_SERVER_ID) };
+    return result;
+  }
+
+  try {
+    if (logger) logger("Authenticating 0dai cloud MCP — browser will open");
+    result.auth = await authenticateCloudMcp({
+      host: options.host,
+      reset: options.reset,
+      timeoutMs: DEFAULT_TIMEOUT_MS,
+      onAuthUrl: (url) => {
+        if (logger) logger(`Open this URL if the browser does not launch: ${url}`);
+      },
+      onBrowserOpenFailed: () => {},
+    });
+  } catch (err) {
+    result.warnings.push(`cloud MCP auth skipped: ${err.message}`);
+    result.auth = { status: "failed", tokenPath: mcpTokenPath(DEFAULT_CLOUD_SERVER_ID), error: err.message };
+  }
+
+  return result;
+}
+
+module.exports = {
+  DEFAULT_MCP_HOST,
+  DEFAULT_CLOUD_SERVER_ID,
+  DEFAULT_CLOUD_SERVER_NAME,
+  authenticateCloudMcp,
+  bootstrapMcp,
+  ensureClaudeSettings,
+  ensureMcpConfig,
+  loadTemplate,
+  mcpTokenPath,
+  mergeMcpConfig,
+  normalizeMcpHost,
+  parseMcpArgs,
+  renderTemplate,
+  runOAuthHandshake,
+  writeMcpAuthTokenFromAccount,
+};

package/lib/utils/model_ratings.js

@@ -0,0 +1,77 @@
+/**
+ * Utilities for model table availability and footer rendering.
+ */
+"use strict";
+
+const { execFileSync } = require("child_process");
+const { SUPPORTED_CLIS } = require("./constants");
+
+function buildSupportedCliIndex(supportedClis = SUPPORTED_CLIS) {
+  const byName = new Map();
+  for (const cli of supportedClis) {
+    byName.set(cli.name, cli);
+  }
+  return byName;
+}
+
+function probeInstalledCliNames(supportedClis = SUPPORTED_CLIS, probe = execFileSync) {
+  const installed = new Set();
+  for (const cli of supportedClis) {
+    try {
+      probe(cli.bin, ["--version"], {
+        stdio: "ignore",
+      });
+      installed.add(cli.name);
+    } catch {}
+  }
+  return installed;
+}
+
+function summarizeModelAvailability(models, supportedClis = SUPPORTED_CLIS, installedCliNames = probeInstalledCliNames(supportedClis)) {
+  const supportedByName = buildSupportedCliIndex(supportedClis);
+  const referencedCliNames = [];
+  const seen = new Set();
+
+  for (const model of models) {
+    if (!model || typeof model.cli !== "string" || seen.has(model.cli)) continue;
+    seen.add(model.cli);
+    referencedCliNames.push(model.cli);
+  }
+
+  const installed = [];
+  const missing = [];
+  const unsupported = [];
+
+  for (const cliName of referencedCliNames) {
+    if (!supportedByName.has(cliName)) {
+      unsupported.push(cliName);
+      continue;
+    }
+    if (installedCliNames.has(cliName)) installed.push(cliName);
+    else missing.push(cliName);
+  }
+
+  return {
+    referencedCliNames,
+    installedCliNames: installed,
+    missingCliNames: missing,
+    unsupportedCliNames: unsupported,
+    totalModels: models.length,
+    availableModels: models.filter((model) => installedCliNames.has(model.cli)),
+  };
+}
+
+function formatAvailableFooter(summary, visibleCount) {
+  const installed = summary.installedCliNames.length ? summary.installedCliNames.join(", ") : "none";
+  const missing = summary.missingCliNames.length ? summary.missingCliNames.join(", ") : "none";
+  const unsupported = summary.unsupportedCliNames.length ? `; unsupported CLIs: ${summary.unsupportedCliNames.join(", ")}` : "";
+  const count = typeof visibleCount === "number" ? visibleCount : summary.availableModels.length;
+  return `--available: ${count} of ${summary.totalModels} models (installed CLIs: ${installed}; missing CLIs: ${missing}${unsupported})`;
+}
+
+module.exports = {
+  buildSupportedCliIndex,
+  probeInstalledCliNames,
+  summarizeModelAvailability,
+  formatAvailableFooter,
+};