lurqrun 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -1,805 +0,0 @@
-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.
- */
-/**
- * Which registry a package lives in.
- *
- * `npm` is the default everywhere — every read path defaults to it, so adding
- * this type changed no existing behaviour. What it buys is that a package name
- * is only unique WITHIN a registry: `requests`, `redis`, `click` and `attrs` all
- * exist on both npm and PyPI as entirely unrelated software, and keying on the
- * bare name would let one overwrite the other's evidence.
- *
- * PyPI names normalise before they are stored (PEP 503: `Flask`, `flask` and
- * `Flask_SQLAlchemy` are the same project); that belongs in the PyPI client at
- * the ingestion boundary, not here, so `name` always holds the canonical form.
- */
-declare const ECOSYSTEMS: readonly ["npm", "pypi"];
-type Ecosystem = (typeof ECOSYSTEMS)[number];
-/**
- * The registry every existing caller means when it doesn't say.
- *
- * Every read helper takes `ecosystem` as a DEFAULTED parameter rather than a
- * required one. That is what let the composite key land as a pure no-op: not a
- * single call site changed, and npm behaviour is bit-identical. A PyPI caller
- * passes the argument; nobody else has to care.
- *
- * ponytail: only `packages` is keyed by registry so far. These are still keyed
- * by bare package name and WILL collide once PyPI rows exist — each one is safe
- * today only because nothing writes a PyPI row yet, so scope it in the phase
- * that first makes it multi-ecosystem, not speculatively now:
- *
- *   package_versions   → needed by PyPI compat (per-version requires-dist)
- *   seed_packages      → needed when a PyPI package can join the sync roster
- *   discovery_queue    → needed by PyPI discovery (classifiers + BigQuery seed)
- *   api_surfaces,
- *   surface_queue,
- *   symbols, entities  → needed by the Python surface worker
- *   compat_edges,
- *   resolved_closures  → needed by the `uv` resolve-check
- *
- * The unscoped reads that go with them live in db/discovery.ts, db/apiSurfaces.ts
- * and pipeline/discovery.ts. Adding a PyPI write path without scoping the tables
- * it touches is how one registry starts answering for the other.
- *
- * RETRIEVAL IS THE ONE THIS DEFAULT CANNOT COVER, and it is the one that fails
- * quietly. A keyed lookup has a name to disambiguate, so a defaulted argument
- * resolves it. `search/recommend.ts` has no name — finding names IS the query —
- * so nothing here helps it, and the first PyPI row with an embedding puts
- * SQLAlchemy in the results for a TypeScript project. No error, just a wrong
- * answer. Retrieval has to take its ecosystem from the REQUEST (the repo whose
- * manifest was parsed, an explicit tool argument, or the stack the agent is
- * editing), never from a default.
- *
- * Two notes for whoever wires that up: filtering the HNSW index after the fact
- * loses recall — pre-filtered partial indexes per ecosystem keep it — and the
- * lexical `search_vector` needs the same treatment, or the hybrid's two halves
- * will disagree about which registry they are searching.
- */
-declare const DEFAULT_ECOSYSTEM: Ecosystem;
-/** Category taxonomy for the JS/TS web stack (§8.3). `other` is the fallback. */
-declare const CATEGORIES: readonly ["framework", "meta-framework", "state-management", "routing", "orm", "database-client", "ui-component-library", "styling", "forms", "validation", "data-fetching", "http-client", "auth", "testing", "build-tool", "bundler", "linting", "date-time", "animation", "charts", "i18n", "utility", "other"];
-type Category = (typeof CATEGORIES)[number];
-declare function isCategory(value: string): value is Category;
-/** Provenance of a package's stored category (§2A). `curated` comes from the
- *  seed file or a manual arg; `inferred` was assigned automatically at ingest
- *  and is safe for a later curation pass to override. */
-type CategorySource = 'curated' | 'inferred';
-/** How a candidate entered the discovery queue (§2B). `dependency-graph` and
- *  `recent` are the long-tail channels; `category-search` is keyword-seeded;
- *  `reactive` is an on-demand query that wasn't tracked yet. */
-type DiscoverySource = 'dependency-graph' | 'category-search' | 'recent' | 'reactive'
-/** Seen on npm's `_changes` replication feed — a name we had never heard of. */
- | 'npm-changes';
-/** Lifecycle of a discovery-queue candidate (§2B). */
-/**
- * `rejected` means the merit gate said no — a verdict about the package, and
- * permanent. `failed` means ingest itself kept throwing, which is a verdict
- * about us, and is cleared by re-queueing once the bug is fixed. Conflating the
- * two would either retry genuine rejects forever or bury a fixable bug.
- */
-type DiscoveryStatus = 'pending' | 'ingested' | 'rejected' | 'failed';
-/**
- * Categories for which bundle size is meaningful and Bundlephobia is consulted
- * (§9.5). Backend-only categories get a null bundle size, and their efficiency
- * weight is redistributed (§10, see scoring).
- */
-declare const FRONTEND_CATEGORIES: readonly ["ui-component-library", "styling", "state-management", "forms", "validation", "data-fetching", "charts", "animation", "date-time", "utility"];
-declare function isFrontendCategory(category: Category | null | undefined): boolean;
-/**
- * Evidence-trustworthiness label, independent of the numeric score (§10, §1).
- * Two-dimensional: `proven`/`emerging` are adoption ladders; `promising` is
- * adoption-independent (high intrinsic quality, new package).
- */
-type Confidence = 'proven' | 'emerging' | 'promising' | 'unproven';
-type Runtime = 'browser' | 'node' | 'both';
-/** Result of co-installing two package versions in the sandbox (compat matrix). */
-type CompatStatus = 'compatible' | 'conflict';
-/**
- * Evidence class behind a compat edge (§3, §4B). Ordered weakest→strongest for
- * upsert precedence: a mined `observed` must never overwrite a sandbox `verified`
- * or `conflict`. `declared` = Tier-0 peer/engine semver; `observed` = co-resolved
- * in N real dependency graphs; `verified` = sandbox co-install passed; `conflict`
- * = declared conflict or a sandbox co-install failed.
- */
-type CompatProvenance = 'declared' | 'observed' | 'verified' | 'conflict';
-/** Upsert precedence: higher wins, so mining can't erase a proven verdict. */
-declare const PROVENANCE_RANK: Record<CompatProvenance, number>;
-/** Coarse post-install result an agent reports back via `report_outcome` — never
- *  source code, just whether the recommended package installed / compiled /
- *  passed tests, or failed. Feeds the recommendation→outcome flywheel (§3.1). */
-type BuildSignal = 'installed' | 'compiled' | 'tests_passed' | 'failed';
-/** Sandbox verdict surfaced to agents: did this version actually install + load? */
-interface BuildVerified {
-    version: string;
-    installed: boolean;
-    loaded: boolean | null;
-    driver: string;
-    ranAt: string;
-}
-/** A map of dependency/peer/engine name → semver range (from a manifest). */
-type DependencyRanges = Record<string, string>;
-/** `peerDependenciesMeta`: per-peer flags, notably `{ optional: true }`. */
-type PeerMeta = Record<string, {
-    optional?: boolean;
-}>;
-/** One incompatibility found across a set of packages. */
-interface CompatConflict {
-    /** Where the conflict came from. `peer-deps`/`engines` are Tier-1 (metadata,
-     *  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;
-    /** The same fact as `detail`, structured, so a consumer can lay it out without
-     *  parsing prose. Present on peer-range violations; absent for engine and
-     *  sandbox conflicts, which aren't about a single declared range. */
-    requirement?: {
-        /** The peer being asked for. */
-        peer: string;
-        /** The range the requirer declares. */
-        range: string;
-        /** What the set actually resolves that peer to, when it is in the set. */
-        resolved: string | null;
-    };
-}
-/**
- * One unordered pair among the checked members.
- *
- * A verdict belongs to a pair, not to a package: the same package can sit in a
- * held pair and a conflicting one, so grading packages would either contradict
- * itself or paint the whole set red. `held` means no declared constraint between
- * the two was violated — it does not mean the pair was executed. Nothing here
- * has been executed.
- */
-interface CompatPair {
-    a: string;
-    b: string;
-    status: 'held' | 'conflict';
-    /** Only on `conflict` — the conflict's own detail string. */
-    detail?: string;
-    /** Only on `conflict`, and only for peer-range violations. */
-    requirement?: CompatConflict['requirement'];
-}
-/** One stored compat edge surfaced to agents, with its evidence class (§4B). */
-interface CompatEvidence {
-    packages: [string, string];
-    versions: [string, string];
-    status: CompatStatus;
-    provenance: CompatProvenance;
-    /** Distinct resolved graphs an `observed` edge was witnessed in (0 otherwise).
-     *  Only a newly-fetched closure accrues one; the daily re-mine re-reads closures
-     *  it has already counted and deliberately does not. NOTE: rows minted before
-     *  that fix carry an inflated count (one per sync run, ~16× on average) and are
-     *  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[];
-    /** 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[];
-    /** The exact members the check ran over, name + resolved version. Versions are
-     *  always surfaced here, and the structure is stable for later scraping. */
-    checked: {
-        name: string;
-        version: string | null;
-    }[];
-    /** 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
-     *  failures. */
-    pairs: CompatPair[];
-}
-/** Kind of an exported symbol, from its `.d.ts` declaration. */
-type ExportKind = 'function' | 'class' | 'interface' | 'type' | 'enum' | 'variable' | 'namespace' | 'unknown';
-/** One normalized exported symbol of a package version's public API surface. */
-interface ExportSymbol {
-    name: string;
-    kind: ExportKind;
-    /** Single-line normalized signature (params/return for functions, etc.), or
-     *  null when the declaration carries no useful signature. */
-    signature: string | null;
-}
-/** What changed between two API surfaces (§4D). Deltas are computed, not guessed. */
-interface SurfaceDelta {
-    added: ExportSymbol[];
-    removed: ExportSymbol[];
-    /** A symbol that disappeared and a near-identical one that appeared — inferred
-     *  by signature similarity, so an agent sees a rename, not remove+add. */
-    renamed: {
-        from: ExportSymbol;
-        to: ExportSymbol;
-    }[];
-    /** Same name, changed signature. */
-    changed: {
-        name: string;
-        before: string | null;
-        after: string | null;
-    }[];
-}
-/** `usage` tool output: version-exact API surface + optional delta from a known
- *  version the agent was trained/working on (§4D). */
-interface UsageOutput {
-    package: string;
-    version: string | null;
-    /** Extracted export list, or null when types are unavailable (falls back to
-     *  the README, which is already fetched). */
-    surface: ExportSymbol[] | null;
-    available: boolean;
-    /** Declared `engines` for this exact version (e.g. `{ node: ">=20" }`), or null
-     *  when the manifest declares none. Independent of `available` — the runtime
-     *  floor matters even for untyped packages. */
-    engines: Record<string, string> | null;
-    /** Present when a `knownVersion` was supplied and both surfaces resolved. */
-    delta?: SurfaceDelta & {
-        fromVersion: string;
-    };
-    /** Echo of a requested version the registry has never published. A structured
-     *  flag as well as prose, so an agent can branch on "this release does not
-     *  exist" without parsing `note` — it is a different answer from "we have no
-     *  surface for it yet", and only one of the two means stop. */
-    unpublishedVersion?: string;
-    /** Why a requested `knownVersion` delta is absent. Only set when one was asked
-     *  for and could not be produced — silence about a requested comparison reads
-     *  as "no changes", which is the one thing it never means. */
-    deltaNote?: string;
-    note?: string;
-}
-type AdvisorySeverity = 'critical' | 'high' | 'moderate' | 'low' | 'info';
-interface Advisory {
-    id: string;
-    severity: AdvisorySeverity;
-    summary: string;
-}
-/** Sub-scores composing the health score (§10). `efficiency` is null when not
- *  size-based (backend categories) — its weight is redistributed.
- *  `quality` (§1) is a standalone, adoption-independent axis — it does NOT feed
- *  the health composite; it blends with health only at ranking time. Null when
- *  no manifest signals were available. */
-interface ScoreBreakdown {
-    maintenance: number;
-    adoption: number;
-    reliability: number;
-    efficiency: number | null;
-    quality: number | null;
-    /**
-     * Field evidence (§3.1) — how this package actually fared after agents
-     * installed it, from `recommendation_outcomes`. `null` means no reports yet
-     * and the weight is redistributed, exactly like `efficiency`.
-     *
-     * Optional rather than required because it postdates the rows already in
-     * `packages.score_breakdown`: a stored breakdown from before this shipped
-     * decodes with the key absent, and `undefined` must read as "no evidence",
-     * never as 0. Treating it as 0 would drop every un-reported package's health
-     * the moment this deployed.
-     */
-    field?: number | null;
-}
-/**
- * Structured usage guide generated at ingest (product refinement: lurq explains,
- * not just ranks). Grounded in the package README/description — never fabricated.
- * Exact current API specifics are deferred to Context7 via `context7Hint`.
- */
-interface UsageGuide {
-    whatItIs: string;
-    whenToUse: string;
-    whenNotToUse?: string;
-    whereItFits: string;
-    howToWireIn?: string;
-    context7Hint?: string;
-}
-/** A single recommendation candidate (§12.3.1). Intentionally compact. */
-interface Candidate {
-    name: string;
-    category: Category | null;
-    healthScore: number;
-    qualityScore: number | null;
-    confidence: Confidence;
-    why: string;
-    latestVersion: string | null;
-    weeklyDownloads: number | null;
-    lastReleaseAt: string | null;
-    repoUrl: string | null;
-    /**
-     * The three facts that can reverse an install decision on their own.
-     *
-     * `recommend` is the call an agent makes *before* choosing a dependency, and
-     * it carried none of them: a deprecated package could be returned with nothing
-     * in the payload saying so, leaving `confidence` and a numeric score as the
-     * only hints. Deprecation caps the maintenance component and bars `proven`,
-     * but a low score reads as "less good", not "do not install this". `evaluate`
-     * and `verify` have always carried these; the tool most likely to precede an
-     * install should not be the one that hides them.
-     *
-     * Emitted even when false/zero — see mcp/compact, which keeps both on purpose,
-     * so an agent never has to read meaning into an absent field.
-     */
-    deprecated: boolean;
-    archived: boolean;
-    advisories: number;
-}
-/** Full evidence read for one package (§12.3.2). */
-interface EvaluateOutput {
-    dataAsOf: string;
-    stale?: boolean;
-    name: string;
-    category: Category | null;
-    healthScore: number;
-    qualityScore: number | null;
-    confidence: Confidence;
-    scoreBreakdown: ScoreBreakdown;
-    latestVersion: string | null;
-    lastReleaseAt: string | null;
-    weeklyDownloads: number | null;
-    downloadGrowth90d: number | null;
-    scorecard: number | null;
-    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;
-    repoUrl: string | null;
-    /** If this package is superseded, the recommended migration target (§1.2). */
-    replacedBy?: {
-        name: string;
-        reason: string;
-    } | null;
-    /** Latest sandbox verdict for this package, if one has been run. */
-    buildVerified?: BuildVerified | null;
-}
-/** `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;
-    deprecated: boolean;
-    archived: boolean;
-    latestVersion: string | null;
-    weeklyDownloads: number | null;
-    riskFlags: string[];
-    /** Overall supply-chain risk, rolled up from riskFlags. */
-    risk: RiskLevel;
-    /** Suspected typosquat target — a popular package this name closely mimics. */
-    typosquatOf: string | null;
-    confidence: Confidence | null;
-    /** 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";
-/** Published npm package name (the CLI command and MCP nickname stay `lurq`).
- *  Keep in sync with package.json "name". */
-declare const PACKAGE_NAME = "lurqrun";
-/**
- * Read from package.json rather than restated, so a release bump cannot leave
- * it behind. This used to be a literal under a "keep in sync" comment, and it
- * drifted the moment someone bumped package.json alone: 0.0.9 shipped to npm
- * announcing itself as 0.0.8.
- *
- * That is not only cosmetic. github/workflow.ts defaults `cliSpec()` to this
- * value and bakes it into the `npx lurqrun@<v>` line of every workflow lurq
- * generates, so a stale constant writes users a CI job pinned to a version
- * other than the one that wrote it.
- *
- * The import is resolved at build time — esbuild inlines the JSON, so there is
- * no file read at runtime and no dependence on where the bundle sits on disk.
- * That last part is why this is an import and not a `readFileSync` of a path
- * relative to `import.meta.url`: the public bin lands at dist/bin/lurq.js and
- * the library entry at dist/index.js, so any relative path correct for one is
- * wrong for the other.
- */
-declare const VERSION: string;
-/** Default hosted endpoint the install wizard writes into agent configs. The
- *  marketing site is `lurq.run`; the MCP service lives on the `api.` subdomain.
- *  Overridable per-invocation with `lurq install --url …` or `LURQ_ENDPOINT`. */
-declare const DEFAULT_ENDPOINT = "https://api.lurq.run/mcp";
-/** Prefix for issued API keys (the rest is high-entropy random). */
-declare const API_KEY_PREFIX = "lurq_live_";
-/** Embedding vector dimensionality (OpenAI text-embedding-3-small). The local
- *  fallback embedder produces vectors of the same length so the DB column and
- *  pgvector index never need to change. */
-declare const EMBEDDING_DIM = 1536;
-/** A package row is flagged `stale: true` in tool responses once its data is
- *  older than this (§17). */
-declare const STALENESS_DAYS = 7;
-/** Per-source persistent-cache TTLs (§17). */
-declare const CACHE_TTL: {
-    readonly npmRegistry: number;
-    readonly npmDownloads: number;
-    readonly github: number;
-    readonly depsDev: number;
-    readonly bundlephobia: number;
-};
-
-/**
- * Load env into process.env exactly once. Safe to call repeatedly.
- *
- * Layering: if `LURQ_ENV_FILE` is set (e.g. `.env.production`), that file loads
- * *first* so its values win, then `.env` fills in the rest (dotenv never
- * overrides an already-set key). This is how the explicit prod path works —
- * `LURQ_ENV_FILE=.env.production` supplies the prod DATABASE_URL while `.env`
- * still provides shared secrets — without prod ever being the ambient default.
- */
-declare function loadEnv(): void;
-declare const EnvSchema: z.ZodObject<{
-    DATABASE_URL: z.ZodOptional<z.ZodString>;
-    GITHUB_TOKEN: z.ZodOptional<z.ZodString>;
-    EMBEDDING_PROVIDER: z.ZodDefault<z.ZodEnum<["openai", "local"]>>;
-    EMBEDDING_API_KEY: z.ZodOptional<z.ZodString>;
-    EMBEDDING_MODEL: z.ZodDefault<z.ZodString>;
-    EMBEDDING_BASE_URL: z.ZodDefault<z.ZodString>;
-    SUMMARY_PROVIDER: z.ZodDefault<z.ZodEnum<["openai", "none"]>>;
-    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 /
-     *  this = days to come all the way around. Raise it if the sync finishes well
-     *  inside the cron window; lower it if npm starts rate-limiting. 0 disables
-     *  the rotation (seeds only, the pre-rotation behaviour).
-     *
-     *  It is also the discovery frontier's clock, which is why it is not a small
-     *  number. `graphChannel` re-expands a package only when its `latest_version`
-     *  moves, and nothing observes a version move except this rotation — so at 400
-     *  against a 20.8k index the graph channel could only re-arm on a 52-day lag
-     *  and had gone effectively silent. */
-    LURQ_SYNC_REFRESH_CAP: z.ZodDefault<z.ZodNumber>;
-    LOG_LEVEL: z.ZodDefault<z.ZodEnum<["error", "warn", "info", "debug"]>>;
-    PORT: z.ZodDefault<z.ZodNumber>;
-    /** Per-API-key rate limit: max requests per window. */
-    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). */
-    LURQ_METRICS_TOKEN: z.ZodOptional<z.ZodString>;
-    /** Shared secret for self-serve key issuance (`POST /keys`). The Clerk-
-     *  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>;
-    /** Resend API key for account email: urgent alerts and the opt-in weekly
-     *  summary. Unset → nothing is sent; the dashboard and CLI still show all of it. */
-    RESEND_API_KEY: z.ZodOptional<z.ZodString>;
-    /** Sender, on a Resend-verified domain. */
-    LURQ_MAIL_FROM: z.ZodDefault<z.ZodString>;
-    /** Clerk secret key, used only to read a recipient's verified primary email at
-     *  send time — lurq stores no email addresses. Unset → nothing is sent. */
-    CLERK_SECRET_KEY: z.ZodOptional<z.ZodString>;
-    /** 32 random bytes, base64 (`openssl rand -base64 32`). Encrypts stored
-     *  Slack/Discord/Teams/webhook URLs, which are credentials. Unset → alert
-     *  channels are disabled rather than stored in the clear. */
-    LURQ_SECRETS_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>;
-    /** Per-seat Price id backing Team. The subscription quantity is the seat count. */
-    STRIPE_PRICE_TEAM: z.ZodOptional<z.ZodString>;
-    /** Yearly Price ids, 20% under twelve months (core/plans ANNUAL_DISCOUNT). */
-    STRIPE_PRICE_PRO_ANNUAL: z.ZodOptional<z.ZodString>;
-    STRIPE_PRICE_TEAM_ANNUAL: z.ZodOptional<z.ZodString>;
-    /** Metered Price billed from the overage meter, attached to monthly Team. */
-    STRIPE_PRICE_TEAM_OVERAGE: 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. */
-    STRIPE_PRICE_ENTERPRISE: z.ZodOptional<z.ZodString>;
-    /** Absolute base URL the checkout returns to, e.g. https://lurq.run. */
-    LURQ_WEB_URL: z.ZodDefault<z.ZodString>;
-    /** Numeric App ID from the GitHub App settings page. */
-    LURQ_GITHUB_APP_ID: z.ZodOptional<z.ZodString>;
-    /** PEM private key. Accepts literal newlines or `\n` escapes (Railway/Vercel). */
-    LURQ_GITHUB_APP_PRIVATE_KEY: z.ZodOptional<z.ZodString>;
-    /** Webhook secret from the same App settings page, so repo changes made on
-     *  GitHub reach us. Unset → `POST /github/webhook` is disabled (404): an
-     *  unverified webhook is an open write endpoint, so no secret means no route. */
-    LURQ_GITHUB_WEBHOOK_SECRET: z.ZodOptional<z.ZodString>;
-    LURQ_ENDPOINT: z.ZodOptional<z.ZodString>;
-    LURQ_API_KEY: z.ZodOptional<z.ZodString>;
-    E2B_API_KEY: z.ZodOptional<z.ZodString>;
-    E2B_TEMPLATE: z.ZodOptional<z.ZodString>;
-    USE_LIVE_API: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    EMBEDDING_PROVIDER: "openai" | "local";
-    EMBEDDING_MODEL: string;
-    EMBEDDING_BASE_URL: string;
-    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;
-    LURQ_MAIL_FROM: string;
-    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;
-    RESEND_API_KEY?: string | undefined;
-    CLERK_SECRET_KEY?: string | undefined;
-    LURQ_SECRETS_KEY?: string | undefined;
-    STRIPE_SECRET_KEY?: string | undefined;
-    STRIPE_WEBHOOK_SECRET?: string | undefined;
-    STRIPE_PRICE_PRO?: string | undefined;
-    STRIPE_PRICE_TEAM?: string | undefined;
-    STRIPE_PRICE_PRO_ANNUAL?: string | undefined;
-    STRIPE_PRICE_TEAM_ANNUAL?: string | undefined;
-    STRIPE_PRICE_TEAM_OVERAGE?: string | undefined;
-    STRIPE_PRICE_ENTERPRISE?: string | undefined;
-    LURQ_GITHUB_APP_ID?: string | undefined;
-    LURQ_GITHUB_APP_PRIVATE_KEY?: string | undefined;
-    LURQ_GITHUB_WEBHOOK_SECRET?: string | undefined;
-    LURQ_ENDPOINT?: string | undefined;
-    LURQ_API_KEY?: string | undefined;
-    E2B_API_KEY?: string | undefined;
-    E2B_TEMPLATE?: string | undefined;
-    USE_LIVE_API?: string | undefined;
-}, {
-    DATABASE_URL?: string | undefined;
-    GITHUB_TOKEN?: string | undefined;
-    EMBEDDING_PROVIDER?: "openai" | "local" | undefined;
-    EMBEDDING_API_KEY?: string | undefined;
-    EMBEDDING_MODEL?: string | undefined;
-    EMBEDDING_BASE_URL?: string | undefined;
-    SUMMARY_PROVIDER?: "openai" | "none" | undefined;
-    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;
-    RESEND_API_KEY?: string | undefined;
-    LURQ_MAIL_FROM?: string | undefined;
-    CLERK_SECRET_KEY?: string | undefined;
-    LURQ_SECRETS_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_TEAM?: string | undefined;
-    STRIPE_PRICE_PRO_ANNUAL?: string | undefined;
-    STRIPE_PRICE_TEAM_ANNUAL?: string | undefined;
-    STRIPE_PRICE_TEAM_OVERAGE?: string | undefined;
-    STRIPE_PRICE_ENTERPRISE?: string | undefined;
-    LURQ_WEB_URL?: string | undefined;
-    LURQ_GITHUB_APP_ID?: string | undefined;
-    LURQ_GITHUB_APP_PRIVATE_KEY?: string | undefined;
-    LURQ_GITHUB_WEBHOOK_SECRET?: string | undefined;
-    LURQ_ENDPOINT?: string | undefined;
-    LURQ_API_KEY?: string | undefined;
-    E2B_API_KEY?: string | undefined;
-    E2B_TEMPLATE?: string | undefined;
-    USE_LIVE_API?: string | undefined;
-}>;
-type Config = z.infer<typeof EnvSchema>;
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-/** Parse + validate the environment. Throws ConfigError on malformed values. */
-declare function getConfig(): Config;
-/**
- * Return the config but fail fast if any of the named required keys are absent.
- * Use in command handlers that genuinely need them (e.g. sync needs DATABASE_URL).
- */
-declare function requireConfig<K extends keyof Config>(keys: K[]): Config;
-
-declare const logger: {
-    error: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    info: (...args: unknown[]) => void;
-    debug: (...args: unknown[]) => void;
-};
-
-/**
- * CLI command wiring (§13). Built with commander. Each command mirrors an MCP
- * tool or an operational task. Handlers are filled in across milestones M1–M7;
- * the command/option surface here is the final, stable shape.
- *
- * Every command supports `--json` for machine-readable output.
- */
-
-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 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 };