@ramusriram/versus 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+Initial public release.
+
+- Main compare command: `versus <left> <right>` (with backends: `auto|openai|gemini|ollama|mock`).
+- Markdown output is **rendered in the terminal by default** (TTY only) for readability.
+  - Use `--raw` or `--format markdown` to print raw Markdown.
+  - Use `--format json` for machine-readable output.
+- Added `versus prompt <left> <right>` to view the full generated LLM prompt (opens a pager by default; optional `--editor` / `--stdout`).
+- Improved mock backend prompt preview: truncates at word boundaries (no mid-word cuts) and points users to `versus prompt`.
+- CLI flag parsing supports both `--flag value` and `--flag=value` (e.g. `--backend=gemini`).
+- Added an animated loading indicator (spinner) for long operations.
+- Added a cached-response notice when output comes from the local cache.
+- Added `--color auto|always|never` (alias: `--no-color`) and improved terminal Markdown rendering for more consistent visuals across terminal themes.
+- Improved Gemini/OpenAI network error hints (includes a WSL DNS workaround for `fetch failed`).
+- Added GitHub Actions CI workflow running tests on Node 20/22.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# Versus CLI (`versus`)
+
+Compare two Linux commands or concepts (A vs B) from inside your terminal, grounded in your machine’s local documentation (man pages, `--help`, `info`) and summarized by an LLM backend.
+
+![CI](https://github.com/RamuSriram/versus-ai-cli/actions/workflows/ci.yml/badge.svg)
+
+## Demo
+
+```bash
+versus nano vim
+versus curl wget --backend gemini
+versus "git pull" "git fetch" --level beginner
+```
+
+## Why this exists
+
+When you’re learning Linux, you constantly ask:
+“What’s the difference between X and Y?”
+
+Versus answers that in a structured way, using **local docs as grounding** so the model is less likely to hallucinate.
+
+## Features
+
+* **Grounded comparisons** using `man`, `--help`, and `info` (best-effort)
+* **Multiple backends:** `gemini`, `openai`, `ollama`, `mock`
+* **Markdown rendering in terminal** by default (TTY). Use `--raw` for source markdown
+* **TTL cache** to reduce repeated API calls and speed up repeat runs
+* **Prompt inspection:** view the exact prompt without calling any backend
+* **CI (GitHub Actions)** runs tests on every push/PR
+
+## Requirements
+
+* Node.js 20+ (matches CI + `engines` in `package.json`)
+* Linux/WSL (macOS likely works too if `man` exists)
+
+## Install
+
+### From npm (recommended)
+
+```bash
+npm install -g @ramusriram/versus
+```
+
+> Note: this command will work after the first npm publish.
+
+Then run:
+
+```bash
+versus nano vim
+```
+
+### From source (for development)
+
+```bash
+git clone https://github.com/RamuSriram/versus-ai-cli.git
+cd versus-ai-cli
+npm install
+npm link
+```
+
+## Quickstart
+
+Backend selection (when `--backend auto`):
+
+* Uses **OpenAI** if `OPENAI_API_KEY` is set
+* Else uses **Gemini** if `GEMINI_API_KEY` is set
+* Else uses **Ollama** if it’s running locally
+* Else falls back to the **Mock** backend
+
+Run without API keys (force mock backend):
+
+```bash
+versus nano vim --backend mock
+```
+
+Gemini:
+
+```bash
+export GEMINI_API_KEY="your_key_here"
+versus nano vim --backend gemini
+```
+
+OpenAI:
+
+```bash
+export OPENAI_API_KEY="your_key_here"
+versus nano vim --backend openai
+```
+
+Ollama (local):
+
+```bash
+# install + run ollama first
+versus nano vim --backend ollama --model llama3
+```
+
+## Usage
+
+```bash
+versus <left> <right> [options]
+```
+
+Common options:
+
+* `-b, --backend <backend>`: `auto|openai|gemini|ollama|mock`
+* `-m, --model <model>`: provider-specific model name
+* `--level <level>`: `beginner|intermediate|advanced`
+* `--mode <mode>`: `summary|cheatsheet|table`
+* `--format <format>`: `rendered|markdown|json`
+* `--raw`: output raw Markdown (disable terminal rendering)
+* `--color <mode>`: `auto|always|never` (alias: `--no-color`, also respects `NO_COLOR=1`)
+* `--no-cache`: bypass cache
+* `--ttl-hours <n>`: cache TTL in hours (default: `720` = 30 days)
+* `--max-doc-chars <n>`: max local docs characters per side
+* `--no-docs`: don’t read local docs (LLM general knowledge only)
+* `-d, --debug`: debug metadata
+
+Tip: flags can be passed as `--backend gemini` or `--backend=gemini`.
+
+## Helpful subcommands
+
+### `versus status` (alias: `versus doctor`)
+
+Checks your environment (Node, `man`, cache path) and backend configuration.
+
+```bash
+versus status
+versus doctor
+```
+
+### `versus cache`
+
+Inspect or clear your local cache:
+
+```bash
+versus cache
+versus cache --clear
+```
+
+### `versus prompt`
+
+View the full prompt that would be sent to the backend (no API call).
+Opens in a pager by default to avoid dumping huge text.
+
+```bash
+versus prompt nano vim
+```
+
+Other modes:
+
+```bash
+versus prompt nano vim --stdout
+versus prompt nano vim --editor
+versus prompt nano vim --output prompt.txt
+```
+
+## Configuration
+
+Optional config file locations (first found wins):
+
+* `${XDG_CONFIG_HOME:-~/.config}/versus/config.json`
+* `~/.versusrc.json`
+
+Example:
+
+```json
+{
+  "backend": "gemini",
+  "model": "gemini-2.5-flash",
+  "level": "intermediate",
+  "mode": "summary",
+  "ttlHours": 720,
+  "maxDocChars": 6000
+}
+```
+
+## Caching
+
+Cache file:
+
+* `~/.cache/versus/cache.json`
+
+Use `--no-cache` to force a fresh response.
+
+## Privacy / Data
+
+Versus sends your inputs (and, by default, any collected local docs like `man`/`--help`/`info`) to the selected backend.
+
+* Want **zero network calls**: use `--backend mock`
+* Want **no local docs included**: use `--no-docs`
+
+## Troubleshooting
+
+### WSL: `Error: fetch failed`
+
+Some WSL setups prefer IPv6 DNS and can cause fetch failures.
+
+```bash
+export NODE_OPTIONS="--dns-result-order=ipv4first"
+```
+
+## Development
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/bin/versus.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv).catch((err) => {
+  // Last-resort crash handler. Most errors are handled inside CLI.
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ramusriram/versus",
+  "version": "0.1.0",
+  "description": "AI-powered CLI to compare two Linux commands or concepts, grounded in local docs (man, --help, info).",
+  "type": "module",
+  "bin": {
+    "versus": "bin/versus.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node ./bin/versus.js --help",
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "openai": "^6.8.0",
+    "picocolors": "^1.1.0"
+  },
+  "keywords": [
+    "cli",
+    "linux",
+    "man",
+    "ai",
+    "llm",
+    "compare",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "test",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}

package/src/backends/gemini.js

@@ -0,0 +1,57 @@
+export async function generateGemini({ prompt, model, apiKey }) {
+  const key = apiKey || process.env.GEMINI_API_KEY;
+  if (!key) {
+    const err = new Error("GEMINI_API_KEY is not set.");
+    err.hint = 'Export your API key: export GEMINI_API_KEY="..."';
+    throw err;
+  }
+
+  const m = model || "gemini-2.5-flash";
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(m)}:generateContent`;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-goog-api-key": key,
+      },
+      body: JSON.stringify({
+        contents: [
+          {
+            role: "user",
+            parts: [{ text: prompt }],
+          },
+        ],
+      }),
+    });
+  } catch {
+    const err = new Error("Failed to reach Gemini API (network error).");
+    err.hint =
+      "Check your internet connection and DNS.\n" +
+      "If you're on WSL and see 'fetch failed', try:\n" +
+      '  export NODE_OPTIONS="--dns-result-order=ipv4first"';
+    throw err;
+  }
+
+  const data = await res.json().catch(() => ({}));
+
+  if (!res.ok) {
+    const msg =
+      data?.error?.message ||
+      data?.message ||
+      (typeof data === "string" ? data : "") ||
+      `HTTP ${res.status}`;
+
+    const err = new Error(`Gemini error: ${msg}`);
+    err.hint =
+      `Check that your model name is valid (e.g. ${m}) and that GEMINI_API_KEY is correct.`;
+    throw err;
+  }
+
+  const parts = data?.candidates?.[0]?.content?.parts;
+  const text = Array.isArray(parts) ? parts.map((p) => p.text || "").join("") : "";
+
+  return String(text).trim();
+}

package/src/backends/index.js

@@ -0,0 +1,66 @@
+import { generateOpenAI } from "./openai.js";
+import { generateGemini } from "./gemini.js";
+import { generateOllama } from "./ollama.js";
+import { generateMock } from "./mock.js";
+
+async function isOllamaUp(baseUrl) {
+  const urlBase = baseUrl || process.env.OLLAMA_BASE_URL || "http://localhost:11434";
+  const url = `${urlBase.replace(/\/$/, "")}/api/version`;
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasOpenAIKey() {
+  return Boolean(process.env.OPENAI_API_KEY);
+}
+
+function hasGeminiKey() {
+  return Boolean(process.env.GEMINI_API_KEY);
+}
+
+export async function generateText({ backend, prompt, model }) {
+  const want = backend || "auto";
+
+  if (want === "auto") {
+    if (hasOpenAIKey()) {
+      const text = await generateOpenAI({ prompt, model });
+      return { text, backendUsed: "openai", modelUsed: model || "gpt-5.2" };
+    }
+    if (hasGeminiKey()) {
+      const text = await generateGemini({ prompt, model });
+      return { text, backendUsed: "gemini", modelUsed: model || "gemini-2.5-flash" };
+    }
+    if (await isOllamaUp()) {
+      const text = await generateOllama({ prompt, model });
+      return { text, backendUsed: "ollama", modelUsed: model || "llama3.2" };
+    }
+    const text = await generateMock({ prompt });
+    return { text, backendUsed: "mock", modelUsed: "mock" };
+  }
+
+  if (want === "openai") {
+    const text = await generateOpenAI({ prompt, model });
+    return { text, backendUsed: "openai", modelUsed: model || "gpt-5.2" };
+  }
+  if (want === "gemini") {
+    const text = await generateGemini({ prompt, model });
+    return { text, backendUsed: "gemini", modelUsed: model || "gemini-2.5-flash" };
+  }
+  if (want === "ollama") {
+    const text = await generateOllama({ prompt, model });
+    return { text, backendUsed: "ollama", modelUsed: model || "llama3.2" };
+  }
+  if (want === "mock") {
+    const text = await generateMock({ prompt });
+    return { text, backendUsed: "mock", modelUsed: "mock" };
+  }
+
+  const err = new Error(`Unknown backend: ${want}`);
+  err.hint = "Use --backend auto|openai|gemini|ollama|mock";
+  throw err;
+}

package/src/backends/mock.js

@@ -0,0 +1,23 @@
+import { truncateAtWordBoundary } from "../util/text.js";
+
+export async function generateMock({ prompt }) {
+  const maxPreviewChars = 900;
+  const preview = truncateAtWordBoundary(prompt, maxPreviewChars);
+  const wasTruncated = String(prompt ?? "").length > maxPreviewChars;
+
+  return [
+    "Mock backend selected.",
+    "",
+    "Set one of:",
+    "- OPENAI_API_KEY (and use --backend=openai)",
+    "- GEMINI_API_KEY (and use --backend=gemini)",
+    "- Install Ollama (and use --backend=ollama)",
+    "",
+    `Prompt preview${wasTruncated ? " (truncated)" : ""}:`,
+    preview,
+    "",
+    "Tip: view the full prompt with:",
+    "  versus prompt <left> <right>          # opens in a pager",
+    "  versus prompt --stdout <left> <right> # print to stdout",
+  ].join("\n");
+}

package/src/backends/ollama.js

@@ -0,0 +1,29 @@
+export async function generateOllama({ prompt, model, baseUrl }) {
+  const urlBase = baseUrl || process.env.OLLAMA_BASE_URL || "http://localhost:11434";
+  const url = `${urlBase.replace(/\/$/, "")}/api/generate`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: model || "llama3.2",
+      prompt,
+      stream: false,
+    }),
+  }).catch((e) => {
+    const err = new Error(`Failed to reach Ollama at ${urlBase}`);
+    err.hint = "Start Ollama and make sure the API is reachable on http://localhost:11434";
+    throw err;
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    const err = new Error(`Ollama error (${res.status}): ${body.slice(0, 200)}`);
+    err.hint = "Check that the model is installed: ollama pull llama3.2";
+    throw err;
+  }
+
+  const data = await res.json();
+  const text = data?.response ?? "";
+  return String(text).trim();
+}

package/src/backends/openai.js

@@ -0,0 +1,40 @@
+import OpenAI from "openai";
+
+export async function generateOpenAI({ prompt, model, apiKey, baseUrl }) {
+  const key = apiKey || process.env.OPENAI_API_KEY;
+  if (!key) {
+    const err = new Error("OPENAI_API_KEY is not set.");
+    err.hint = 'Export your API key: export OPENAI_API_KEY="..."';
+    throw err;
+  }
+
+  const client = new OpenAI({
+    apiKey: key,
+    baseURL: baseUrl || process.env.OPENAI_BASE_URL,
+  });
+
+  try {
+    const response = await client.responses.create({
+      model: model || "gpt-5.2",
+      input: prompt,
+    });
+
+    const text = response?.output_text ?? "";
+    return String(text).trim();
+  } catch (e) {
+    const msg = e?.message || String(e);
+    const err = new Error(`OpenAI request failed: ${msg}`);
+
+    const lower = String(msg).toLowerCase();
+    if (lower.includes("fetch failed")) {
+      err.hint =
+        "Check your internet connection and DNS.\n" +
+        "If you're on WSL and see 'fetch failed', try:\n" +
+        '  export NODE_OPTIONS="--dns-result-order=ipv4first"';
+    } else if (lower.includes("401") || lower.includes("unauthorized")) {
+      err.hint = "Check that OPENAI_API_KEY is valid.";
+    }
+
+    throw err;
+  }
+}

package/src/cache.js

@@ -0,0 +1,82 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+function cacheFilePath() {
+  const home = os.homedir();
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg ? xdg : path.join(home, ".cache");
+  return path.join(base, "versus", "cache.json");
+}
+
+async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function readCache() {
+  const file = cacheFilePath();
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object") return { version: 1, entries: {} };
+    if (!data.entries || typeof data.entries !== "object") data.entries = {};
+    return data;
+  } catch (err) {
+    if (err?.code === "ENOENT") return { version: 1, entries: {} };
+    // If corrupted, keep a backup and start fresh.
+    if (err instanceof SyntaxError) {
+      const backup = file + ".corrupt";
+      try {
+        await fs.rename(file, backup);
+      } catch {}
+      return { version: 1, entries: {} };
+    }
+    throw err;
+  }
+}
+
+async function writeCache(data) {
+  const file = cacheFilePath();
+  const dir = path.dirname(file);
+  await ensureDir(dir);
+  await fs.writeFile(file, JSON.stringify(data, null, 2), "utf8");
+}
+
+export async function getCacheInfo() {
+  const file = cacheFilePath();
+  const data = await readCache();
+  const entries = Object.keys(data.entries || {}).length;
+  return { file, entries };
+}
+
+export async function cacheGet(key) {
+  const data = await readCache();
+  const entry = data.entries?.[key];
+  if (!entry) return null;
+
+  if (entry.expiresAt) {
+    const exp = Date.parse(entry.expiresAt);
+    if (Number.isFinite(exp) && Date.now() > exp) {
+      // expired: delete
+      delete data.entries[key];
+      await writeCache(data);
+      return null;
+    }
+  }
+
+  return entry;
+}
+
+export async function cacheSet(key, entry) {
+  const data = await readCache();
+  data.entries[key] = entry;
+  await writeCache(data);
+}
+
+export async function clearCache() {
+  const data = await readCache();
+  const count = Object.keys(data.entries || {}).length;
+  data.entries = {};
+  await writeCache(data);
+  return count;
+}