@ramusriram/versus 0.1.0

package/src/cli.js

@@ -0,0 +1,341 @@
+import { Command } from "commander";
+import { createRequire } from "module";
+
+import { runComparison, buildComparisonPrompt } from "./engine.js";
+import { runStatus } from "./status.js";
+import { clearCache, getCacheInfo } from "./cache.js";
+import { loadUserConfig } from "./config.js";
+import { hasAnyFlag } from "./util/argv.js";
+import { createSpinner } from "./util/spinner.js";
+import { editText, pageText, writeTextFile } from "./util/view.js";
+import { renderMarkdownToTerminal } from "./util/markdown.js";
+import { formatLocalDateTime, formatLocalDateTimeShort, formatRelativeTime } from "./util/time.js";
+import { pc, setColorMode } from "./util/style.js";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+function toInt(value, fallback) {
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function normalizeFormat(value) {
+  const v = String(value ?? "").trim().toLowerCase();
+  if (!v) return "rendered";
+  if (v === "rendered" || v === "pretty" || v === "plain") return "rendered";
+  if (v === "markdown" || v === "md" || v === "raw") return "markdown";
+  if (v === "json") return "json";
+  return v;
+}
+
+function normalizeOptions(raw, config, argv) {
+  const defaults = {
+    backend: "auto",
+    model: undefined,
+    level: "intermediate",
+    mode: "summary",
+    format: "rendered",
+    cache: true,
+    ttlHours: 720,
+    maxDocChars: 6000,
+    includeDocs: true,
+    debug: false,
+  };
+
+  // Start with hard defaults, then config, then CLI overrides (only when explicitly provided)
+  const merged = { ...defaults, ...(config || {}) };
+
+  // Explicit CLI overrides (only if user actually typed the flag)
+  if (hasAnyFlag(argv, ["-b", "--backend"])) merged.backend = raw.backend;
+  if (hasAnyFlag(argv, ["-m", "--model"])) merged.model = raw.model;
+
+  if (hasAnyFlag(argv, ["--level"])) merged.level = raw.level;
+  if (hasAnyFlag(argv, ["--mode"])) merged.mode = raw.mode;
+  if (hasAnyFlag(argv, ["--format"])) merged.format = normalizeFormat(raw.format);
+  if (hasAnyFlag(argv, ["--raw"])) merged.format = "markdown";
+
+  if (hasAnyFlag(argv, ["--ttl-hours"])) merged.ttlHours = toInt(raw.ttlHours, merged.ttlHours);
+  if (hasAnyFlag(argv, ["--max-doc-chars"])) merged.maxDocChars = toInt(raw.maxDocChars, merged.maxDocChars);
+
+  if (hasAnyFlag(argv, ["--no-cache"])) merged.cache = false;
+  if (hasAnyFlag(argv, ["--no-docs"])) merged.includeDocs = false;
+
+  if (hasAnyFlag(argv, ["-d", "--debug"])) merged.debug = true;
+
+  // Normalize numeric types
+  merged.ttlHours = toInt(merged.ttlHours, defaults.ttlHours);
+  merged.maxDocChars = toInt(merged.maxDocChars, defaults.maxDocChars);
+
+  merged.format = normalizeFormat(merged.format);
+
+  return merged;
+}
+
+function printError(err) {
+  const msg = err?.message || String(err);
+  console.error(pc.red("Error:"), msg);
+  if (err?.hint) console.error(pc.dim(err.hint));
+  if (process.env.VERSUS_DEBUG_STACK === "1" && err?.stack) {
+    console.error(pc.dim(err.stack));
+  }
+}
+
+function printHeader(left, right) {
+  const title = pc.bold(pc.cyan(`${left} vs ${right}`));
+  console.log(title);
+  console.log(pc.dim("─".repeat(Math.min(60, Math.max(10, title.length)))));
+}
+
+function shouldShowSpinner(options) {
+  // Keep JSON output super clean.
+  if (options.format === "json") return false;
+
+  // Mock backend is basically instant; avoid flicker.
+  if (options.backend === "mock") return false;
+
+  return Boolean(process.stderr.isTTY);
+}
+
+function normalizeArgvForColor(args) {
+  // Commander does not know about `--no-color` when `--color <mode>` is used.
+  // We treat it as an alias for `--color=never`.
+  return args.map((a) => (a === "--no-color" ? "--color=never" : a));
+}
+
+function extractColorMode(args) {
+  // Last occurrence wins.
+  for (let i = args.length - 1; i >= 0; i--) {
+    const a = args[i];
+    if (a === "--color" && i + 1 < args.length) return args[i + 1];
+    if (a.startsWith("--color=")) return a.slice("--color=".length);
+  }
+  return "auto";
+}
+
+export async function main(argv) {
+  const rawArgv = normalizeArgvForColor(argv.slice(2));
+  setColorMode(extractColorMode(rawArgv));
+
+  const program = new Command();
+  const argvForCommander = [...argv.slice(0, 2), ...rawArgv];
+
+  program
+    .name("versus")
+    .description("Compare two Linux commands or concepts using an LLM, grounded in local docs.")
+    .version(pkg.version)
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+
+  program.addHelpText(
+    "after",
+    `\nExamples:\n  versus nano vim\n  versus curl wget --backend gemini\n  versus "git pull" "git fetch" --level beginner\n\nUseful commands:\n  versus status            # environment / backend checks (alias: doctor)\n  versus cache --clear     # clear cached responses\n  versus prompt nano vim   # view the full generated prompt in a pager\n\nOutput tips:\n  By default, versus renders Markdown for readability (TTY only).\n  Use --raw (or --format markdown) to print raw Markdown.\n  Control ANSI styling with --color auto|always|never (or set NO_COLOR=1).\n  Alias: --no-color is the same as --color=never.\n\nTip: flags can be passed as --backend gemini OR --backend=gemini.\n`
+  );
+
+  program
+    .command("status")
+    .alias("doctor")
+    .description("Check environment (Node, man, cache path, and optional LLM backends).")
+    .option("--color <mode>", "ANSI styling: auto|always|never", "auto")
+    .option("--json", "output machine-readable JSON")
+    .action(async (opts) => {
+      try {
+        const report = await runStatus();
+        if (opts.json) {
+          console.log(JSON.stringify(report, null, 2));
+          return;
+        }
+        for (const line of report.human) console.log(line);
+      } catch (err) {
+        printError(err);
+        process.exitCode = 1;
+      }
+    });
+
+  program
+    .command("cache")
+    .description("Inspect or clear the local cache.")
+    .option("--color <mode>", "ANSI styling: auto|always|never", "auto")
+    .option("--clear", "delete all cache entries")
+    .option("--json", "output machine-readable JSON")
+    .action(async (opts) => {
+      try {
+        if (opts.clear) {
+          const cleared = await clearCache();
+          if (opts.json) {
+            console.log(JSON.stringify({ cleared }, null, 2));
+          } else {
+            console.log(pc.green(`Cleared ${cleared} cache entr${cleared === 1 ? "y" : "ies"}.`));
+          }
+          return;
+        }
+
+        const info = await getCacheInfo();
+        if (opts.json) {
+          console.log(JSON.stringify(info, null, 2));
+        } else {
+          console.log(pc.bold("Cache"));
+          console.log(`File: ${info.file}`);
+          console.log(`Entries: ${info.entries}`);
+          console.log(pc.dim("Tip: run `versus cache --clear` to delete all entries."));
+        }
+      } catch (err) {
+        printError(err);
+        process.exitCode = 1;
+      }
+    });
+
+  program
+    .command("prompt")
+    .description("Generate the full LLM prompt for a comparison (no backend call).")
+    .argument("<left>", "first command or concept")
+    .argument("<right>", "second command or concept")
+    .option("--color <mode>", "ANSI styling: auto|always|never", "auto")
+    .option("--level <level>", "beginner|intermediate|advanced", "intermediate")
+    .option("--mode <mode>", "summary|cheatsheet|table", "summary")
+    .option("--max-doc-chars <n>", "max characters of local docs to include per side", "6000")
+    .option("--no-docs", "do not read local docs")
+    .option("--stdout", "print prompt to stdout instead of opening a pager/editor")
+    .option("--editor", "open prompt in $EDITOR (fallback: nano)")
+    .option("--output <file>", "write prompt to a file")
+    .option("-d, --debug", "print debug metadata (doc sources, etc.)")
+    .action(async (left, right, opts) => {
+      const spinner = createSpinner({ text: "Building prompt" });
+      try {
+        const config = await loadUserConfig();
+        const options = normalizeOptions(opts, config, rawArgv);
+
+        const { prompt, leftInfo, rightInfo } = await buildComparisonPrompt(left, right, options);
+
+        spinner.stop();
+
+        if (opts.output) {
+          await writeTextFile(opts.output, prompt);
+        }
+
+        if (opts.stdout) {
+          process.stdout.write(prompt);
+          if (!prompt.endsWith("\n")) process.stdout.write("\n");
+        } else if (opts.editor) {
+          await editText(prompt, {
+            filePath: opts.output,
+            keepFile: Boolean(opts.output),
+          });
+        } else {
+          await pageText(prompt);
+        }
+
+        if (options.debug) {
+          const meta = {
+            sources: { left: leftInfo.sources, right: rightInfo.sources },
+            skipped: { left: leftInfo.skipped, right: rightInfo.skipped },
+          };
+          console.error(pc.dim("\nDebug"));
+          console.error(pc.dim(JSON.stringify(meta, null, 2)));
+        }
+      } catch (err) {
+        spinner.stop();
+        printError(err);
+        process.exitCode = 1;
+      }
+    });
+
+  program
+    .argument("<left>", "first command or concept")
+    .argument("<right>", "second command or concept")
+    .option("--color <mode>", "ANSI styling: auto|always|never", "auto")
+    .option("-b, --backend <backend>", "auto|openai|gemini|ollama|mock", "auto")
+    .option("-m, --model <model>", "model name (provider-specific)")
+    .option("--level <level>", "beginner|intermediate|advanced", "intermediate")
+    .option("--mode <mode>", "summary|cheatsheet|table", "summary")
+    .option("--format <format>", "rendered|markdown|json", "rendered")
+    .option("--raw", "output raw Markdown (disable terminal rendering)")
+    .option("--no-cache", "disable cache")
+    .option("--ttl-hours <n>", "cache TTL in hours (default: 720 = 30 days)")
+    .option("--max-doc-chars <n>", "max characters of local docs to include per side")
+    .option("--no-docs", "do not read local docs (LLM general knowledge only)")
+    .option("-d, --debug", "print debug metadata (timings, doc sources, cache)")
+    .action(async (left, right, opts) => {
+      let spinner = null;
+      try {
+        const config = await loadUserConfig();
+        const options = normalizeOptions(opts, config, rawArgv);
+
+        if (shouldShowSpinner(options)) spinner = createSpinner({ text: "Comparing" });
+
+        const result = await runComparison(left, right, options);
+
+        spinner?.stop();
+
+        if (options.format === "json") {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        printHeader(left, right);
+
+        // Small, helpful metadata (kept subtle).
+        const backendLine = `Backend: ${result.backend}${result.model ? ` (model: ${result.model})` : ""}`;
+        console.log(pc.dim(backendLine));
+
+        if (result.cached) {
+          if (result.createdAt) {
+            const dt = new Date(result.createdAt);
+            const nowMs = Date.now();
+            const ageMs = Math.max(0, nowMs - dt.getTime());
+            const rel = formatRelativeTime(dt.getTime(), nowMs);
+
+            // UX rule: show relative age when it's recent (actionable), otherwise show local absolute time.
+            // < 60m  => "Cached (3m ago)"
+            // >= 60m => "Cached from Dec 28, 3:43 PM IST"
+            if (ageMs < 60 * 60 * 1000) {
+              console.log(pc.dim(`ℹ Cached (${rel}). Use --no-cache to refresh.`));
+            } else {
+              const localShort = formatLocalDateTimeShort(dt, new Date(nowMs));
+              console.log(pc.dim(`ℹ Cached from ${localShort}. Use --no-cache to refresh.`));
+            }
+
+            if (options.debug) {
+              const localFull = formatLocalDateTime(dt);
+              console.log(pc.dim(`  (cache createdAt: local=${localFull}, relative=${rel}, utc/iso=${result.createdAt})`));
+            }
+          } else {
+            console.log(pc.dim("ℹ Cached response. Use --no-cache to refresh."));
+          }
+        }
+
+        console.log("");
+
+        const raw = result.text.trim();
+        let out = raw;
+
+        const shouldRender = options.format === "rendered" && Boolean(process.stdout.isTTY);
+
+        if (shouldRender) {
+          try {
+            out = renderMarkdownToTerminal(raw);
+          } catch (e) {
+            // Graceful fallback to raw markdown.
+            out = raw;
+            if (options.debug) {
+              console.error(pc.dim("(markdown render failed; falling back to raw)"));
+            }
+          }
+        }
+
+        console.log(out);
+        console.log("");
+
+        if (options.debug) {
+          console.log(pc.dim("Debug"));
+          console.log(pc.dim(JSON.stringify(result.meta, null, 2)));
+        }
+      } catch (err) {
+        spinner?.stop();
+        printError(err);
+        process.exitCode = 1;
+      }
+    });
+
+  await program.parseAsync(argvForCommander);
+}

package/src/config.js

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+function configPaths() {
+  const home = os.homedir();
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg ? xdg : path.join(home, ".config");
+  return [
+    path.join(base, "versus", "config.json"),
+    path.join(home, ".versusrc.json"),
+  ];
+}
+
+export async function loadUserConfig() {
+  const paths = configPaths();
+  for (const p of paths) {
+    try {
+      const raw = await fs.readFile(p, "utf8");
+      const data = JSON.parse(raw);
+      if (data && typeof data === "object") return data;
+    } catch (err) {
+      if (err?.code === "ENOENT") continue;
+      const e = new Error(`Failed to read config file: ${p}`);
+      e.hint = "Fix the JSON syntax or delete the config file to use defaults.";
+      throw e;
+    }
+  }
+  return {};
+}

package/src/engine.js

@@ -0,0 +1,143 @@
+import { collectDocs } from "./introspect.js";
+import { buildPrompt } from "./prompt.js";
+import { cacheGet, cacheSet } from "./cache.js";
+import { generateText } from "./backends/index.js";
+import { sha256 } from "./util/text.js";
+import { hrtimeMs, nowIso } from "./util/timing.js";
+
+function computeCacheKey({ left, right, options, leftDocs, rightDocs }) {
+  const payload = {
+    v: 1, // bump to invalidate cache when prompt logic changes
+    left,
+    right,
+    backend: options.backend || "auto",
+    model: options.model || null,
+    level: options.level || "intermediate",
+    mode: options.mode || "summary",
+    includeDocs: Boolean(options.includeDocs),
+    docsHash: sha256(`${leftDocs}\n---\n${rightDocs}`),
+  };
+  return sha256(JSON.stringify(payload));
+}
+
+export async function buildComparisonPrompt(left, right, options) {
+  const includeDocs = options.includeDocs !== false;
+
+  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" },
+      ];
+
+  const leftDocs = leftInfo.docs || "";
+  const rightDocs = rightInfo.docs || "";
+
+  const prompt = buildPrompt({
+    left,
+    right,
+    leftDocs,
+    rightDocs,
+    level: options.level,
+    mode: options.mode,
+  });
+
+  return { prompt, leftInfo, rightInfo, leftDocs, rightDocs };
+}
+
+export async function runComparison(left, right, options) {
+  const t0 = hrtimeMs();
+
+  const { prompt, leftInfo, rightInfo, leftDocs, rightDocs } = await buildComparisonPrompt(
+    left,
+    right,
+    options
+  );
+
+  const key = computeCacheKey({ left, right, options, leftDocs, rightDocs });
+
+  const ttlHours = Number.isFinite(options.ttlHours) ? options.ttlHours : 720;
+  const ttlMs = Math.max(0, ttlHours) * 60 * 60 * 1000;
+  const now = Date.now();
+
+  if (options.cache !== false) {
+    const cached = await cacheGet(key);
+    if (cached?.text) {
+      const t1 = hrtimeMs();
+      return {
+        left,
+        right,
+        backend: cached.backendUsed || cached.backend || options.backend || "auto",
+        model: cached.modelUsed || cached.model || options.model || null,
+        cached: true,
+        createdAt: cached.createdAt,
+        text: cached.text,
+        meta: {
+          cacheKey: key,
+          cacheHit: true,
+          msTotal: t1 - t0,
+          sources: {
+            left: leftInfo.sources,
+            right: rightInfo.sources,
+          },
+          skipped: {
+            left: leftInfo.skipped,
+            right: rightInfo.skipped,
+          },
+        },
+      };
+    }
+  }
+
+  const tLLM0 = hrtimeMs();
+  const gen = await generateText({
+    backend: options.backend,
+    prompt,
+    model: options.model,
+  });
+  const tLLM1 = hrtimeMs();
+
+  const createdAt = nowIso();
+  const expiresAt = ttlMs > 0 ? new Date(now + ttlMs).toISOString() : null;
+
+  const entry = {
+    createdAt,
+    expiresAt,
+    text: gen.text,
+    backendUsed: gen.backendUsed,
+    modelUsed: gen.modelUsed,
+  };
+
+  if (options.cache !== false) {
+    await cacheSet(key, entry);
+  }
+
+  const t1 = hrtimeMs();
+
+  return {
+    left,
+    right,
+    backend: gen.backendUsed,
+    model: gen.modelUsed,
+    cached: false,
+    createdAt,
+    text: gen.text,
+    meta: {
+      cacheKey: key,
+      cacheHit: false,
+      msTotal: t1 - t0,
+      msLLM: tLLM1 - tLLM0,
+      sources: {
+        left: leftInfo.sources,
+        right: rightInfo.sources,
+      },
+      skipped: {
+        left: leftInfo.skipped,
+        right: rightInfo.skipped,
+      },
+    },
+  };
+}

package/src/introspect.js

@@ -0,0 +1,165 @@
+import { spawn } from "node:child_process";
+
+import { validateTargetForExec } from "./util/sanitize.js";
+import { normalizeText, truncate } from "./util/text.js";
+
+const DEFAULT_TIMEOUT_MS = 1200;
+
+function blockedBecausePrivilege(tokens) {
+  const first = tokens[0];
+  return first === "sudo" || first === "su" || first === "doas";
+}
+
+function runCommand(cmd, args, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        // Make man output less "paged" and less fancy.
+        MANPAGER: "cat",
+        PAGER: "cat",
+        LESS: "FRX",
+      },
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const killTimer =
+      timeoutMs && timeoutMs > 0
+        ? setTimeout(() => {
+            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")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+
+    child.on("error", () => {
+      if (done) return;
+      done = true;
+      if (killTimer) clearTimeout(killTimer);
+      resolve({ ok: false, stdout: "", stderr: "", error: true });
+    });
+
+    child.on("close", (code) => {
+      if (done) return;
+      done = true;
+      if (killTimer) clearTimeout(killTimer);
+      resolve({ ok: code === 0, stdout, stderr, code });
+    });
+  });
+}
+
+async function tryAddSource(sources, kind, cmd, args, maxCharsPerSource) {
+  const res = await runCommand(cmd, args);
+  const cleaned = normalizeText(res.stdout);
+  if (!cleaned) return;
+  sources.push({
+    kind,
+    cmd,
+    args,
+    chars: cleaned.length,
+    snippet: cleaned.slice(0, 80),
+  });
+  return truncate(cleaned, maxCharsPerSource);
+}
+
+export async function collectDocs(target, { maxChars = 6000, debug = false } = {}) {
+  const validated = validateTargetForExec(target);
+  if (!validated.ok) {
+    return {
+      docs: "",
+      sources: [],
+      skipped: validated.reason,
+    };
+  }
+
+  const tokens = validated.tokens;
+
+  if (blockedBecausePrivilege(tokens)) {
+    return {
+      docs: "",
+      sources: [],
+      skipped: `Skipping local docs for safety (starts with '${tokens[0]}').`,
+    };
+  }
+
+  // Split budget between sources. We'll aim for ~3 sources max, so maxChars/3 each.
+  const maxPerSource = Math.max(800, Math.floor(maxChars / 3));
+
+  const sources = [];
+  const [cmd, ...rest] = tokens;
+
+  const parts = [];
+
+  // Always try man for the base command first.
+  const manBase = await tryAddSource(sources, "man", "man", ["-P", "cat", cmd], maxPerSource);
+  if (manBase) parts.push(`## man ${cmd}\n${manBase}`);
+
+  // If we have a subcommand, try a man page like git-pull.
+  if (rest.length >= 1) {
+    const sub = rest[0];
+    const manSub = await tryAddSource(
+      sources,
+      "man-subcommand",
+      "man",
+      ["-P", "cat", `${cmd}-${sub}`],
+      maxPerSource
+    );
+    if (manSub) parts.push(`## man ${cmd}-${sub}\n${manSub}`);
+  }
+
+  // Try --help. For multi-token, we do: <cmd> <rest...> --help
+  {
+    const helpArgs = rest.length ? [...rest, "--help"] : ["--help"];
+    const helpOut = await tryAddSource(sources, "--help", cmd, helpArgs, maxPerSource);
+    if (helpOut) parts.push(`## ${cmd} ${helpArgs.join(" ")}\n${helpOut}`);
+  }
+
+  // Try info for base command (info doesn't do subcommands well usually).
+  {
+    const infoOut = await tryAddSource(sources, "info", "info", [cmd], maxPerSource);
+    if (infoOut) parts.push(`## info ${cmd}\n${infoOut}`);
+  }
+
+  // Try bash builtin help (only makes sense for single tokens like 'cd', 'help', etc.)
+  if (rest.length === 0) {
+    const bashOut = await tryAddSource(
+      sources,
+      "bash-help",
+      "bash",
+      ["-lc", `help ${cmd}`],
+      maxPerSource
+    );
+    if (bashOut) parts.push(`## bash help ${cmd}\n${bashOut}`);
+  }
+
+  // Heuristic: git help <subcommand>
+  if (cmd === "git" && rest.length >= 1) {
+    const sub = rest[0];
+    const gitHelp = await tryAddSource(
+      sources,
+      "git-help",
+      "git",
+      ["help", sub],
+      maxPerSource
+    );
+    if (gitHelp) parts.push(`## git help ${sub}\n${gitHelp}`);
+  }
+
+  const docs = parts.join("\n\n").trim();
+
+  return {
+    docs,
+    sources: debug ? sources : sources.map(({ kind }) => ({ kind })),
+    skipped: docs ? null : "No local docs found via man/--help/info/bash help.",
+  };
+}