lurqrun 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+import { Command } from 'commander';
+
+/**
+ * Shared domain types and the v1 category taxonomy (§8.3).
+ * These are the stable contracts the rest of the system builds on.
+ */
+/** 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;
+/**
+ * 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). */
+type Confidence = 'proven' | 'emerging' | 'unproven';
+type Runtime = 'browser' | 'node' | 'both';
+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. */
+interface ScoreBreakdown {
+    maintenance: number;
+    adoption: number;
+    reliability: number;
+    efficiency: 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;
+    confidence: Confidence;
+    why: string;
+    latestVersion: string | null;
+    weeklyDownloads: number | null;
+    lastReleaseAt: string | null;
+    repoUrl: string | null;
+}
+/** Full evidence read for one package (§12.3.2). */
+interface EvaluateOutput {
+    dataAsOf: string;
+    stale?: boolean;
+    name: string;
+    category: Category | null;
+    healthScore: number;
+    confidence: Confidence;
+    scoreBreakdown: ScoreBreakdown;
+    latestVersion: string | null;
+    lastReleaseAt: string | null;
+    weeklyDownloads: number | null;
+    downloadGrowth90d: number | null;
+    dependentsCount: number | null;
+    scorecard: number | null;
+    bundleMinGzipKb: number | null;
+    deprecated: boolean;
+    archived: boolean;
+    advisories: Advisory[];
+    summary: string | null;
+    usageGuide: UsageGuide | null;
+    repoUrl: string | null;
+}
+/** `verify` output (§12.3.4). */
+interface VerifyOutput {
+    exists: boolean;
+    tracked: boolean;
+    deprecated: boolean;
+    archived: boolean;
+    latestVersion: string | null;
+    weeklyDownloads: number | null;
+    riskFlags: string[];
+    confidence: Confidence | null;
+    advisoryCount: number;
+}
+
+/** Static identifiers shared across the CLI and MCP server. */
+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";
+/** Keep in sync with package.json "version". */
+declare const VERSION = "0.0.1";
+/** 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. */
+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>;
+    SUMMARY_PROVIDER: z.ZodDefault<z.ZodEnum<["openai", "none"]>>;
+    SUMMARY_API_KEY: z.ZodOptional<z.ZodString>;
+    SUMMARY_MODEL: z.ZodDefault<z.ZodString>;
+    LURQ_SYNC_CONCURRENCY: z.ZodDefault<z.ZodNumber>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<["error", "warn", "info", "debug"]>>;
+}, "strip", z.ZodTypeAny, {
+    EMBEDDING_PROVIDER: "openai" | "local";
+    EMBEDDING_MODEL: string;
+    SUMMARY_PROVIDER: "openai" | "none";
+    SUMMARY_MODEL: string;
+    LURQ_SYNC_CONCURRENCY: number;
+    LOG_LEVEL: "info" | "error" | "warn" | "debug";
+    DATABASE_URL?: string | undefined;
+    GITHUB_TOKEN?: string | undefined;
+    EMBEDDING_API_KEY?: string | undefined;
+    SUMMARY_API_KEY?: string | undefined;
+}, {
+    DATABASE_URL?: string | undefined;
+    GITHUB_TOKEN?: string | undefined;
+    EMBEDDING_PROVIDER?: "openai" | "local" | undefined;
+    EMBEDDING_API_KEY?: string | undefined;
+    EMBEDDING_MODEL?: string | undefined;
+    SUMMARY_PROVIDER?: "openai" | "none" | undefined;
+    SUMMARY_API_KEY?: string | undefined;
+    SUMMARY_MODEL?: string | undefined;
+    LURQ_SYNC_CONCURRENCY?: number | undefined;
+    LOG_LEVEL?: "info" | "error" | "warn" | "debug" | 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 { type Advisory, type AdvisorySeverity, CACHE_TTL, CATEGORIES, type Candidate, type Category, type Confidence, type Config, ConfigError, EMBEDDING_DIM, type EvaluateOutput, FRONTEND_CATEGORIES, PACKAGE_NAME, type Runtime, SERVER_NAME, STALENESS_DAYS, type ScoreBreakdown, type UsageGuide, VERSION, type VerifyOutput, buildProgram, getConfig, isCategory, isFrontendCategory, loadEnv, logger, requireConfig };