@ramusriram/versus 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.2
+
+- Added demo GIF to README (cropped for cleaner display).
+- **UX improvement:** Added real-time progress status messages ("Reading local docs for curl...", "Querying gemini...") during comparisons.
+- Centralized default model names in `src/backends/defaults.js` for easier maintenance.
+
+## 0.1.1
+
+- Published to npm as `@ramusriram/versus`.
+- Added npm version, license, and Node.js version badges to README.
+- Added package metadata: `author`, `repository`, `homepage`, `bugs` fields.
+- Added CLI integration test with mock backend.
+
 ## 0.1.0
 
 Initial public release.

package/README.md

@@ -1,14 +1,19 @@
 # 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.
+[![npm version](https://img.shields.io/npm/v/@ramusriram/versus)](https://www.npmjs.com/package/@ramusriram/versus)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@ramusriram/versus)](https://nodejs.org/)
+[![CI](https://github.com/RamuSriram/versus-ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/RamuSriram/versus-ai-cli/actions/workflows/ci.yml)
 
-![CI](https://github.com/RamuSriram/versus-ai-cli/actions/workflows/ci.yml/badge.svg)
+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.
 
 ## Demo
 
+![versus demo](.github/assets/demo.gif)
+
 ```bash
-versus nano vim
-versus curl wget --backend gemini
+versus curl wget
+versus nano vim --backend gemini
 versus "git pull" "git fetch" --level beginner
 ```
 
@@ -41,8 +46,6 @@ Versus answers that in a structured way, using **local docs as grounding** so th
 npm install -g @ramusriram/versus
 ```
 
-> Note: this command will work after the first npm publish.
-
 Then run:
 
 ```bash

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@ramusriram/versus",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI-powered CLI to compare two Linux commands or concepts, grounded in local docs (man, --help, info).",
+  "author": "Ramu Sriram",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RamuSriram/versus-ai-cli.git"
+  },
+  "homepage": "https://github.com/RamuSriram/versus-ai-cli#readme",
+  "bugs": {
+    "url": "https://github.com/RamuSriram/versus-ai-cli/issues"
+  },
   "type": "module",
   "bin": {
     "versus": "bin/versus.js"
@@ -37,4 +46,4 @@
     "CHANGELOG.md",
     "LICENSE"
   ]
-}
+}

package/src/backends/defaults.js

@@ -0,0 +1,10 @@
+/**
+ * Default model names for each backend.
+ * Centralized here to avoid repetition and make updates easier.
+ */
+export const DEFAULT_MODELS = {
+    openai: "gpt-5.2",
+    gemini: "gemini-2.5-flash",
+    ollama: "llama3.2",
+    mock: "mock",
+};

package/src/backends/gemini.js

@@ -1,3 +1,5 @@
+import { DEFAULT_MODELS } from "./defaults.js";
+
 export async function generateGemini({ prompt, model, apiKey }) {
   const key = apiKey || process.env.GEMINI_API_KEY;
   if (!key) {
@@ -6,7 +8,7 @@ export async function generateGemini({ prompt, model, apiKey }) {
     throw err;
   }
 
-  const m = model || "gemini-2.5-flash";
+  const m = model || DEFAULT_MODELS.gemini;
   const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(m)}:generateContent`;
 
   let res;

package/src/backends/index.js

@@ -2,6 +2,7 @@ import { generateOpenAI } from "./openai.js";
 import { generateGemini } from "./gemini.js";
 import { generateOllama } from "./ollama.js";
 import { generateMock } from "./mock.js";
+import { DEFAULT_MODELS } from "./defaults.js";
 
 async function isOllamaUp(baseUrl) {
   const urlBase = baseUrl || process.env.OLLAMA_BASE_URL || "http://localhost:11434";
@@ -29,38 +30,39 @@ export async function generateText({ backend, prompt, model }) {
   if (want === "auto") {
     if (hasOpenAIKey()) {
       const text = await generateOpenAI({ prompt, model });
-      return { text, backendUsed: "openai", modelUsed: model || "gpt-5.2" };
+      return { text, backendUsed: "openai", modelUsed: model || DEFAULT_MODELS.openai };
     }
     if (hasGeminiKey()) {
       const text = await generateGemini({ prompt, model });
-      return { text, backendUsed: "gemini", modelUsed: model || "gemini-2.5-flash" };
+      return { text, backendUsed: "gemini", modelUsed: model || DEFAULT_MODELS.gemini };
     }
     if (await isOllamaUp()) {
       const text = await generateOllama({ prompt, model });
-      return { text, backendUsed: "ollama", modelUsed: model || "llama3.2" };
+      return { text, backendUsed: "ollama", modelUsed: model || DEFAULT_MODELS.ollama };
     }
     const text = await generateMock({ prompt });
-    return { text, backendUsed: "mock", modelUsed: "mock" };
+    return { text, backendUsed: "mock", modelUsed: DEFAULT_MODELS.mock };
   }
 
   if (want === "openai") {
     const text = await generateOpenAI({ prompt, model });
-    return { text, backendUsed: "openai", modelUsed: model || "gpt-5.2" };
+    return { text, backendUsed: "openai", modelUsed: model || DEFAULT_MODELS.openai };
   }
   if (want === "gemini") {
     const text = await generateGemini({ prompt, model });
-    return { text, backendUsed: "gemini", modelUsed: model || "gemini-2.5-flash" };
+    return { text, backendUsed: "gemini", modelUsed: model || DEFAULT_MODELS.gemini };
   }
   if (want === "ollama") {
     const text = await generateOllama({ prompt, model });
-    return { text, backendUsed: "ollama", modelUsed: model || "llama3.2" };
+    return { text, backendUsed: "ollama", modelUsed: model || DEFAULT_MODELS.ollama };
   }
   if (want === "mock") {
     const text = await generateMock({ prompt });
-    return { text, backendUsed: "mock", modelUsed: "mock" };
+    return { text, backendUsed: "mock", modelUsed: DEFAULT_MODELS.mock };
   }
 
   const err = new Error(`Unknown backend: ${want}`);
   err.hint = "Use --backend auto|openai|gemini|ollama|mock";
   throw err;
 }
+

package/src/backends/ollama.js

@@ -1,3 +1,5 @@
+import { DEFAULT_MODELS } from "./defaults.js";
+
 export async function generateOllama({ prompt, model, baseUrl }) {
   const urlBase = baseUrl || process.env.OLLAMA_BASE_URL || "http://localhost:11434";
   const url = `${urlBase.replace(/\/$/, "")}/api/generate`;
@@ -6,7 +8,7 @@ export async function generateOllama({ prompt, model, baseUrl }) {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
-      model: model || "llama3.2",
+      model: model || DEFAULT_MODELS.ollama,
       prompt,
       stream: false,
     }),

package/src/backends/openai.js

@@ -1,4 +1,5 @@
 import OpenAI from "openai";
+import { DEFAULT_MODELS } from "./defaults.js";
 
 export async function generateOpenAI({ prompt, model, apiKey, baseUrl }) {
   const key = apiKey || process.env.OPENAI_API_KEY;
@@ -15,7 +16,7 @@ export async function generateOpenAI({ prompt, model, apiKey, baseUrl }) {
 
   try {
     const response = await client.responses.create({
-      model: model || "gpt-5.2",
+      model: model || DEFAULT_MODELS.openai,
       input: prompt,
     });
 

package/src/cache.js

@@ -28,7 +28,7 @@ async function readCache() {
       const backup = file + ".corrupt";
       try {
         await fs.rename(file, backup);
-      } catch {}
+      } catch { }
       return { version: 1, entries: {} };
     }
     throw err;

package/src/cli.js

@@ -263,7 +263,12 @@ export async function main(argv) {
 
         if (shouldShowSpinner(options)) spinner = createSpinner({ text: "Comparing" });
 
-        const result = await runComparison(left, right, options);
+        // Status callback updates spinner text for real-time progress
+        const onStatus = (msg) => {
+          if (spinner) spinner.update(msg);
+        };
+
+        const result = await runComparison(left, right, options, onStatus);
 
         spinner?.stop();
 

package/src/engine.js

@@ -20,18 +20,22 @@ function computeCacheKey({ left, right, options, leftDocs, rightDocs }) {
   return sha256(JSON.stringify(payload));
 }
 
-export async function buildComparisonPrompt(left, right, options) {
+export async function buildComparisonPrompt(left, right, options, onStatus) {
   const includeDocs = options.includeDocs !== false;
+  const status = typeof onStatus === "function" ? onStatus : () => { };
 
-  const [leftInfo, rightInfo] = includeDocs
-    ? await Promise.all([
-        collectDocs(left, { maxChars: options.maxDocChars, debug: options.debug }),
-        collectDocs(right, { maxChars: options.maxDocChars, debug: options.debug }),
-      ])
-    : [
-        { docs: "", sources: [], skipped: "docs disabled" },
-        { docs: "", sources: [], skipped: "docs disabled" },
-      ];
+  let leftInfo, rightInfo;
+
+  if (includeDocs) {
+    status(`Reading local docs for ${left}`);
+    leftInfo = await collectDocs(left, { maxChars: options.maxDocChars, debug: options.debug });
+
+    status(`Reading local docs for ${right}`);
+    rightInfo = await collectDocs(right, { maxChars: options.maxDocChars, debug: options.debug });
+  } else {
+    leftInfo = { docs: "", sources: [], skipped: "docs disabled" };
+    rightInfo = { docs: "", sources: [], skipped: "docs disabled" };
+  }
 
   const leftDocs = leftInfo.docs || "";
   const rightDocs = rightInfo.docs || "";
@@ -48,13 +52,15 @@ export async function buildComparisonPrompt(left, right, options) {
   return { prompt, leftInfo, rightInfo, leftDocs, rightDocs };
 }
 
-export async function runComparison(left, right, options) {
+export async function runComparison(left, right, options, onStatus) {
   const t0 = hrtimeMs();
+  const status = typeof onStatus === "function" ? onStatus : () => { };
 
   const { prompt, leftInfo, rightInfo, leftDocs, rightDocs } = await buildComparisonPrompt(
     left,
     right,
-    options
+    options,
+    onStatus
   );
 
   const key = computeCacheKey({ left, right, options, leftDocs, rightDocs });
@@ -92,6 +98,10 @@ export async function runComparison(left, right, options) {
     }
   }
 
+  // Show which backend we're querying
+  const backendName = options.backend === "auto" ? "LLM" : options.backend;
+  status(`Querying ${backendName}`);
+
   const tLLM0 = hrtimeMs();
   const gen = await generateText({
     backend: options.backend,

package/src/introspect.js

@@ -30,13 +30,13 @@ function runCommand(cmd, args, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
     const killTimer =
       timeoutMs && timeoutMs > 0
         ? setTimeout(() => {
-            if (done) return;
-            done = true;
-            try {
-              child.kill("SIGKILL");
-            } catch {}
-            resolve({ ok: false, stdout, stderr, timedOut: true });
-          }, timeoutMs)
+          if (done) return;
+          done = true;
+          try {
+            child.kill("SIGKILL");
+          } catch { }
+          resolve({ ok: false, stdout, stderr, timedOut: true });
+        }, timeoutMs)
         : null;
 
     child.stdout.on("data", (d) => (stdout += d.toString("utf8")));

package/test/cli.test.js

@@ -0,0 +1,77 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const binPath = path.join(__dirname, "..", "bin", "versus.js");
+
+function runCLI(args, { timeout = 5000 } = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [binPath, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, NO_COLOR: "1" },
+        });
+
+        let stdout = "";
+        let stderr = "";
+        let done = false;
+
+        const timer = setTimeout(() => {
+            if (done) return;
+            done = true;
+            try {
+                child.kill("SIGKILL");
+            } catch { }
+            resolve({ stdout, stderr, code: null, timedOut: true });
+        }, timeout);
+
+        child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+        child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+
+        child.on("close", (code) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code, timedOut: false });
+        });
+
+        child.on("error", () => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code: 1, timedOut: false });
+        });
+    });
+}
+
+test("CLI --help exits 0 and shows usage", async () => {
+    const { stdout, code } = await runCLI(["--help"]);
+    assert.equal(code, 0);
+    assert.match(stdout, /versus/i);
+    assert.match(stdout, /Compare/i);
+});
+
+test("CLI --version exits 0 and shows version", async () => {
+    const { stdout, code } = await runCLI(["--version"]);
+    assert.equal(code, 0);
+    assert.match(stdout, /\d+\.\d+\.\d+/);
+});
+
+test("CLI runs comparison with mock backend", async () => {
+    const { stdout, code } = await runCLI(["curl", "wget", "--backend", "mock", "--no-cache"]);
+    assert.equal(code, 0);
+    assert.match(stdout, /curl vs wget/i);
+    assert.match(stdout, /mock/i);
+});
+
+test("CLI status command exits 0", async () => {
+    const { code } = await runCLI(["status"]);
+    assert.equal(code, 0);
+});
+
+test("CLI cache command exits 0", async () => {
+    const { code } = await runCLI(["cache"]);
+    assert.equal(code, 0);
+});