lurqrun 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -35,6 +35,16 @@ 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). */
@@ -62,13 +72,28 @@ interface CompatConflict {
     packages: string[];
     detail: string;
 }
+/** 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). */
+    witnessCount: number;
+}
 /**
  * `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[];
-    overall: 'compatible' | 'conflict' | 'unknown';
+    /** 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';
     conflicts: CompatConflict[];
     /** Packages lurq has no compatibility metadata for (counted toward `unknown`). */
     unverified: string[];
@@ -78,6 +103,51 @@ 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. */
+    evidence: CompatEvidence[];
+}
+/** 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;
+    /** Present when a `knownVersion` was supplied and both surfaces resolved. */
+    delta?: SurfaceDelta & {
+        fromVersion: string;
+    };
+    note?: string;
 }
 type AdvisorySeverity = 'critical' | 'high' | 'moderate' | 'low' | 'info';
 interface Advisory {
@@ -178,7 +248,7 @@ declare const SERVER_NAME = "lurq";
  *  Keep in sync with package.json "name". */
 declare const PACKAGE_NAME = "lurqrun";
 /** Keep in sync with package.json "version". */
-declare const VERSION = "0.0.4";
+declare const VERSION = "0.0.6";
 /** 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`. */
@@ -201,7 +271,15 @@ declare const CACHE_TTL: {
     readonly bundlephobia: number;
 };
 
-/** Load `.env` into process.env exactly once. Safe to call repeatedly. */
+/**
+ * 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>;
@@ -233,6 +311,7 @@ declare const EnvSchema: z.ZodObject<{
     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;
@@ -256,6 +335,7 @@ declare const EnvSchema: z.ZodObject<{
     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;
@@ -279,6 +359,7 @@ declare const EnvSchema: z.ZodObject<{
     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 {
@@ -309,4 +390,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 CompatOutput, type CompatStatus, type Confidence, type Config, ConfigError, DEFAULT_ENDPOINT, type DependencyRanges, type DiscoverySource, type DiscoveryStatus, EMBEDDING_DIM, type EvaluateOutput, FRONTEND_CATEGORIES, PACKAGE_NAME, type PeerMeta, type RiskLevel, type Runtime, SERVER_NAME, STALENESS_DAYS, type ScoreBreakdown, type UsageGuide, 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 CompatProvenance, type CompatStatus, type Confidence, type Config, ConfigError, DEFAULT_ENDPOINT, type DependencyRanges, type DiscoverySource, type DiscoveryStatus, EMBEDDING_DIM, 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 };