@ramusriram/versus 0.1.0

package/src/prompt.js

@@ -0,0 +1,57 @@
+export function buildPrompt({
+  left,
+  right,
+  leftDocs,
+  rightDocs,
+  level = "intermediate",
+  mode = "summary",
+}) {
+  const audience =
+    level === "beginner"
+      ? "Beginner (use simple language, minimal jargon, short explanations)."
+      : level === "advanced"
+        ? "Advanced (assume Linux comfort; include nuanced tradeoffs/perf details when relevant)."
+        : "Intermediate (developer-friendly; explain jargon once).";
+
+  const modeGuide =
+    mode === "cheatsheet"
+      ? "Include practical flags and a few example commands. Keep it under ~450 words."
+      : mode === "table"
+        ? "Prioritize a clear comparison table (4–8 rows) and keep other text short."
+        : "Keep it concise (under ~250 words).";
+
+  const docsNote =
+    leftDocs?.trim() || rightDocs?.trim()
+      ? "Use the provided docs as the most reliable source. If the docs are missing or unclear, say so and then use general knowledge."
+      : "No docs were provided; use general knowledge, but be explicit that you are not grounded in local docs.";
+
+  return [
+    "You are a Linux expert and a careful technical writer.",
+    "",
+    `Task: Compare "${left}" and "${right}" for a developer.`,
+    `Audience: ${audience}`,
+    `Mode: ${mode}. ${modeGuide}`,
+    "",
+    "Output format: Markdown.",
+    "Rules:",
+    `- ${docsNote}`,
+    "- Do NOT invent flags that look plausible. If you are unsure, say you are unsure.",
+    "- Avoid fluff. Be helpful and specific.",
+    "",
+    "Required structure:",
+    "1) One-line verdict",
+    "2) Short overview",
+    `3) When to use ${left}`,
+    `4) When to use ${right}`,
+    "5) Key differences table",
+    "6) Examples (2–3 per side) if you can do so safely",
+    "7) Common mistakes / gotchas",
+    "",
+    `--- DOCS: ${left} ---`,
+    leftDocs?.trim() ? leftDocs.trim() : "[no local docs found]",
+    "",
+    `--- DOCS: ${right} ---`,
+    rightDocs?.trim() ? rightDocs.trim() : "[no local docs found]",
+    "",
+  ].join("\n");
+}

package/src/status.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { getCacheInfo } from "./cache.js";
+import { pc } from "./util/style.js";
+
+function run(cmd, args, { timeoutMs = 1200 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+
+    let stdout = "";
+    let done = false;
+
+    const timer =
+      timeoutMs && timeoutMs > 0
+        ? setTimeout(() => {
+            if (done) return;
+            done = true;
+            try {
+              child.kill("SIGKILL");
+            } catch {}
+            resolve({ ok: false, stdout, timedOut: true });
+          }, timeoutMs)
+        : null;
+
+    child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+    child.on("error", () => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      resolve({ ok: false, stdout: "" });
+    });
+    child.on("close", (code) => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      resolve({ ok: code === 0, stdout });
+    });
+  });
+}
+
+async function checkMan() {
+  // man can return non-zero on some systems depending on pager, so we just check it outputs something.
+  const res = await run("man", ["-P", "cat", "ls"], { timeoutMs: 1500 });
+  return Boolean(res.stdout && res.stdout.length > 20);
+}
+
+async function checkOllama() {
+  const base = process.env.OLLAMA_BASE_URL || "http://localhost:11434";
+  const baseNoSlash = base.replace(/\/$/, "");
+  const versionUrl = `${baseNoSlash}/api/version`;
+  const tagsUrl = `${baseNoSlash}/api/tags`;
+
+  try {
+    const vRes = await fetch(versionUrl);
+    if (!vRes.ok) return { ok: false, base, reason: `HTTP ${vRes.status}` };
+    const v = await vRes.json().catch(() => ({}));
+
+    const tRes = await fetch(tagsUrl);
+    const tags = tRes.ok ? await tRes.json().catch(() => ({})) : {};
+    const models = Array.isArray(tags?.models)
+      ? tags.models.map((m) => m.name).slice(0, 10)
+      : [];
+
+    return { ok: true, base, version: v?.version, models };
+  } catch (e) {
+    return { ok: false, base, reason: "not reachable" };
+  }
+}
+
+export async function runStatus() {
+  const node = process.versions.node;
+  const major = Number(node.split(".")[0] || 0);
+  const nodeOk = major >= 20;
+
+  const manOk = await checkMan().catch(() => false);
+  const cacheInfo = await getCacheInfo();
+
+  const openaiKey = Boolean(process.env.OPENAI_API_KEY);
+  const geminiKey = Boolean(process.env.GEMINI_API_KEY);
+  const ollama = await checkOllama();
+
+  const ok = nodeOk && manOk;
+
+  const human = [];
+  human.push(pc.bold("versus status"));
+  human.push("");
+
+  human.push(`${nodeOk ? pc.green("✔") : pc.red("✖")} Node.js ${node} (need 20+)`);
+  human.push(`${manOk ? pc.green("✔") : pc.red("✖")} man pages available`);
+
+  human.push(`${pc.green("ℹ")} Cache file: ${cacheInfo.file}`);
+  human.push(`${pc.green("ℹ")} Cache entries: ${cacheInfo.entries}`);
+  human.push("");
+
+  human.push(pc.bold("Backends"));
+  human.push(`${openaiKey ? pc.green("✔") : pc.yellow("•")} OpenAI key ${openaiKey ? "set" : "not set"} (OPENAI_API_KEY)`);
+  human.push(`${geminiKey ? pc.green("✔") : pc.yellow("•")} Gemini key ${geminiKey ? "set" : "not set"} (GEMINI_API_KEY)`);
+  if (ollama.ok) {
+    const models = ollama.models?.length ? `models: ${ollama.models.join(", ")}` : "no models found (try: ollama pull llama3.2)";
+    human.push(`${pc.green("✔")} Ollama reachable at ${ollama.base} (${models})`);
+  } else {
+    human.push(`${pc.yellow("•")} Ollama not reachable at ${ollama.base}`);
+  }
+
+  human.push("");
+  human.push(pc.dim("Tip: set OPENAI_API_KEY or GEMINI_API_KEY, or run Ollama locally to get real answers."));
+
+  return {
+    ok,
+    checks: {
+      node: { ok: nodeOk, version: node, required: ">=20" },
+      man: { ok: manOk },
+      cache: cacheInfo,
+      backends: {
+        openai: { ok: openaiKey },
+        gemini: { ok: geminiKey },
+        ollama,
+      },
+    },
+    human,
+  };
+}
+
+
+// Backwards-compatible alias (older docs used `doctor`).
+export const runDoctor = runStatus;

package/src/util/argv.js

@@ -0,0 +1,16 @@
+// Small helpers for working with raw argv.
+// We deliberately support both "--flag value" and "--flag=value" styles.
+
+/**
+ * Returns true if any of the given flags appear in argv.
+ * Supports:
+ *   --flag
+ *   --flag=value
+ *   -f
+ *   -f=value
+ */
+export function hasAnyFlag(argv, flags) {
+  return flags.some((flag) =>
+    argv.some((arg) => arg === flag || arg.startsWith(`${flag}=`))
+  );
+}

package/src/util/markdown.js

@@ -0,0 +1,206 @@
+import { pc } from "./style.js";
+
+import { stripAnsi } from "./text.js";
+
+// IMPORTANT: do not capture styling functions at module load time.
+// `pc` is a live binding that can be reconfigured at runtime (e.g. `--color never`).
+const IDENTITY = (s) => s;
+const style = (name) => (s) => (typeof pc?.[name] === "function" ? pc[name](s) : IDENTITY(s));
+
+const bold = style("bold");
+const dim = style("dim");
+const underline = style("underline");
+const italic = style("italic");
+const cyan = style("cyan");
+
+// Inline code should be readable but not visually loud across themes.
+// Avoid inverse/background blocks (they can look harsh on dark themes).
+const codeSpan = (s) => dim(underline(s));
+
+function padAnsiRight(text, width) {
+  const len = stripAnsi(text).length;
+  if (len >= width) return text;
+  return text + " ".repeat(width - len);
+}
+
+function parseTableRow(line) {
+  let t = line.trim();
+  if (t.startsWith("|")) t = t.slice(1);
+  if (t.endsWith("|")) t = t.slice(0, -1);
+  return t.split("|").map((c) => c.trim());
+}
+
+function isTableSeparator(line) {
+  const t = line.trim();
+  if (!t.includes("|")) return false;
+  // Separator is mostly pipes, dashes, colons and spaces.
+  return /^[|:\-\s]+$/.test(t) && t.includes("-");
+}
+
+function renderInline(text) {
+  const input = String(text ?? "");
+
+  // Code spans: split on backticks and style odd segments.
+  const parts = input.split("`");
+  const out = parts.map((seg, idx) => {
+    if (idx % 2 === 1) return codeSpan(seg);
+
+    let s = seg;
+
+    // Links: [text](url) -> underlined text (keep url in dim parens)
+    s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, label, url) => {
+      const cleanLabel = String(label);
+      const cleanUrl = String(url);
+      return `${underline(cleanLabel)}${dim(` (${cleanUrl})`)}`;
+    });
+
+    // Bold: **text** or __text__
+    s = s.replace(/(\*\*|__)(.+?)\1/g, (_m, _d, inner) => bold(inner));
+
+    // Italic-ish: *text* or _text_ (avoid matching inside words too aggressively)
+    s = s.replace(/(^|[^\w])(\*|_)([^*_]+?)\2([^\w]|$)/g, (_m, pre, _d, inner, post) => {
+      // Many terminals render italics inconsistently. Underline is the safest emphasis.
+      return `${pre}${underline(inner)}${post}`;
+    });
+
+    return s;
+  });
+
+  return out.join("");
+}
+
+function renderTable(lines, startIdx) {
+  const header = parseTableRow(lines[startIdx]);
+  const rows = [header];
+
+  let i = startIdx + 2; // skip header + separator
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) break;
+    if (!line.includes("|")) break;
+    rows.push(parseTableRow(line));
+    i++;
+  }
+
+  const cols = Math.max(...rows.map((r) => r.length));
+  for (const r of rows) {
+    while (r.length < cols) r.push("");
+  }
+
+  // Pre-render cells so we can measure visible widths.
+  const rendered = rows.map((r, rowIdx) =>
+    r.map((c) => {
+      const cell = renderInline(c);
+      return rowIdx === 0 ? bold(cell) : cell;
+    })
+  );
+
+  const widths = new Array(cols).fill(0);
+  for (const r of rendered) {
+    r.forEach((cell, idx) => {
+      const w = stripAnsi(cell).length;
+      if (w > widths[idx]) widths[idx] = w;
+    });
+  }
+
+  const border = "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+";
+
+  const out = [];
+  out.push(border);
+  for (let rowIdx = 0; rowIdx < rendered.length; rowIdx++) {
+    const row = rendered[rowIdx];
+    const line =
+      "|" +
+      row
+        .map((cell, idx) => {
+          const padded = padAnsiRight(cell, widths[idx]);
+          return ` ${padded} `;
+        })
+        .join("|") +
+      "|";
+    out.push(line);
+    if (rowIdx === 0) out.push(border);
+  }
+  out.push(border);
+
+  return { renderedLines: out, nextIdx: i };
+}
+
+/**
+ * Render Markdown into a terminal-friendly string.
+ *
+ * If stdout is not a TTY, you should generally skip rendering and print raw Markdown.
+ */
+export function renderMarkdownToTerminal(markdown) {
+  const md = String(markdown ?? "");
+  const lines = md.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  const out = [];
+
+  let inCode = false;
+  for (let idx = 0; idx < lines.length; idx++) {
+    const line = lines[idx];
+    const trimmed = line.trim();
+
+    // Fenced code blocks
+    if (trimmed.startsWith("```")) {
+      inCode = !inCode;
+      out.push(dim(trimmed));
+      continue;
+    }
+
+    if (inCode) {
+      out.push(dim(line));
+      continue;
+    }
+
+    // Markdown tables
+    if (line.includes("|") && idx + 1 < lines.length && isTableSeparator(lines[idx + 1])) {
+      const table = renderTable(lines, idx);
+      out.push(...table.renderedLines);
+      idx = table.nextIdx - 1;
+      continue;
+    }
+
+    // Headings
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    if (h) {
+      const text = h[2].trim();
+      out.push(bold(cyan(text)));
+      continue;
+    }
+
+    // Horizontal rule
+    if (/^\s*([-*_])\1\1+\s*$/.test(trimmed)) {
+      out.push(dim("─".repeat(40)));
+      continue;
+    }
+
+    // Blockquote
+    const bq = line.match(/^\s*>\s?(.*)$/);
+    if (bq) {
+      out.push(dim(`│ ${bq[1]}`));
+      continue;
+    }
+
+    // Unordered list
+    const ul = line.match(/^(\s*)([-*+])\s+(.*)$/);
+    if (ul) {
+      const indent = ul[1] || "";
+      out.push(`${indent}• ${renderInline(ul[3])}`);
+      continue;
+    }
+
+    // Ordered list
+    const ol = line.match(/^(\s*)(\d+)\.\s+(.*)$/);
+    if (ol) {
+      const indent = ol[1] || "";
+      out.push(`${indent}${ol[2]}. ${renderInline(ol[3])}`);
+      continue;
+    }
+
+    // Regular line
+    out.push(renderInline(line));
+  }
+
+  return out.join("\n");
+}

package/src/util/sanitize.js

@@ -0,0 +1,28 @@
+const SAFE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._+:-]*$/;
+
+export function tokenizeTarget(target) {
+  return String(target).trim().split(/\s+/).filter(Boolean);
+}
+
+export function isSafeToken(token) {
+  // Disallow shell metacharacters, quotes, spaces, etc.
+  // Allow typical command names and subcommands: git, pull, docker-compose, ip, ss, etc.
+  return SAFE_TOKEN.test(token);
+}
+
+export function validateTargetForExec(target) {
+  const tokens = tokenizeTarget(target);
+  if (tokens.length === 0) {
+    return { ok: false, reason: "Empty target" };
+  }
+  if (!isSafeToken(tokens[0])) {
+    return { ok: false, reason: `Unsafe command token: "${tokens[0]}"` };
+  }
+  for (const t of tokens.slice(1)) {
+    // Allow subcommand tokens, but still keep them safe.
+    if (!isSafeToken(t)) {
+      return { ok: false, reason: `Unsafe token: "${t}"` };
+    }
+  }
+  return { ok: true, tokens };
+}

package/src/util/spinner.js

@@ -0,0 +1,47 @@
+// Tiny terminal spinner (animated dots) for long-running operations.
+// Writes to stderr so stdout stays clean for piping.
+
+export function createSpinner({ text = "Working", delayMs = 150, intervalMs = 120 } = {}) {
+  // Only show when stderr is a real TTY.
+  if (!process.stderr.isTTY) {
+    return {
+      update: () => {},
+      stop: () => {},
+    };
+  }
+
+  const frames = ["", ".", "..", "..."];
+  let frameIdx = 0;
+  let lastLen = 0;
+  let interval = null;
+  let started = false;
+
+  const writeFrame = () => {
+    const msg = `${text}${frames[frameIdx]}`;
+    frameIdx = (frameIdx + 1) % frames.length;
+
+    // Clear any leftover characters from longer previous frames.
+    const pad = lastLen > msg.length ? " ".repeat(lastLen - msg.length) : "";
+    lastLen = msg.length;
+    process.stderr.write(`\r${msg}${pad}`);
+  };
+
+  const timer = setTimeout(() => {
+    started = true;
+    writeFrame();
+    interval = setInterval(writeFrame, intervalMs);
+  }, delayMs);
+
+  return {
+    update(nextText) {
+      text = String(nextText ?? "");
+    },
+    stop() {
+      clearTimeout(timer);
+      if (interval) clearInterval(interval);
+      if (started) {
+        process.stderr.write(`\r${" ".repeat(lastLen)}\r`);
+      }
+    },
+  };
+}

package/src/util/style.js

@@ -0,0 +1,46 @@
+import picocolors from "picocolors";
+
+// Shared styling layer so we can honor `--color` and `NO_COLOR`
+// consistently across the CLI.
+//
+// `pc` is a live binding (reassigned by setColorMode). Other modules import it
+// and will automatically see the updated object.
+
+export let pc = picocolors;
+
+function normalizeMode(mode) {
+  const m = String(mode ?? "auto").trim().toLowerCase();
+  if (m === "always" || m === "on" || m === "true" || m === "1") return "always";
+  if (m === "never" || m === "off" || m === "false" || m === "0") return "never";
+  return "auto";
+}
+
+/**
+ * Configure ANSI color/styling.
+ *
+ * Supported modes:
+ * - auto: enable when attached to a TTY and NO_COLOR is not set
+ * - always: force-enable
+ * - never: force-disable
+ */
+export function setColorMode(mode, { stdoutIsTTY = process.stdout.isTTY, stderrIsTTY = process.stderr.isTTY } = {}) {
+  const m = normalizeMode(mode);
+
+  const noColorEnv = Object.prototype.hasOwnProperty.call(process.env, "NO_COLOR");
+  const forceColorEnv = process.env.FORCE_COLOR;
+  const isTTY = Boolean(stdoutIsTTY || stderrIsTTY);
+
+  let enabled;
+  if (m === "always") {
+    enabled = true;
+  } else if (m === "never") {
+    enabled = false;
+  } else {
+    // auto
+    enabled = isTTY && !noColorEnv && forceColorEnv !== "0";
+  }
+
+  // picocolors exposes createColors(enabled) which returns an object containing
+  // the same styling functions but conditionally enabled.
+  pc = typeof picocolors.createColors === "function" ? picocolors.createColors(enabled) : picocolors;
+}

package/src/util/text.js

@@ -0,0 +1,61 @@
+import crypto from "node:crypto";
+
+export function sha256(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+export function stripAnsi(text) {
+  // Basic ANSI escape stripping
+  return text.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "");
+}
+
+export function stripOverstrikes(text) {
+  // man pages often use overstrike/backspace formatting: "H\bH" or "_\bX".
+  // This removes any "char + backspace" sequences.
+  // Example: "m\ban" -> "an" (approx).
+  return text.replace(/.\x08/g, "");
+}
+
+export function normalizeText(text) {
+  let t = String(text ?? "");
+  t = t.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  t = stripAnsi(t);
+  t = stripOverstrikes(t);
+  // Collapse absurd whitespace while keeping newlines.
+  t = t.replace(/\n{3,}/g, "\n\n");
+  t = t.replace(/[ \t]{2,}/g, " ");
+  return t.trim();
+}
+
+export function truncate(text, maxChars) {
+  const t = String(text ?? "");
+  if (!Number.isFinite(maxChars) || maxChars <= 0) return "";
+  if (t.length <= maxChars) return t;
+  return t.slice(0, maxChars) + "\n\n[...truncated...]\n";
+}
+
+/**
+ * Truncate without chopping words in half (when possible).
+ *
+ * If we can't find a whitespace boundary (e.g. a very long token), we fall back
+ * to a hard character cut.
+ */
+export function truncateAtWordBoundary(text, maxChars, { suffix = "\n\n[...truncated...]\n" } = {}) {
+  const t = String(text ?? "");
+  if (!Number.isFinite(maxChars) || maxChars <= 0) return "";
+  if (t.length <= maxChars) return t;
+
+  // Look for a whitespace boundary near the cut point.
+  const window = t.slice(0, maxChars + 1);
+  const lastWs = Math.max(
+    window.lastIndexOf(" "),
+    window.lastIndexOf("\n"),
+    window.lastIndexOf("\t")
+  );
+
+  // If we found any whitespace boundary, prefer it to avoid chopping words.
+  const cut = lastWs >= 0 ? lastWs : maxChars;
+
+  return t.slice(0, cut).trimEnd() + suffix;
+}
+

package/src/util/time.js

@@ -0,0 +1,93 @@
+// Time formatting helpers for user-facing UX.
+
+function pad2(n) {
+  return String(n).padStart(2, "0");
+}
+
+function formatUtcOffsetLabel(date) {
+  // getTimezoneOffset() returns minutes behind UTC (e.g., IST => -330)
+  const offsetMin = -date.getTimezoneOffset();
+  const sign = offsetMin >= 0 ? "+" : "-";
+  const abs = Math.abs(offsetMin);
+  const hh = pad2(Math.floor(abs / 60));
+  const mm = pad2(abs % 60);
+  return `UTC${sign}${hh}:${mm}`;
+}
+
+function resolveTimeZoneLabel(date) {
+  // Best effort: try to get a friendly short name from Intl (e.g., IST, PST).
+  // If ICU data is limited, this may fall back to GMT offsets.
+  try {
+    const parts = new Intl.DateTimeFormat(undefined, { timeZoneName: "short" }).formatToParts(date);
+    const tzPart = parts.find((p) => p.type === "timeZoneName");
+    if (tzPart?.value) return tzPart.value;
+  } catch {
+    // ignore
+  }
+
+  // Special-case common one: Asia/Kolkata.
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (tz === "Asia/Kolkata" || tz === "Asia/Calcutta") return "IST";
+  } catch {
+    // ignore
+  }
+
+  return formatUtcOffsetLabel(date);
+}
+
+export function formatLocalDateTime(date) {
+  const base = new Intl.DateTimeFormat(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "2-digit",
+    hour: "numeric",
+    minute: "2-digit",
+  }).format(date);
+
+  const tz = resolveTimeZoneLabel(date);
+  return `${base} ${tz}`;
+}
+
+// A shorter local datetime intended for CLI metadata.
+// Omits the year when the timestamp is within the current year.
+export function formatLocalDateTimeShort(date, now = new Date()) {
+  const includeYear = date.getFullYear() !== now.getFullYear();
+
+  const opts = {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  };
+
+  if (includeYear) opts.year = "numeric";
+
+  const base = new Intl.DateTimeFormat(undefined, opts).format(date);
+  const tz = resolveTimeZoneLabel(date);
+  return `${base} ${tz}`;
+}
+
+export function formatRelativeTime(fromMs, toMs = Date.now()) {
+  const delta = Math.max(0, toMs - fromMs);
+
+  if (delta < 5_000) return "just now";
+
+  const sec = Math.floor(delta / 1000);
+  if (sec < 60) return `${sec}s ago`;
+
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+
+  const day = Math.floor(hr / 24);
+  if (day < 30) return `${day}d ago`;
+
+  const mo = Math.floor(day / 30);
+  if (mo < 12) return `${mo}mo ago`;
+
+  const yr = Math.floor(mo / 12);
+  return `${yr}y ago`;
+}

package/src/util/timing.js

@@ -0,0 +1,7 @@
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function hrtimeMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}