lurqrun 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,6 +1,77 @@
 import { z } from 'zod';
 import { Command } from 'commander';
 
+/**
+ * The single answer to "is it safe to install this?".
+ *
+ * This exists because lurq had several. `verify` rolled risk flags into a
+ * level, `evaluate` reported a health score and a confidence tier, and `audit`
+ * emitted findings — three code paths deriving safety from overlapping inputs
+ * and disagreeing about the same package. A tool that answers one question
+ * three ways has not answered it, and the disagreement always surfaced at the
+ * worst moment, because the paths diverge exactly where the evidence is thin.
+ *
+ * Every surface now calls this and renders what it returns. Adding a signal
+ * means editing one file, and no caller can accidentally be more reassuring
+ * than the evidence supports.
+ *
+ * Three rules, each of which was a real defect:
+ *
+ *  1. A SECURITY FINDING OVERRIDES QUALITY. A package with a known advisory is
+ *     not "safe" because it is popular and well maintained. The health score
+ *     stays a quality measure — it is not fudged — but it never sets the
+ *     verdict, and the verdict is what every surface leads with.
+ *
+ *  2. UNKNOWN IS NOT CLEAN. `advisories` is NULL until the package has been
+ *     analysed and `[]` once it has, and collapsing those with `?? []` reported
+ *     "0 advisories" for a package nobody had looked at yet. Missing evidence
+ *     is carried in `unknowns` and suppresses reassurance outright.
+ *
+ *  3. A NAME THAT DOES NOT EXIST IS NOT A RISK RATING. It is bad input, and
+ *     saying "high risk" invites the reader to weigh it against a benefit. There
+ *     is no package to weigh.
+ */
+
+/**
+ * `invalid` is deliberately outside `RiskLevel`: it is a statement about the
+ * INPUT, not about a package, and flattening it into `high` loses the only
+ * thing the caller can act on — that there is nothing here to install.
+ */
+type VerdictLevel = RiskLevel | 'invalid';
+interface SecurityVerdict {
+    level: VerdictLevel;
+    /** Why this is not clean, worst first. Empty only when nothing was found. */
+    reasons: string[];
+    /**
+     * What was NOT established. Non-empty means `level` is provisional: it is the
+     * worst we can currently justify, not the worst that is true.
+     */
+    unknowns: string[];
+    /** Every input needed to justify a clean bill was present. */
+    complete: boolean;
+    /**
+     * Safe to render as reassurance ("looks safe", a green tick).
+     *
+     * The one flag every renderer must consult. It requires a low level AND no
+     * findings AND nothing unchecked, so a caller cannot produce a green tick
+     * over a gap in the evidence by reading `level` alone.
+     */
+    reassuring: boolean;
+    /** Advisories actually recorded. Null when none have been fetched yet. */
+    advisoryCount: number | null;
+    /**
+     * WHICH version this verdict is about, in words a reader can act on.
+     *
+     * Without it the surfaces agree and still mislead. `verify vitest` answers
+     * about the latest release and says "no problems found"; the audit answers
+     * about the 2.1.9 you have installed and says "vulnerable". Both are correct
+     * and they read as a contradiction, because neither said what it was talking
+     * about. A clean bill for the newest version is not a clean bill for the one
+     * running in your node_modules.
+     */
+    scope: string;
+}
+
 /**
  * Shared domain types and the v1 category taxonomy (§8.3).
  * These are the stable contracts the rest of the system builds on.
@@ -124,8 +195,13 @@ type PeerMeta = Record<string, {
 /** One incompatibility found across a set of packages. */
 interface CompatConflict {
     /** Where the conflict came from. `peer-deps`/`engines` are Tier-1 (metadata,
-     *  instant, deterministic); `sandbox` is Tier-2 (empirical co-install). */
-    source: 'peer-deps' | 'engines' | 'sandbox';
+     *  instant, deterministic); `resolve` is npm's own ERESOLVE on the whole set;
+     *  `sandbox` is the empirical co-install under VM isolation.
+     *
+     *  A `resolve` conflict is about the SET, not a pair — npm reports that these
+     *  packages cannot coexist, not which two are at fault — so `packages` carries
+     *  every member and `enumeratePairs` deliberately does not attribute it. */
+    source: 'peer-deps' | 'engines' | 'sandbox' | 'resolve';
     /** The packages involved in the conflict. */
     packages: string[];
     detail: string;
@@ -172,19 +248,43 @@ interface CompatEvidence {
      *  only corrected by a backfill, which has not been run. */
     witnessCount: number;
 }
+/**
+ * How the set-level verdict was established.
+ *
+ * `source` distinguishes a cache hit from a resolve we just ran, which matters
+ * for a caller deciding whether the answer is worth re-checking: a cached entry
+ * is exact for those versions and immutable, but it was minted at `at` and the
+ * publish that would have invalidated it may not have been seen yet.
+ */
+interface CompatResolution {
+    source: 'cache' | 'resolved';
+    /** True when npm produced a lockfile for the exact set. */
+    resolved: boolean;
+    /** 'ERESOLVE' for a proven conflict; null when it resolved. */
+    reason: 'ERESOLVE' | null;
+    /** npm's own message on a conflict — names the packages and ranges. */
+    detail?: string;
+    /** ISO timestamp the resolution was established. */
+    at: string;
+}
 /**
  * `compat` output: whole-architecture compatibility for a set of packages.
  * Tier-1 peer-dependency/engine analysis + any Tier-2 sandbox conflicts.
  */
 interface CompatOutput {
     packages: string[];
-    /** Evidence-graded verdict:
-     *  - `conflict`   — a proven incompatibility (peer-range violation or conflict edge).
-     *  - `compatible` — every pair is *positively evidenced* (verified/observed edge).
-     *  - `likely`     — no conflict found, but not proven; absence of a declared
-     *                   conflict is not proof, so an unverified set is never `compatible`.
-     *  - `unknown`    — a member has no metadata yet (not ingested). */
-    overall: 'compatible' | 'likely' | 'conflict' | 'unknown';
+    /** Verdict about the *set*, not its pairs:
+     *  - `conflict`   — proven broken: a peer-range violation, a sandbox conflict,
+     *                   or npm's own ERESOLVE on this exact set.
+     *  - `compatible` — npm resolved these exact versions together.
+     *  - `unknown`    — genuinely undetermined: a member we have no version for, or
+     *                   a resolve that could not complete. Never a hedge on a set
+     *                   we did resolve.
+     *
+     *  There is deliberately no `likely`. It meant "no pair is known to be broken",
+     *  which is a statement about our coverage rather than about the packages, and
+     *  it was the answer real stacks got almost every time. */
+    overall: 'compatible' | 'conflict' | 'unknown';
     conflicts: CompatConflict[];
     /** Packages lurq has no compatibility metadata for (counted toward `unknown`). */
     unverified: string[];
@@ -194,9 +294,12 @@ interface CompatOutput {
         name: string;
         version: string | null;
     }[];
-    /** Stored edges among these packages with their evidence strength (§4B) — lets
-     *  agents (and metrics) see *why* a pair is called compatible, not just that. */
+    /** Sandbox-established edges among these packages (verified/conflict) — the
+     *  one pairwise signal that is not derivable from a set resolution. */
     evidence: CompatEvidence[];
+    /** How the set-level verdict was reached. Absent when a declared conflict made
+     *  a resolve unnecessary, or when a member had no version to key on. */
+    resolution?: CompatResolution;
     /** Every unordered pair among `checked`, each with its own verdict — exactly
      *  n(n−1)/2 entries. `conflicts` lists only what went wrong; this lists what
      *  was compared, which is what lets a caller show coverage rather than just
@@ -349,6 +452,8 @@ interface EvaluateOutput {
     bundleMinGzipKb: number | null;
     deprecated: boolean;
     archived: boolean;
+    /** The shared safety call — identical to what `verify` and `audit` return. */
+    verdict: SecurityVerdict;
     advisories: Advisory[];
     summary: string | null;
     usageGuide: UsageGuide | null;
@@ -364,6 +469,7 @@ interface EvaluateOutput {
 /** `verify` output (§12.3.4). */
 /** Supply-chain risk gate: high = review before installing (see security/risk). */
 type RiskLevel = 'low' | 'medium' | 'high';
+
 interface VerifyOutput {
     exists: boolean;
     tracked: boolean;
@@ -377,7 +483,10 @@ interface VerifyOutput {
     /** Suspected typosquat target — a popular package this name closely mimics. */
     typosquatOf: string | null;
     confidence: Confidence | null;
-    advisoryCount: number;
+    /** Null when this package has never been analysed — NOT the same as zero. */
+    advisoryCount: number | null;
+    /** The shared safety call. Read `verdict.reassuring` before showing a tick. */
+    verdict: SecurityVerdict;
 }
 
 declare const SERVER_NAME = "lurq";
@@ -446,6 +555,27 @@ declare const EnvSchema: z.ZodObject<{
     SUMMARY_API_KEY: z.ZodOptional<z.ZodString>;
     SUMMARY_MODEL: z.ZodDefault<z.ZodString>;
     SUMMARY_BASE_URL: z.ZodDefault<z.ZodString>;
+    /**
+     * How many `npm install --package-lock-only` processes may run at once.
+     *
+     * Each one holds npm's arborist tree in memory — 200-500MB for a real stack —
+     * so this is a memory cap wearing a concurrency hat. Eight concurrent resolves
+     * is ~3GB and will OOM a small container; the work is network-bound anyway, so
+     * raising it buys throughput only until the box runs out of RAM.
+     */
+    LURQ_RESOLVE_CONCURRENCY: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Where npm keeps its metadata cache for stack resolution.
+     *
+     * Point this at a persistent volume in production. A warm cache is the
+     * difference between 8.6s and 19.2s on a 15-package stack (measured), and an
+     * ephemeral container filesystem means every redeploy pays cold cost again for
+     * the first few hundred resolves. Unset = npm's default location.
+     */
+    LURQ_NPM_CACHE_DIR: z.ZodOptional<z.ZodString>;
+    /** Budget for one stack resolve. Past this the answer is `unknown`, never a
+     *  guess — and nothing is cached, so the next ask gets a real attempt. */
+    LURQ_RESOLVE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
     LURQ_SYNC_CONCURRENCY: z.ZodDefault<z.ZodNumber>;
     /** Stalest non-seed packages the daily sync refreshes on top of the seed list.
      *  This is the rotation rate for everything discovery ingested: index size /
@@ -465,6 +595,11 @@ declare const EnvSchema: z.ZodObject<{
     LURQ_RATE_LIMIT_MAX: z.ZodDefault<z.ZodNumber>;
     /** Coarser per-IP rate limit (blunts unauthenticated floods before auth). */
     LURQ_IP_RATE_LIMIT_MAX: z.ZodDefault<z.ZodNumber>;
+    /** Per-IP limit for `POST /scan/public`, the one unauthenticated route that
+     *  reads GitHub, queries the database, and queues ingestion work. The coarse
+     *  IP limit is the wrong ceiling for it: 240 scans a minute is nothing for a
+     *  JSON-RPC caller and a great deal of somebody else's GitHub budget. */
+    LURQ_SCAN_RATE_LIMIT_MAX: z.ZodDefault<z.ZodNumber>;
     /** Rate-limit window, milliseconds (applies to both limiters). */
     LURQ_RATE_LIMIT_WINDOW_MS: z.ZodDefault<z.ZodNumber>;
     /** Bearer token guarding `/metrics`. Unset → the endpoint is disabled (404). */
@@ -473,10 +608,32 @@ declare const EnvSchema: z.ZodObject<{
      *  authenticated web app presents it to mint a key for a signed-in user. Unset
      *  → the endpoint is disabled (404). Keep it server-side, never in the client. */
     LURQ_ISSUER_SECRET: z.ZodOptional<z.ZodString>;
+    /** PostHog project token (the public `phc_…` one, same as the web app's).
+     *  Set → the hosted service sends account-keyed product events (key issued,
+     *  tool called) that join the web app's identified visitors. Unset → nothing
+     *  is sent, which is every local and stdio install. */
+    LURQ_POSTHOG_KEY: z.ZodOptional<z.ZodString>;
     STRIPE_SECRET_KEY: z.ZodOptional<z.ZodString>;
     /** Signing secret for `POST /billing/webhook`. Unset → the endpoint is 404. */
     STRIPE_WEBHOOK_SECRET: z.ZodOptional<z.ZodString>;
     /** Price id backing the Pro plan. Unset → Pro cannot be checked out. */
+    /**
+     * Whether Stripe Managed Payments applies to our Checkout Sessions: Stripe as
+     * merchant of record, taking over indirect tax registration and remittance,
+     * disputes and fraud — the half `automatic_tax` alone does not buy.
+     *
+     * ALWAYS SENT, in both directions, and that is the point. Managed Payments has
+     * an account-level default (on, for accounts created since it shipped), so
+     * omitting the parameter hands the decision to a dashboard toggle instead of
+     * to config. That is action at a distance: the same deploy behaves differently
+     * per account, and the failure it produces is a 400 at the moment someone
+     * tries to pay. Sending it explicitly makes the deployment the authority.
+     *
+     * Defaults true to match the account default. Every product must carry an
+     * eligible `tax_code` (see billing/provision.ts) or Stripe rejects the session,
+     * so `false` is the one-variable escape hatch if eligibility is ever in doubt.
+     */
+    STRIPE_MANAGED_PAYMENTS: z.ZodEffects<z.ZodDefault<z.ZodEnum<["true", "false"]>>, boolean, "true" | "false" | undefined>;
     STRIPE_PRICE_PRO: z.ZodOptional<z.ZodString>;
     /** Price id backing Enterprise. Normally unset: Enterprise is sold by
      *  conversation, and `contactOnly` in core/plans.ts is what the page reads. */
@@ -503,20 +660,26 @@ declare const EnvSchema: z.ZodObject<{
     SUMMARY_PROVIDER: "openai" | "none";
     SUMMARY_MODEL: string;
     SUMMARY_BASE_URL: string;
+    LURQ_RESOLVE_CONCURRENCY: number;
+    LURQ_RESOLVE_TIMEOUT_MS: number;
     LURQ_SYNC_CONCURRENCY: number;
     LURQ_SYNC_REFRESH_CAP: number;
     LOG_LEVEL: "info" | "error" | "warn" | "debug";
     PORT: number;
     LURQ_RATE_LIMIT_MAX: number;
     LURQ_IP_RATE_LIMIT_MAX: number;
+    LURQ_SCAN_RATE_LIMIT_MAX: number;
     LURQ_RATE_LIMIT_WINDOW_MS: number;
+    STRIPE_MANAGED_PAYMENTS: boolean;
     LURQ_WEB_URL: string;
     DATABASE_URL?: string | undefined;
     GITHUB_TOKEN?: string | undefined;
     EMBEDDING_API_KEY?: string | undefined;
     SUMMARY_API_KEY?: string | undefined;
+    LURQ_NPM_CACHE_DIR?: string | undefined;
     LURQ_METRICS_TOKEN?: string | undefined;
     LURQ_ISSUER_SECRET?: string | undefined;
+    LURQ_POSTHOG_KEY?: string | undefined;
     STRIPE_SECRET_KEY?: string | undefined;
     STRIPE_WEBHOOK_SECRET?: string | undefined;
     STRIPE_PRICE_PRO?: string | undefined;
@@ -540,17 +703,23 @@ declare const EnvSchema: z.ZodObject<{
     SUMMARY_API_KEY?: string | undefined;
     SUMMARY_MODEL?: string | undefined;
     SUMMARY_BASE_URL?: string | undefined;
+    LURQ_RESOLVE_CONCURRENCY?: number | undefined;
+    LURQ_NPM_CACHE_DIR?: string | undefined;
+    LURQ_RESOLVE_TIMEOUT_MS?: number | undefined;
     LURQ_SYNC_CONCURRENCY?: number | undefined;
     LURQ_SYNC_REFRESH_CAP?: number | undefined;
     LOG_LEVEL?: "info" | "error" | "warn" | "debug" | undefined;
     PORT?: number | undefined;
     LURQ_RATE_LIMIT_MAX?: number | undefined;
     LURQ_IP_RATE_LIMIT_MAX?: number | undefined;
+    LURQ_SCAN_RATE_LIMIT_MAX?: number | undefined;
     LURQ_RATE_LIMIT_WINDOW_MS?: number | undefined;
     LURQ_METRICS_TOKEN?: string | undefined;
     LURQ_ISSUER_SECRET?: string | undefined;
+    LURQ_POSTHOG_KEY?: string | undefined;
     STRIPE_SECRET_KEY?: string | undefined;
     STRIPE_WEBHOOK_SECRET?: string | undefined;
+    STRIPE_MANAGED_PAYMENTS?: "true" | "false" | undefined;
     STRIPE_PRICE_PRO?: string | undefined;
     STRIPE_PRICE_ENTERPRISE?: string | undefined;
     LURQ_WEB_URL?: string | undefined;
@@ -592,4 +761,4 @@ declare const logger: {
 
 declare function buildProgram(): Command;
 
-export { API_KEY_PREFIX, type Advisory, type AdvisorySeverity, type BuildSignal, type BuildVerified, CACHE_TTL, CATEGORIES, type Candidate, type Category, type CategorySource, type CompatConflict, type CompatEvidence, type CompatOutput, type CompatPair, type CompatProvenance, type CompatStatus, type Confidence, type Config, ConfigError, DEFAULT_ECOSYSTEM, DEFAULT_ENDPOINT, type DependencyRanges, type DiscoverySource, type DiscoveryStatus, ECOSYSTEMS, EMBEDDING_DIM, type Ecosystem, type EvaluateOutput, type ExportKind, type ExportSymbol, FRONTEND_CATEGORIES, PACKAGE_NAME, PROVENANCE_RANK, type PeerMeta, type RiskLevel, type Runtime, SERVER_NAME, STALENESS_DAYS, type ScoreBreakdown, type SurfaceDelta, type UsageGuide, type UsageOutput, VERSION, type VerifyOutput, buildProgram, getConfig, isCategory, isFrontendCategory, loadEnv, logger, requireConfig };
+export { API_KEY_PREFIX, type Advisory, type AdvisorySeverity, type BuildSignal, type BuildVerified, CACHE_TTL, CATEGORIES, type Candidate, type Category, type CategorySource, type CompatConflict, type CompatEvidence, type CompatOutput, type CompatPair, type CompatProvenance, type CompatResolution, type CompatStatus, type Confidence, type Config, ConfigError, DEFAULT_ECOSYSTEM, DEFAULT_ENDPOINT, type DependencyRanges, type DiscoverySource, type DiscoveryStatus, ECOSYSTEMS, EMBEDDING_DIM, type Ecosystem, type EvaluateOutput, type ExportKind, type ExportSymbol, FRONTEND_CATEGORIES, PACKAGE_NAME, PROVENANCE_RANK, type PeerMeta, type RiskLevel, type Runtime, SERVER_NAME, STALENESS_DAYS, type ScoreBreakdown, type SurfaceDelta, type UsageGuide, type UsageOutput, VERSION, type VerifyOutput, buildProgram, getConfig, isCategory, isFrontendCategory, loadEnv, logger, requireConfig };