lurqrun 0.1.6 → 0.1.7

package/dist/commands-FIL5ET6P.js

@@ -0,0 +1,911 @@
+import { createRequire as __lurqCreateRequire } from 'node:module'; const require = __lurqCreateRequire(import.meta.url);
+import {
+  searchCapabilities
+} from "./chunk-L6N4JFW2.js";
+import {
+  CONFIDENCE,
+  QUALITY_WEIGHTS,
+  WEIGHT_EXPLANATIONS,
+  activeWeightsPath,
+  applyOverrides,
+  loadWeights,
+  resetWeights,
+  saveWeights,
+  settableKeys,
+  validateWeights
+} from "./chunk-2VMOWSRY.js";
+import {
+  isCategory
+} from "./chunk-VLRHFMGJ.js";
+import {
+  require_semver
+} from "./chunk-3GHJR7XR.js";
+import {
+  loadEnv,
+  requireConfig
+} from "./chunk-GRJXQBQZ.js";
+import "./chunk-WHX2ZFCG.js";
+import {
+  MissingKeyError
+} from "./chunk-4ZYCIMY4.js";
+import {
+  openInBrowser
+} from "./chunk-TNTXWSYA.js";
+import {
+  bold,
+  confidenceLabel,
+  detail,
+  dim,
+  formatDate,
+  formatNumber,
+  formatPercent,
+  green,
+  red,
+  table,
+  yellow
+} from "./chunk-4KCPOMG6.js";
+import "./chunk-LUAKDHLZ.js";
+import {
+  resolveApiKey
+} from "./chunk-Y5GI7RL3.js";
+import "./chunk-GPTKSNR6.js";
+import {
+  __toESM,
+  init_esm_shims
+} from "./chunk-I3M2KJXB.js";
+
+// src/cli/commands.ts
+init_esm_shims();
+var import_semver = __toESM(require_semver(), 1);
+var handleRecommend = async (...a) => (await import("./handlers-GEJAVZDK.js")).handleRecommend(...a);
+var handleEvaluate = async (...a) => (await import("./handlers-GEJAVZDK.js")).handleEvaluate(...a);
+var handleCompare = async (...a) => (await import("./handlers-GEJAVZDK.js")).handleCompare(...a);
+var handleVerify = async (...a) => (await import("./handlers-GEJAVZDK.js")).handleVerify(...a);
+var getPackageVersions = async (...a) => (await import("./packages-THVFMWFP.js")).getPackageVersions(...a);
+async function withDb(fn) {
+  requireConfig(["DATABASE_URL"]);
+  const { createDb } = await import("./client-IRKAMDYZ.js");
+  const handle = createDb();
+  try {
+    return await fn(handle.db);
+  } finally {
+    await handle.close();
+  }
+}
+function indexSource() {
+  loadEnv();
+  if (process.env.LURQ_LOCAL === "1") return "local";
+  if (resolveApiKey()) return "hosted";
+  if (process.env.DATABASE_URL) return "local";
+  throw new MissingKeyError();
+}
+async function fromIndex(tool, args, local) {
+  if (indexSource() === "local") return withDb(local);
+  const { callTool } = await import("./remote-YGCXYI4V.js");
+  return callTool(tool, args);
+}
+function candidateFlags(c) {
+  const flags = [
+    c.deprecated && red("deprecated"),
+    c.archived && yellow("archived"),
+    c.advisories ? yellow(`${c.advisories} advisory`) : null
+  ].filter(Boolean);
+  return flags.length ? flags.join(" ") : dim("\u2014");
+}
+async function runRecommend(need, opts) {
+  if (opts.category && !isCategory(opts.category)) {
+    throw new Error(`Unknown category "${opts.category}".`);
+  }
+  const args = {
+    need,
+    category: opts.category,
+    constraints: opts.minConfidence ? { minConfidence: opts.minConfidence } : void 0
+  };
+  const res = await fromIndex("recommend", args, (db) => handleRecommend(db, args));
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  const candidates = res.candidates ?? [];
+  if (candidates.length === 0) {
+    console.log("No matching packages found.");
+    return;
+  }
+  console.log(
+    table(
+      ["Package", "Health", "Quality", "Confidence", "Weekly", "Latest", "Category", "Flags"],
+      candidates.map((c) => [
+        c.name,
+        String(c.healthScore),
+        c.qualityScore != null ? String(c.qualityScore) : "\u2014",
+        confidenceLabel(c.confidence),
+        formatNumber(c.weeklyDownloads),
+        c.latestVersion ?? "\u2014",
+        c.category ?? "\u2014",
+        // Last, and the only coloured cell: it is the column that can reverse
+        // the decision the other seven are supporting, so it reads as a verdict
+        // at the end of the row rather than as one more attribute among them.
+        candidateFlags(c)
+      ])
+    )
+  );
+  printExclusions(res);
+  console.log(dim(`
+data as of ${formatDate(res.dataAsOf)}`));
+}
+function printExclusions(res) {
+  if (!("excluded" in res)) return;
+  const excluded = res.excluded ?? [];
+  if (excluded.length === 0) return;
+  console.log(yellow(`
+policy refused ${excluded.length}:`));
+  for (const e of excluded) console.log(`  ${e.name}  ${dim(`${e.rule}: ${e.reason}`)}`);
+}
+async function runEvaluate(pkg, opts) {
+  const res = await fromIndex(
+    "evaluate",
+    { package: pkg },
+    (db) => handleEvaluate(db, { package: pkg })
+  );
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  if ("tracked" in res) {
+    console.log(res.suggestion);
+    return;
+  }
+  console.log(bold(res.name) + (res.category ? dim(`  (${res.category})`) : ""));
+  if (res.policy) {
+    console.log(
+      res.policy.allowed ? green("policy: allowed") : red(`policy: blocked (${res.policy.rule}): ${res.policy.reason}`)
+    );
+  }
+  const b = res.scoreBreakdown ?? {};
+  const advisories = res.advisories;
+  console.log(
+    detail([
+      ["health", `${res.healthScore}  ${confidenceLabel(res.confidence)}`],
+      ["quality", res.qualityScore != null ? String(res.qualityScore) : "\u2014"],
+      [
+        "breakdown",
+        `maint ${b.maintenance ?? "\u2014"} \xB7 adopt ${b.adoption ?? "\u2014"} \xB7 rel ${b.reliability ?? "\u2014"} \xB7 eff ${b.efficiency ?? "\u2014"} \xB7 qual ${b.quality ?? "\u2014"}`
+      ],
+      ["version", res.latestVersion ?? "\u2014"],
+      [
+        "weekly dl",
+        `${formatNumber(res.weeklyDownloads)}  (${formatPercent(res.downloadGrowth90d)} 90d)`
+      ],
+      ["scorecard", res.scorecard != null ? String(res.scorecard) : "\u2014"],
+      ["bundle", res.bundleMinGzipKb != null ? `${res.bundleMinGzipKb} KB gzip` : "\u2014"],
+      ["released", formatDate(res.lastReleaseAt)],
+      [
+        "flags",
+        [res.deprecated && "deprecated", res.archived && "archived"].filter(Boolean).join(", ") || "none"
+      ],
+      [
+        "advisories",
+        advisories == null ? yellow("not checked yet") : advisories.length ? advisories.map((a) => `${a.severity}`).join(", ") : "none"
+      ],
+      ["repo", res.repoUrl ?? "\u2014"]
+    ])
+  );
+  if (res.buildVerified) {
+    const bv = res.buildVerified;
+    const state = !bv.installed ? red("install failed") : bv.loaded === false ? yellow("installs, load failed") : green("installs and loads");
+    console.log(`
+sandbox: ${state}  ${dim(`${bv.version} \xB7 ${bv.driver}`)}`);
+  }
+  if (res.summary) console.log("\n" + res.summary);
+  if (res.usageGuide) {
+    const g = res.usageGuide;
+    console.log(
+      "\n" + detail(
+        [
+          ["what", g.whatItIs],
+          ["when", g.whenToUse],
+          g.whenNotToUse ? ["when not", g.whenNotToUse] : null,
+          ["fits", g.whereItFits],
+          g.howToWireIn ? ["wire-in", g.howToWireIn] : null
+        ].filter(Boolean)
+      )
+    );
+  }
+  console.log(dim(`
+data as of ${formatDate(res.dataAsOf)}${res.stale ? "  (stale)" : ""}`));
+}
+async function runCompare(pkgs, opts) {
+  const res = await fromIndex(
+    "compare",
+    { packages: pkgs },
+    (db) => handleCompare(db, { packages: pkgs })
+  );
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  console.log(
+    table(
+      ["Package", "Health", "Confidence", "Weekly", "90d", "Scorecard", "Released"],
+      (res.rows ?? []).map((r) => [
+        r.name,
+        String(r.healthScore),
+        confidenceLabel(r.confidence),
+        formatNumber(r.weeklyDownloads),
+        formatPercent(r.downloadGrowth90d),
+        r.scorecard != null ? String(r.scorecard) : "\u2014",
+        formatDate(r.lastReleaseAt)
+      ])
+    )
+  );
+  const notFound = res.notFound ?? (res.pending ? [] : res.missing ?? []);
+  if (notFound.length) console.log(red(`
+not on npm: ${notFound.join(", ")}`));
+  if (res.pending?.length) {
+    console.log(dim(`
+being scored now (retry shortly): ${res.pending.join(", ")}`));
+  }
+  console.log(dim(`data as of ${formatDate(res.dataAsOf)}`));
+}
+function runCan(query, opts = {}) {
+  const matches = searchCapabilities(query, 5);
+  if (opts.json) {
+    console.log(JSON.stringify(matches, null, 2));
+    return;
+  }
+  if (!query.trim()) console.log(dim("Showing everything lurq does. Add words to narrow it.\n"));
+  for (const m of matches) {
+    console.log(bold(m.title));
+    console.log(`  ${m.answer}`);
+    if (m.cli) console.log(`  ${green("$")} ${m.cli}`);
+    if (m.mcp) console.log(dim(`  agents: call the \`${m.mcp}\` tool`));
+    if (m.page) console.log(dim(`  dashboard: https://lurq.run${m.page}`));
+    console.log("");
+  }
+}
+function runWeights(opts = {}) {
+  const w = loadWeights();
+  const active = activeWeightsPath();
+  if (opts.json) {
+    console.log(JSON.stringify({ ...w, source: active?.source ?? "defaults" }, null, 2));
+    return;
+  }
+  const pct = (n) => n.toFixed(2);
+  console.log(bold("Two axes, blended for default sort:"));
+  console.log(`  composite = (1\u2212\u03BB)\xB7health + \u03BB\xB7quality      \u03BB = ${pct(w.composite.lambda)}
+`);
+  console.log(bold("Health (proven-ness) \u2014 weighted sum of 4 components:"));
+  console.log(
+    detail([
+      [
+        "maintenance",
+        `${pct(w.health.maintenance)}  ${dim("\u2014 " + WEIGHT_EXPLANATIONS.maintenance)}`
+      ],
+      ["adoption", `${pct(w.health.adoption)}  ${dim("\u2014 " + WEIGHT_EXPLANATIONS.adoption)}`],
+      [
+        "reliability",
+        `${pct(w.health.reliability)}  ${dim("\u2014 " + WEIGHT_EXPLANATIONS.reliability)}`
+      ],
+      ["efficiency", `${pct(w.health.efficiency)}  ${dim("\u2014 " + WEIGHT_EXPLANATIONS.efficiency)}`]
+    ])
+  );
+  console.log("\n" + bold("Quality (intrinsic, adoption-independent):"));
+  console.log("  " + dim(Object.keys(QUALITY_WEIGHTS).join(", ")));
+  console.log("\n" + bold("Confidence thresholds:"));
+  console.log(
+    detail([
+      [
+        "proven",
+        `\u2265 ${formatNumber(CONFIDENCE.proven.minWeeklyDownloads)} weekly dl, \u2265 ${CONFIDENCE.proven.minAgeMonths}mo old`
+      ],
+      [
+        "emerging",
+        `\u2265 ${formatNumber(CONFIDENCE.emerging.minWeeklyDownloads)} weekly dl OR \u2265 ${CONFIDENCE.emerging.strongGrowth * 100}% 90d growth`
+      ],
+      ["promising", `\u2265 ${CONFIDENCE.promising.minQuality} quality score (adoption-independent)`]
+    ])
+  );
+  console.log(
+    dim(
+      `
+Source: ${active ? `${active.source} (${active.path})` : "defaults (no user overrides)"}`
+    )
+  );
+}
+async function runEditWeights(opts) {
+  const { invalidateCache } = await import("./cache-DKI34SVS.js");
+  if (opts.reset) {
+    const removed = resetWeights();
+    console.log(
+      removed.length ? `Removed overrides:
+  ${removed.join("\n  ")}` : "No overrides to remove; already on defaults."
+    );
+    if (removed.length) await invalidateCache();
+    return;
+  }
+  if (opts.explain) {
+    const key = opts.explain;
+    const text = WEIGHT_EXPLANATIONS[key];
+    if (!text) {
+      throw new Error(
+        `No explanation for "${key}". Known: ${Object.keys(WEIGHT_EXPLANATIONS).join(", ")}.`
+      );
+    }
+    console.log(`${bold(key)} \u2014 ${text}`);
+    return;
+  }
+  if (opts.set && opts.set.length > 0) {
+    const next = applyOverrides(loadWeights(), opts.set);
+    const { weights, normalized } = validateWeights(next);
+    const path = saveWeights(weights, opts.project ? "project" : "user");
+    await invalidateCache();
+    console.log(`Saved overrides to ${path}`);
+    if (normalized) {
+      console.log(
+        yellow("Health weights did not sum to 1.0 \u2014 renormalized to: ") + `maint ${weights.health.maintenance.toFixed(3)}, adopt ${weights.health.adoption.toFixed(3)}, rel ${weights.health.reliability.toFixed(3)}, eff ${weights.health.efficiency.toFixed(3)}`
+      );
+    }
+    console.log(
+      dim(
+        "\nThese weights apply to a self-hosted index, on its next operator rescore.\nThe hosted service ranks with its published weights (`lurq weights`)."
+      )
+    );
+    return;
+  }
+  console.log(dim(`No changes. Settable keys: ${settableKeys().join(", ")}.
+`));
+  runWeights(opts);
+}
+async function runPlan(file, opts) {
+  const { readFileSync } = await import("fs");
+  let document;
+  try {
+    document = readFileSync(file, "utf8");
+  } catch {
+    throw new Error(`Could not read "${file}".`);
+  }
+  if (opts.optimize && opts.optimize !== "speed" && opts.optimize !== "balanced") {
+    throw new Error("--optimize must be 'speed' or 'balanced'.");
+  }
+  const args = { document, optimize: opts.optimize };
+  const res = await fromIndex("plan", args, async (db) => {
+    const { handlePlan } = await import("./plan-V4OEI3J4.js");
+    return handlePlan(db, args);
+  });
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  if (!("slots" in res)) {
+    console.log(res.note);
+    return;
+  }
+  if (opts.html || opts.open) {
+    const { writeFileSync } = await import("fs");
+    const { tmpdir } = await import("os");
+    const { join } = await import("path");
+    const { renderPlanHtml } = await import("./planView-JRXGCG2N.js");
+    const out = opts.html ?? join(tmpdir(), `lurq-plan-${Date.now()}.html`);
+    writeFileSync(out, renderPlanHtml(res), "utf8");
+    console.log(`Roadmap written to ${out}`);
+    if (opts.open) openInBrowser(out);
+  }
+  console.log(
+    table(
+      ["Component", "Layer", "Recommended", "Health", "Confidence", "Alternatives"],
+      (res.slots ?? []).map((s) => [
+        s.need.length > 32 ? s.need.slice(0, 31) + "\u2026" : s.need,
+        s.layer,
+        s.recommended ? `${s.recommended.name}@${s.recommended.latestVersion ?? "?"}` : dim("\u2014"),
+        s.recommended ? String(s.recommended.healthScore) : "\u2014",
+        s.recommended ? confidenceLabel(s.recommended.confidence) : "\u2014",
+        (s.alternatives ?? []).map((a) => a.name).join(", ") || "\u2014"
+      ])
+    )
+  );
+  if ((res.unmatched ?? []).length)
+    console.log(yellow(`
+No match for: ${(res.unmatched ?? []).join(", ")}`));
+  if (res.compatibility) {
+    const c = res.compatibility;
+    const col = c.overall === "compatible" ? green : c.overall === "conflict" ? red : dim;
+    console.log("\n" + bold("Compatibility: ") + col(c.overall));
+    for (const s of res.slots ?? []) {
+      if (s.swappedFrom && s.recommended) {
+        console.log(
+          green(`  \u2713 swapped ${s.swappedFrom} \u2192 ${s.recommended.name} for compatibility`)
+        );
+      }
+    }
+    for (const cf of c.conflicts ?? [])
+      console.log(red(`  \u2717 ${cf.detail} (no compatible alternative)`));
+    if (c.unverified?.length) console.log(dim(`  unverified: ${c.unverified.join(", ")}`));
+  }
+  console.log("\n" + bold("Roadmap (Mermaid):"));
+  console.log(res.mermaid);
+  console.log(dim(`
+${res.note}`));
+  console.log(dim(`data as of ${formatDate(res.dataAsOf)}`));
+}
+async function runVerify(pkg, opts) {
+  const res = await fromIndex(
+    "verify",
+    { package: pkg },
+    (db) => handleVerify(db, { package: pkg })
+  );
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  const v = res.verdict;
+  const headline = v.level === "invalid" ? red("\u2717 NOT A REAL PACKAGE") : v.level === "high" ? red(`\u2717 do not install ${v.scope} without review`) : v.level === "medium" ? yellow("\u26A0 usable, but read the findings") : v.reassuring ? green(`\u2713 no supply-chain problems found in ${v.scope}`) : yellow(`? ${v.scope} is not fully checked yet`);
+  console.log(`${bold(pkg)}  ${headline}`);
+  for (const r of v.reasons ?? []) console.log(`  ${red("\u2022")} ${r}`);
+  for (const u of v.unknowns ?? []) console.log(`  ${yellow("?")} ${u}`);
+  if (v.level === "invalid") return;
+  const riskColor = v.level === "high" ? red : v.level === "medium" ? yellow : green;
+  const riskFlags = res.riskFlags ?? [];
+  console.log(
+    detail([
+      ["version", res.latestVersion ?? "\u2014"],
+      ["weekly dl", formatNumber(res.weeklyDownloads)],
+      ["confidence", res.confidence ? confidenceLabel(res.confidence) : "\u2014"],
+      // Never "0" for something nobody has looked at.
+      [
+        "advisories",
+        res.advisoryCount == null ? yellow("not checked yet") : String(res.advisoryCount)
+      ],
+      ["risk", riskColor(v.level)],
+      ["risk flags", riskFlags.length ? yellow(riskFlags.join(", ")) : "none"]
+    ])
+  );
+}
+async function runVersions(pkg, opts) {
+  const limit = opts.limit ? Math.max(1, parseInt(opts.limit, 10) || 30) : 30;
+  loadEnv();
+  if (!process.env.DATABASE_URL) {
+    throw new Error(
+      "`lurq versions` reads a self-hosted index and is not available on the hosted service. To see what changed between two versions, run `lurq usage <pkg> --known <v>`."
+    );
+  }
+  await withDb(async (db) => {
+    const versions = await getPackageVersions(db, pkg, limit);
+    if (opts.json) return console.log(JSON.stringify(versions, null, 2));
+    if (versions.length === 0) {
+      console.log(`No stored versions for ${bold(pkg)}. Run \`lurq sync --package ${pkg}\` first.`);
+      return;
+    }
+    console.log(bold(pkg));
+    console.log(
+      table(
+        ["Version", "Published"],
+        versions.map((v) => [
+          v.version,
+          v.publishedAt ? v.publishedAt.toISOString().slice(0, 10) : "\u2014"
+        ])
+      )
+    );
+  });
+}
+async function runWatch() {
+  const { watchNpmChanges } = await import("./watch-DGFMWUDL.js");
+  await withDb(async (db) => {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    console.log(dim("watching npm for releases of tracked packages \u2014 Ctrl-C to stop"));
+    try {
+      await watchNpmChanges(db, { signal: controller.signal });
+    } finally {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+    }
+  });
+}
+async function runSandbox(pkg, version, opts) {
+  if (opts.allowScripts) {
+    console.error(
+      yellow("warning: running install scripts and loading the package locally without isolation")
+    );
+  }
+  const { verifyPackageInSandbox } = await import("./sandbox-MEZLAODF.js");
+  await withDb(async (db) => {
+    const result = await verifyPackageInSandbox(db, pkg, version ?? null, {
+      target: { node: "20", moduleSystem: opts.esm ? "esm" : "cjs" },
+      allowScripts: opts.allowScripts
+    });
+    if (opts.json) return console.log(JSON.stringify(result, null, 2));
+    const ok = result.installed && result.imported !== false;
+    const label = version ? `${pkg}@${version}` : pkg;
+    const verdict = ok ? green("\u2713 installs and loads") : red("\u2717 failed");
+    console.log(
+      `${bold(label)}  ${verdict}  ${dim(`(${result.durationMs}ms \xB7 ${result.driver})`)}`
+    );
+    console.log(
+      detail([
+        ["installed", result.installed ? "yes" : "no"],
+        ["loaded", result.imported === null ? "\u2014" : result.imported ? "yes" : "no"],
+        ["module", result.moduleSystem],
+        ["scripts", result.ranScripts ? "ran" : "skipped"],
+        ["error", result.error ?? "none"]
+      ])
+    );
+  });
+}
+async function runUsage(pkg, opts) {
+  const args = {
+    package: pkg,
+    version: opts.version,
+    knownVersion: opts.known,
+    query: opts.query,
+    offset: opts.offset
+  };
+  const res = await fromIndex("usage", args, async (db) => {
+    const { handleUsage } = await import("./handlers-GEJAVZDK.js");
+    return handleUsage(db, args);
+  });
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  console.log(`${bold(res.package)}${res.version ? `@${res.version}` : ""}`);
+  if (res.engines) {
+    const reqs = Object.entries(res.engines).map(([k, v]) => `${k} ${v}`).join(", ");
+    if (reqs) console.log(dim(`requires: ${reqs}`));
+  }
+  if (res.unpublishedVersion) return console.log(red(res.note ?? "that version does not exist"));
+  if (!res.available) return console.log(dim(res.note ?? "no API surface available"));
+  console.log(
+    table(
+      ["Export", "Kind", "Signature"],
+      (res.surface ?? []).map((s) => [s.name, s.kind, s.signature ?? ""])
+    )
+  );
+  if (res.note) console.log(res.shallow ? yellow(res.note) : dim(res.note));
+  if (res.delta) {
+    const d = res.delta;
+    const removed = d.removed ?? [];
+    const added = d.added ?? [];
+    const renamed = d.renamed ?? [];
+    const changed = d.changed ?? [];
+    console.log(bold(`
+\u0394 from ${res.package}@${d.fromVersion}:`));
+    for (const s of removed) console.log(red(`  - ${s.name}`));
+    for (const s of added) console.log(green(`  + ${s.name}`));
+    for (const r of renamed) console.log(yellow(`  ~ ${r.from.name} \u2192 ${r.to.name}`));
+    for (const c of changed)
+      console.log(yellow(`  ! ${c.name}: ${c.before ?? "?"} \u2192 ${c.after ?? "?"}`));
+    if (!removed.length && !added.length && !renamed.length && !changed.length) {
+      console.log(dim("  no API changes"));
+    }
+  } else if (res.deltaNote) {
+    console.log(yellow(`
+${res.deltaNote}`));
+  }
+}
+async function runCompatBackfill(opts) {
+  await withDb(async (db) => {
+    const compat = await import("./compat-R3UTFQ5Q.js");
+    if (opts.resolve) {
+      console.error(yellow("resolve-only backfill (npm resolution, no install/VM)"));
+      const res2 = await compat.resolveBackfill(db, opts);
+      console.log(
+        `${green("resolve backfill done")}: ${res2.verified} edges across ${res2.batches} runs, ${res2.skipped} batches skipped`
+      );
+      return;
+    }
+    console.error(
+      yellow(
+        "co-installing top packages in the sandbox (loads package code locally without isolation unless E2B_API_KEY is set)"
+      )
+    );
+    const res = await compat.backfillVerify(db, opts);
+    console.log(
+      `${green("backfill done")}: ${res.verified} edges across ${res.batches} runs, ${res.skipped} batches skipped`
+    );
+  });
+}
+function parsePins(pins) {
+  if (!pins?.length) return void 0;
+  const out = {};
+  for (const raw of pins) {
+    const at = raw.indexOf("=");
+    const name = at === -1 ? "" : raw.slice(0, at).trim();
+    const version = at === -1 ? "" : raw.slice(at + 1).trim();
+    if (!name || !version) throw new Error(`--pin expects name=version, got "${raw}"`);
+    if (!import_semver.default.valid(version)) {
+      throw new Error(
+        `--pin needs an exact published version, got "${name}=${version}". A range resolves to latest instead of erroring, which would report the wrong version as pinned.`
+      );
+    }
+    out[name] = version;
+  }
+  return out;
+}
+async function runCompat(pkgs, opts) {
+  const versions = parsePins(opts.pin);
+  const args = { packages: pkgs, versions };
+  const read = async (db) => {
+    const { handleCompat } = await import("./handlers-GEJAVZDK.js");
+    return handleCompat(db, args);
+  };
+  const res = opts.run ? await withDb(async (db) => {
+    console.error(
+      yellow("co-installing in the sandbox (loads package code locally without isolation)")
+    );
+    const { verifyCompatibility } = await import("./compat-R3UTFQ5Q.js");
+    await verifyCompatibility(db, pkgs);
+    return read(db);
+  }) : await fromIndex("compat", args, read);
+  const conflicts = res.conflicts ?? [];
+  const unverified = res.unverified ?? [];
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  const color = res.overall === "compatible" ? green : res.overall === "conflict" ? red : dim;
+  console.log(`${bold((res.packages ?? pkgs).join(" + "))}  ${color(res.overall)}`);
+  if (conflicts.length) {
+    console.log(
+      table(
+        ["Source", "Detail"],
+        conflicts.map((c) => [c.source, c.detail])
+      )
+    );
+  } else if (res.overall === "compatible") {
+    console.log(dim("no peer-dependency or engine conflicts across the set"));
+  }
+  if (unverified.length) {
+    console.log(dim(`
+unverified (no metadata): ${unverified.join(", ")}`));
+  }
+  const conflicted = new Set(
+    conflicts.flatMap((c) => c.packages.length >= 2 ? [[...c.packages].sort().join("\0")] : [])
+  );
+  const isOverruled = (e) => conflicted.has([...e.packages].sort().join("\0"));
+  const compatEvidence = (res.evidence ?? []).filter((e) => e.status === "compatible");
+  if (compatEvidence.length) {
+    console.log(
+      table(
+        ["Pair", "Evidence", "Witnesses"],
+        compatEvidence.map((e) => [
+          `${e.packages[0]} + ${e.packages[1]}`,
+          isOverruled(e) ? `${e.provenance} (overruled)` : e.provenance,
+          e.provenance === "observed" ? String(e.witnessCount) : "\u2014"
+        ])
+      )
+    );
+    if (compatEvidence.some(isOverruled)) {
+      console.log(
+        dim("overruled: a declared peer/engine constraint above beats the co-resolution witness")
+      );
+    }
+  }
+}
+async function runMcpSurface(server, opts) {
+  const args = { server, version: opts.version ?? null };
+  const res = await fromIndex(
+    "mcp_surface",
+    args,
+    (db) => import("./mcpHandlers-QFN4MCFL.js").then((m) => m.handleMcpSurface(db, args))
+  );
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  console.log(`${bold(server)}${res.version ? dim(`@${res.version}`) : ""}`);
+  const requires = res.requires ?? [];
+  if (requires.length) {
+    console.log(
+      table(
+        ["Needs", "Required", "Secret", "What for"],
+        requires.map((r) => [
+          r.name,
+          r.required ? red("yes") : dim("no"),
+          r.secret ? yellow("yes") : dim("no"),
+          r.description ?? "\u2014"
+        ])
+      )
+    );
+  }
+  if (res.configRequest) console.log(yellow(`
+${res.configRequest}
+`));
+  const tools = res.tools ?? [];
+  if (res.verdict !== "verified_true" || tools.length === 0) {
+    console.log(yellow(`${res.verdict}: ${res.coverageNote}`));
+    return;
+  }
+  console.log(
+    table(
+      ["Tool", "Required", "Optional", "Behaviour"],
+      tools.map((t) => {
+        const required = t.required ?? [];
+        const optional = (t.params ?? []).filter((p) => !required.includes(p));
+        const a = t.annotations ?? {};
+        const behaviour = [
+          a.readOnlyHint ? green("read-only") : red("writes"),
+          a.destructiveHint ? red("destroys") : null,
+          a.openWorldHint ? yellow("external") : null,
+          t.deprecated ? yellow("deprecated") : null
+        ].filter(Boolean).join(" ");
+        return [t.name, required.join(", ") || "\u2014", optional.join(", ") || "\u2014", behaviour];
+      })
+    )
+  );
+  console.log(dim(res.coverageNote));
+}
+async function runMcpDrift(server, opts) {
+  const args = { server, fromVersion: opts.from, toVersion: opts.to };
+  const res = await fromIndex(
+    "mcp_drift",
+    args,
+    (db) => import("./mcpHandlers-QFN4MCFL.js").then((m) => m.handleMcpDrift(db, args))
+  );
+  if (opts.json) return console.log(JSON.stringify(res, null, 2));
+  console.log(`${bold(server)} ${dim(`${opts.from} \u2192 ${opts.to}`)}`);
+  if (res.inconclusive) {
+    console.log(yellow(res.inconclusive));
+    return;
+  }
+  const {
+    annotationFlips = [],
+    silentDrift = [],
+    removedTools = [],
+    requiredAdded = [],
+    paramsRemoved = [],
+    typeChanged = [],
+    addedTools = [],
+    requiredRelaxed = [],
+    paramsAdded = [],
+    outputChanged = [],
+    deprecated = [],
+    prosePolished = []
+  } = res;
+  const widened = annotationFlips.filter((f) => f.widensPrivilege);
+  for (const f of widened) {
+    console.log(red(`\u26A0 privilege  ${f.tool}.${f.hint}: ${f.from} \u2192 ${f.to}`));
+  }
+  for (const t of silentDrift) {
+    console.log(yellow(`\u26A0 silent     ${t}: schema changed, description did not`));
+  }
+  for (const t of removedTools) console.log(red(`\u2717 removed    ${t}`));
+  for (const c of requiredAdded) {
+    console.log(red(`\u2717 required   ${c.tool}: ${c.params.join(", ")} now mandatory`));
+  }
+  for (const c of paramsRemoved) {
+    console.log(red(`\u2717 dropped    ${c.tool}: ${c.params.join(", ")}`));
+  }
+  for (const c of typeChanged.filter((x) => !x.widened)) {
+    console.log(red(`\u2717 narrowed   ${c.tool}.${c.param}`));
+  }
+  for (const t of addedTools) console.log(green(`+ added      ${t}`));
+  for (const c of requiredRelaxed) {
+    console.log(green(`+ optional   ${c.tool}: ${c.params.join(", ")}`));
+  }
+  for (const c of paramsAdded) {
+    console.log(green(`+ params     ${c.tool}: ${c.params.join(", ")}`));
+  }
+  for (const c of typeChanged.filter((x) => x.widened)) {
+    console.log(green(`+ relaxed    ${c.tool}.${c.param}`));
+  }
+  for (const t of outputChanged) console.log(dim(`\xB7 output     ${t}`));
+  for (const f of annotationFlips.filter((x) => !x.widensPrivilege)) {
+    console.log(dim(`\xB7 safer      ${f.tool}.${f.hint}: ${f.from} \u2192 ${f.to}`));
+  }
+  for (const t of deprecated) console.log(yellow(`\xB7 deprecated ${t}`));
+  for (const t of prosePolished) console.log(dim(`\xB7 docs only  ${t}`));
+  console.log(
+    res.breaking ? red(`
+${res.summary}`) : green(`
+${res.summary || "no contract change"}`)
+  );
+}
+async function probeProjectServers(servers, budgetMs) {
+  const { createDb } = await import("./client-IRKAMDYZ.js");
+  const { extractAndStoreMcp } = await import("./mcp-3JHD5SUZ.js");
+  const { hasStoredSurface } = await import("./surface-YL6O67W3.js");
+  const { LocalSandbox } = await import("./local-XPZMRH5R.js");
+  const targets = servers.filter((s) => s.kind === "npm-stdio" && s.packageName);
+  if (targets.length === 0) return { probed: 0, skipped: 0 };
+  const handle = createDb({ max: 2 });
+  const sandbox = new LocalSandbox();
+  const deadline = Date.now() + budgetMs;
+  let probed = 0;
+  let skipped = 0;
+  try {
+    for (const s of targets) {
+      if (Date.now() > deadline) {
+        skipped++;
+        continue;
+      }
+      const name = s.packageName;
+      if (s.version && await hasStoredSurface(handle.db, name, s.version, "mcp_tools_list", 0, "mcp_server")) {
+        continue;
+      }
+      try {
+        const r = await extractAndStoreMcp(handle.db, name, s.version, { sandbox });
+        if (r.outcome === "stored" || r.outcome === "cached") probed++;
+      } catch {
+        skipped++;
+      }
+    }
+  } finally {
+    await handle.close();
+  }
+  return { probed, skipped };
+}
+async function runAudit(dir, opts) {
+  const { collectInventory } = await import("./inventory-5AWSLJYU.js");
+  const inv = collectInventory(dir ?? process.cwd(), { projectOnly: opts.projectOnly });
+  let probeNote = null;
+  if (opts.probe) {
+    if (indexSource() !== "local") {
+      probeNote = "--probe is for a self-hosted index; on the hosted service queued MCP servers are probed for you";
+    } else {
+      const budget = Math.max(5e3, Number(opts.probeBudget ?? 90) * 1e3);
+      const { probed, skipped } = await probeProjectServers(inv.mcpServers, budget);
+      probeNote = `probed ${probed} MCP server(s)${skipped ? `, ${skipped} left queued (budget)` : ""}`;
+    }
+  }
+  const payload = {
+    packages: inv.packages.map((p) => ({ name: p.name, range: p.range, installed: p.installed })),
+    transitives: inv.transitives.map((t) => ({ name: t.name, version: t.version, via: t.via })),
+    mcpServers: inv.mcpServers.map((s) => ({
+      alias: s.alias,
+      kind: s.kind,
+      packageName: s.packageName,
+      version: s.version,
+      endpoint: s.endpoint
+    })),
+    notes: inv.notes
+  };
+  const res = await fromIndex(
+    "audit",
+    payload,
+    (db) => import("./auditHandler-JCOJSUYW.js").then((m) => m.handleAudit(db, payload))
+  );
+  if (opts.json) return console.log(JSON.stringify({ ...res, filesRead: inv.filesRead }, null, 2));
+  const { SEVERITY_RANK, worstSeverity } = await import("./types-M5JP2W3D.js");
+  const colour = (s) => s === "critical" || s === "high" ? red : s === "moderate" ? yellow : dim;
+  console.log(bold(inv.root));
+  console.log(dim(`read ${inv.filesRead.length} file(s): ${inv.filesRead.join(", ") || "\u2014"}`));
+  if (probeNote) console.log(dim(probeNote));
+  const flagged = (res.items ?? []).map((i) => ({ ...i, findings: i.findings ?? [] })).filter((i) => i.findings.length > 0).sort(
+    (a, b) => SEVERITY_RANK[worstSeverity(a.findings)] - SEVERITY_RANK[worstSeverity(b.findings)]
+  );
+  if (flagged.length === 0) {
+    console.log(green("\nNothing flagged."));
+  } else {
+    console.log("");
+    for (const item of flagged) {
+      const sev = worstSeverity(item.findings);
+      const tag = item.unit === "mcp" ? dim(" [mcp]") : "";
+      const tag2 = item.unit === "transitive" ? dim(" [transitive]") : tag;
+      const ver = item.installed ? dim(`@${item.installed}`) : "";
+      console.log(`${colour(sev)(sev.padEnd(8))} ${bold(item.name)}${ver}${tag2}`);
+      for (const f of item.findings) console.log(`         ${f.detail}`);
+    }
+  }
+  const c = res.coverage;
+  console.log(
+    `
+${bold("coverage")}  ${c.answered}/${c.discovered} declared dependencies answered` + (c.queued ? `, ${yellow(`${c.queued} queued`)}` : "") + (c.skipped ? `, ${dim(`${c.skipped} not assessable`)}` : "")
+  );
+  console.log(
+    c.treeRead ? dim(`          ${c.transitivesChecked} transitive install(s) checked for vulnerabilities`) : red("          no lockfile \u2014 the dependency tree was NOT checked for vulnerabilities")
+  );
+  if (!c.vulnComplete) {
+    console.log(
+      red("vulnerability lookup incomplete \u2014 absence of a finding here is NOT an all-clear")
+    );
+  }
+  console.log(
+    dim(
+      "          scope: installed packages and configured MCP servers. API versions pinned in your own source are not read."
+    )
+  );
+  for (const n of res.notes ?? []) console.log(dim(`\xB7 ${n}`));
+}
+async function runMcpStack(dir, opts) {
+  const { runMcpStackLive } = await import("./mcpScan-QZHWENIP.js");
+  await runMcpStackLive(dir, opts);
+}
+export {
+  indexSource,
+  runAudit,
+  runCan,
+  runCompare,
+  runCompat,
+  runCompatBackfill,
+  runEditWeights,
+  runEvaluate,
+  runMcpDrift,
+  runMcpStack,
+  runMcpSurface,
+  runPlan,
+  runRecommend,
+  runSandbox,
+  runUsage,
+  runVerify,
+  runVersions,
+  runWatch,
+  runWeights
+};