ragcode-context-engine 0.1.0

package/dist/src/cli/update.js

@@ -0,0 +1,111 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createRequire } from "node:module";
+const execFileAsync = promisify(execFile);
+// `ragcode update` upgrades the globally-installed CLI in place. We don't bundle an auto-updater;
+// we shell out to the package manager that owns the global install. The published package name is
+// `ragcode-context-engine` (see package.json), which is what npm/pnpm/yarn install globally.
+export const PACKAGE_NAME = "ragcode-context-engine";
+function currentVersion() {
+    // The package.json depth differs between source (src/cli/update.ts -> ../../package.json) and the
+    // built layout (dist/src/cli/update.js -> ../../../package.json), so try both rather than guessing.
+    const require = createRequire(import.meta.url);
+    for (const candidate of ["../../package.json", "../../../package.json"]) {
+        try {
+            const pkg = require(candidate);
+            if (pkg.name === PACKAGE_NAME && pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return "unknown";
+}
+// Auto-detect the package manager from the npm_config_user_agent the parent PM exposes, falling
+// back to npm. This keeps a pnpm-global install from being "updated" by npm into a broken state.
+function detectPackageManager(env = process.env) {
+    const agent = env.npm_config_user_agent ?? "";
+    if (agent.startsWith("pnpm"))
+        return "pnpm";
+    if (agent.startsWith("yarn"))
+        return "yarn";
+    return "npm";
+}
+async function fetchLatestVersion() {
+    // `npm view` works even under pnpm/yarn since npm is virtually always present; if it's not,
+    // the catch downgrades us to a best-effort install without a pre-check.
+    try {
+        const { stdout } = await execFileAsync("npm", ["view", PACKAGE_NAME, "version"]);
+        const version = stdout.trim();
+        return version.length > 0 ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function installArgv(pm, spec) {
+    switch (pm) {
+        case "pnpm":
+            return { file: "pnpm", args: ["add", "-g", spec] };
+        case "yarn":
+            return { file: "yarn", args: ["global", "add", spec] };
+        default:
+            return { file: "npm", args: ["install", "-g", spec] };
+    }
+}
+export async function runUpdate(options = {}) {
+    const current = currentVersion();
+    const pm = options.packageManager ?? detectPackageManager();
+    const target = options.version ?? "latest";
+    const latest = target === "latest" ? await fetchLatestVersion() : target;
+    const upToDate = Boolean(latest && latest === current);
+    if (options.checkOnly) {
+        return {
+            ok: true,
+            currentVersion: current,
+            latestVersion: latest,
+            upToDate,
+            installed: false,
+            message: latest
+                ? upToDate
+                    ? `RagCode is up to date (${current}).`
+                    : `Update available: ${current} → ${latest}. Run \`ragcode update\` to install.`
+                : `Installed version ${current}. Could not reach the registry to check for updates.`
+        };
+    }
+    if (upToDate) {
+        return {
+            ok: true,
+            currentVersion: current,
+            latestVersion: latest,
+            upToDate: true,
+            installed: false,
+            message: `RagCode is already up to date (${current}).`
+        };
+    }
+    const spec = `${PACKAGE_NAME}@${target}`;
+    const { file, args } = installArgv(pm, spec);
+    try {
+        await execFileAsync(file, args);
+        return {
+            ok: true,
+            currentVersion: current,
+            latestVersion: latest,
+            upToDate: false,
+            installed: true,
+            message: `Updated RagCode via ${pm} (${current} → ${latest ?? target}). Restart any running watchers and MCP clients to pick up the new version.`
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            ok: false,
+            currentVersion: current,
+            latestVersion: latest,
+            upToDate: false,
+            installed: false,
+            message: `Update via ${pm} failed: ${(err.stderr ?? err.message ?? "").trim()}. You can update manually with \`${file} ${args.join(" ")}\`.`
+        };
+    }
+}

package/dist/src/config/dotenv.d.ts

@@ -0,0 +1 @@
+export declare function loadDotEnv(cwd?: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/src/config/dotenv.js

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseEnv } from "node:util";
+export function loadDotEnv(cwd = process.cwd(), env = process.env) {
+    const filePath = path.join(cwd, ".env");
+    if (!fs.existsSync(filePath))
+        return env;
+    const parsed = parseEnv(fs.readFileSync(filePath, "utf8"));
+    for (const [key, value] of Object.entries(parsed)) {
+        if (env[key] === undefined)
+            env[key] = value;
+    }
+    return env;
+}

package/dist/src/config/graph-runtime.d.ts

@@ -0,0 +1,13 @@
+import type { GraphStore } from "../core/contracts.js";
+export type GraphStoreKind = "memory" | "sqlite";
+export interface GraphRuntimeConfig {
+    graphStore: GraphStoreKind;
+    sqlitePath: string;
+}
+export interface GraphRuntimeComponents {
+    graphStore: GraphStore;
+    config: GraphRuntimeConfig;
+}
+export declare function createGraphRuntimeFromEnv(env?: NodeJS.ProcessEnv, cwd?: string): GraphRuntimeComponents;
+export declare function createGraphRuntimeFromConfig(config: GraphRuntimeConfig): GraphRuntimeComponents;
+export declare function readGraphRuntimeConfig(env?: NodeJS.ProcessEnv, cwd?: string): GraphRuntimeConfig;

package/dist/src/config/graph-runtime.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+import { InMemoryGraphStore } from "../graph/in-memory-graph-store.js";
+import { SQLiteGraphStore } from "../graph/sqlite-graph-store.js";
+export function createGraphRuntimeFromEnv(env = process.env, cwd = process.cwd()) {
+    const config = readGraphRuntimeConfig(env, cwd);
+    return createGraphRuntimeFromConfig(config);
+}
+export function createGraphRuntimeFromConfig(config) {
+    if (config.graphStore === "memory") {
+        return { graphStore: new InMemoryGraphStore(), config };
+    }
+    fs.mkdirSync(path.dirname(config.sqlitePath), { recursive: true });
+    return { graphStore: new SQLiteGraphStore(config.sqlitePath), config };
+}
+export function readGraphRuntimeConfig(env = process.env, cwd = process.cwd()) {
+    const graphStore = enumValue(env.RAGCODE_GRAPH_STORE, ["memory", "sqlite"], "memory");
+    return {
+        graphStore,
+        sqlitePath: env.RAGCODE_SQLITE_PATH ?? path.join(cwd, ".ragcode", "graph.sqlite")
+    };
+}
+function enumValue(value, allowed, fallback) {
+    if (!value)
+        return fallback;
+    if (allowed.includes(value))
+        return value;
+    throw new Error(`Invalid graph runtime value "${value}". Expected one of: ${allowed.join(", ")}.`);
+}

package/dist/src/config/runtime-config.d.ts

@@ -0,0 +1,87 @@
+import type { GraphStore } from "../core/contracts.js";
+import type { EmbeddingProvider, SemanticStore } from "../core/contracts.js";
+import { type GraphRuntimeConfig } from "./graph-runtime.js";
+import { type SemanticRuntimeConfig } from "./semantic-runtime.js";
+export interface RuntimeConfigFile {
+    graphStore?: string;
+    sqlitePath?: string;
+    semanticStore?: string;
+    lancedbUri?: string;
+    lanceDbUri?: string;
+    lancedbTable?: string;
+    lanceDbTableName?: string;
+    embeddingProvider?: string;
+    embeddingBaseUrl?: string;
+    embeddingApiKey?: string;
+    embeddingModel?: string;
+    embeddingDimensions?: number | string;
+    embeddingRequestDimensions?: boolean | string;
+    embeddingBatchSize?: number | string;
+    embeddingConcurrency?: number | string;
+    semanticMaxChunks?: number | string;
+}
+export interface RuntimeConfigOverrides extends RuntimeConfigFile {
+    repoRoot?: string;
+}
+export interface RuntimeConfig {
+    repoRoot: string;
+    configPath: string;
+    graph: GraphRuntimeConfig;
+    semantic: SemanticRuntimeConfig;
+    embeddingApiKey?: string;
+    sources: Record<string, "override" | "env" | "config" | "default">;
+}
+export interface RuntimeComponents {
+    graphStore: GraphStore;
+    semanticStore: SemanticStore;
+    embeddingProvider: EmbeddingProvider;
+    config: RuntimeConfig;
+}
+export interface RedactedRuntimeConfig {
+    repoRoot: string;
+    configPath: string;
+    graphStore: RuntimeConfig["graph"]["graphStore"];
+    sqlitePath: string;
+    semanticStore: RuntimeConfig["semantic"]["semanticStore"];
+    lancedbUri?: string;
+    lanceDbTableName: string;
+    embeddingProvider: RuntimeConfig["semantic"]["embeddingProvider"];
+    embeddingBaseUrl?: string;
+    embeddingModel?: string;
+    embeddingDimensions?: number;
+    embeddingRequestDimensions: boolean;
+    embeddingBatchSize: number;
+    embeddingConcurrency: number;
+    semanticMaxChunks?: number;
+    embeddingApiKey: "set" | "unset" | "redacted";
+    sources: RuntimeConfig["sources"];
+}
+export declare const DEFAULT_RUNTIME_CONFIG: {
+    readonly graphStore: "sqlite";
+    readonly sqlitePath: string;
+    readonly semanticStore: "lancedb";
+    readonly lancedbUri: string;
+    readonly lanceDbTableName: "code_chunks";
+    readonly embeddingProvider: "deterministic";
+    readonly embeddingBaseUrl: "https://api.openai.com/v1";
+    readonly embeddingBatchSize: 64;
+    readonly embeddingConcurrency: 1;
+    readonly embeddingRequestDimensions: false;
+};
+export declare function loadRuntimeConfig(options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    overrides?: RuntimeConfigOverrides;
+}): RuntimeConfig;
+export declare function createRuntimeComponents(config: RuntimeConfig): RuntimeComponents;
+export declare function createRuntimeComponentsForRepo(options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    overrides?: RuntimeConfigOverrides;
+}): RuntimeComponents;
+export declare function writeRuntimeConfigFile(repoRoot: string, config: RuntimeConfigFile): string;
+export declare function runtimeConfigToEnv(config: RuntimeConfig, options?: {
+    includeSecrets?: boolean;
+}): Record<string, string>;
+export declare function redactRuntimeConfig(config: RuntimeConfig): RedactedRuntimeConfig;
+export declare function readRuntimeConfigFile(configPath: string): RuntimeConfigFile;

package/dist/src/config/runtime-config.js

@@ -0,0 +1,215 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createGraphRuntimeFromConfig } from "./graph-runtime.js";
+import { createSemanticRuntimeFromConfig } from "./semantic-runtime.js";
+export const DEFAULT_RUNTIME_CONFIG = {
+    graphStore: "sqlite",
+    sqlitePath: path.join(".ragcode", "graph.sqlite"),
+    semanticStore: "lancedb",
+    lancedbUri: path.join(".ragcode", "lancedb"),
+    lanceDbTableName: "code_chunks",
+    embeddingProvider: "deterministic",
+    embeddingBaseUrl: "https://api.openai.com/v1",
+    embeddingBatchSize: 64,
+    embeddingConcurrency: 1,
+    embeddingRequestDimensions: false
+};
+const CONFIG_FILE_NAME = path.join(".ragcode", "config.json");
+export function loadRuntimeConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const repoRoot = path.resolve(options.overrides?.repoRoot ?? env.RAGCODE_REPO_ROOT ?? options.cwd ?? process.cwd());
+    const configPath = path.join(repoRoot, CONFIG_FILE_NAME);
+    const fileConfig = readRuntimeConfigFile(configPath);
+    const sources = {};
+    const graphStore = selectString("graphStore", options.overrides?.graphStore, env.RAGCODE_GRAPH_STORE, fileConfig.graphStore, DEFAULT_RUNTIME_CONFIG.graphStore, sources);
+    const sqlitePath = resolveRepoPath(repoRoot, selectString("sqlitePath", options.overrides?.sqlitePath, env.RAGCODE_SQLITE_PATH, fileConfig.sqlitePath, DEFAULT_RUNTIME_CONFIG.sqlitePath, sources));
+    const semanticStore = selectString("semanticStore", options.overrides?.semanticStore, env.RAGCODE_SEMANTIC_STORE, fileConfig.semanticStore, DEFAULT_RUNTIME_CONFIG.semanticStore, sources);
+    const lanceDbUri = resolveRepoPath(repoRoot, selectString("lancedbUri", options.overrides?.lancedbUri ?? options.overrides?.lanceDbUri, env.RAGCODE_LANCEDB_URI, fileConfig.lancedbUri ?? fileConfig.lanceDbUri, DEFAULT_RUNTIME_CONFIG.lancedbUri, sources));
+    const lanceDbTableName = selectString("lanceDbTableName", options.overrides?.lanceDbTableName ?? options.overrides?.lancedbTable, env.RAGCODE_LANCEDB_TABLE, fileConfig.lanceDbTableName ?? fileConfig.lancedbTable, DEFAULT_RUNTIME_CONFIG.lanceDbTableName, sources);
+    const embeddingProvider = normalizeEmbeddingProvider(selectString("embeddingProvider", options.overrides?.embeddingProvider, env.RAGCODE_EMBEDDING_PROVIDER, fileConfig.embeddingProvider, DEFAULT_RUNTIME_CONFIG.embeddingProvider, sources));
+    const embeddingBaseUrl = selectString("embeddingBaseUrl", options.overrides?.embeddingBaseUrl, env.RAGCODE_EMBEDDING_BASE_URL, fileConfig.embeddingBaseUrl, DEFAULT_RUNTIME_CONFIG.embeddingBaseUrl, sources);
+    const embeddingApiKey = selectOptionalString("embeddingApiKey", options.overrides?.embeddingApiKey, env.RAGCODE_EMBEDDING_API_KEY ?? env.OPENAI_API_KEY, fileConfig.embeddingApiKey, sources);
+    const embeddingModel = selectOptionalString("embeddingModel", options.overrides?.embeddingModel, env.RAGCODE_EMBEDDING_MODEL, fileConfig.embeddingModel, sources)
+        ?? (embeddingProvider === "openai-compatible" ? "text-embedding-3-small" : undefined);
+    const embeddingDimensions = selectOptionalPositiveInteger("embeddingDimensions", options.overrides?.embeddingDimensions, env.RAGCODE_EMBEDDING_DIMENSIONS, fileConfig.embeddingDimensions, sources);
+    const embeddingRequestDimensions = selectBoolean("embeddingRequestDimensions", options.overrides?.embeddingRequestDimensions, env.RAGCODE_EMBEDDING_REQUEST_DIMENSIONS, fileConfig.embeddingRequestDimensions, DEFAULT_RUNTIME_CONFIG.embeddingRequestDimensions, sources);
+    const embeddingBatchSize = selectPositiveInteger("embeddingBatchSize", options.overrides?.embeddingBatchSize, env.RAGCODE_EMBEDDING_BATCH_SIZE, fileConfig.embeddingBatchSize, DEFAULT_RUNTIME_CONFIG.embeddingBatchSize, sources);
+    const embeddingConcurrency = selectPositiveInteger("embeddingConcurrency", options.overrides?.embeddingConcurrency, env.RAGCODE_EMBEDDING_CONCURRENCY, fileConfig.embeddingConcurrency, DEFAULT_RUNTIME_CONFIG.embeddingConcurrency, sources);
+    const semanticMaxChunks = selectSemanticMaxChunks("semanticMaxChunks", options.overrides?.semanticMaxChunks, env.RAGCODE_SEMANTIC_MAX_CHUNKS, fileConfig.semanticMaxChunks, embeddingProvider, sources);
+    return {
+        repoRoot,
+        configPath,
+        graph: {
+            graphStore: enumValue(graphStore, ["memory", "sqlite"], "graphStore"),
+            sqlitePath
+        },
+        semantic: {
+            semanticStore: enumValue(semanticStore, ["memory", "lancedb"], "semanticStore"),
+            embeddingProvider,
+            lanceDbUri,
+            lanceDbTableName,
+            embeddingBaseUrl,
+            embeddingModel,
+            embeddingDimensions,
+            embeddingRequestDimensions,
+            embeddingBatchSize,
+            embeddingConcurrency,
+            semanticMaxChunks
+        },
+        embeddingApiKey,
+        sources
+    };
+}
+export function createRuntimeComponents(config) {
+    const graphRuntime = createGraphRuntimeFromConfig(config.graph);
+    const semanticRuntime = createSemanticRuntimeFromConfig(config.semantic, {
+        RAGCODE_EMBEDDING_API_KEY: config.embeddingApiKey ?? ""
+    });
+    return {
+        graphStore: graphRuntime.graphStore,
+        semanticStore: semanticRuntime.semanticStore,
+        embeddingProvider: semanticRuntime.embeddingProvider,
+        config
+    };
+}
+export function createRuntimeComponentsForRepo(options = {}) {
+    return createRuntimeComponents(loadRuntimeConfig(options));
+}
+export function writeRuntimeConfigFile(repoRoot, config) {
+    const configPath = path.join(path.resolve(repoRoot), CONFIG_FILE_NAME);
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return configPath;
+}
+export function runtimeConfigToEnv(config, options = {}) {
+    const env = {
+        RAGCODE_GRAPH_STORE: config.graph.graphStore,
+        RAGCODE_SQLITE_PATH: config.graph.sqlitePath,
+        RAGCODE_SEMANTIC_STORE: config.semantic.semanticStore,
+        RAGCODE_LANCEDB_URI: config.semantic.lanceDbUri ?? path.join(config.repoRoot, DEFAULT_RUNTIME_CONFIG.lancedbUri),
+        RAGCODE_LANCEDB_TABLE: config.semantic.lanceDbTableName,
+        RAGCODE_EMBEDDING_PROVIDER: config.semantic.embeddingProvider,
+        RAGCODE_EMBEDDING_BASE_URL: config.semantic.embeddingBaseUrl ?? DEFAULT_RUNTIME_CONFIG.embeddingBaseUrl,
+        RAGCODE_EMBEDDING_BATCH_SIZE: String(config.semantic.embeddingBatchSize),
+        RAGCODE_EMBEDDING_CONCURRENCY: String(config.semantic.embeddingConcurrency)
+    };
+    if (config.semantic.embeddingModel)
+        env.RAGCODE_EMBEDDING_MODEL = config.semantic.embeddingModel;
+    if (config.semantic.embeddingDimensions)
+        env.RAGCODE_EMBEDDING_DIMENSIONS = String(config.semantic.embeddingDimensions);
+    if (config.semantic.embeddingRequestDimensions)
+        env.RAGCODE_EMBEDDING_REQUEST_DIMENSIONS = "true";
+    if (config.semantic.semanticMaxChunks !== undefined)
+        env.RAGCODE_SEMANTIC_MAX_CHUNKS = String(config.semantic.semanticMaxChunks);
+    if (config.embeddingApiKey)
+        env.RAGCODE_EMBEDDING_API_KEY = options.includeSecrets ? config.embeddingApiKey : "<redacted>";
+    return env;
+}
+export function redactRuntimeConfig(config) {
+    return {
+        repoRoot: config.repoRoot,
+        configPath: config.configPath,
+        graphStore: config.graph.graphStore,
+        sqlitePath: config.graph.sqlitePath,
+        semanticStore: config.semantic.semanticStore,
+        lancedbUri: config.semantic.lanceDbUri,
+        lanceDbTableName: config.semantic.lanceDbTableName,
+        embeddingProvider: config.semantic.embeddingProvider,
+        embeddingBaseUrl: config.semantic.embeddingBaseUrl,
+        embeddingModel: config.semantic.embeddingModel,
+        embeddingDimensions: config.semantic.embeddingDimensions,
+        embeddingRequestDimensions: config.semantic.embeddingRequestDimensions,
+        embeddingBatchSize: config.semantic.embeddingBatchSize,
+        embeddingConcurrency: config.semantic.embeddingConcurrency,
+        semanticMaxChunks: config.semantic.semanticMaxChunks,
+        embeddingApiKey: config.embeddingApiKey ? "set" : "unset",
+        sources: config.sources
+    };
+}
+export function readRuntimeConfigFile(configPath) {
+    try {
+        return JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+function resolveRepoPath(repoRoot, value) {
+    return path.isAbsolute(value) ? value : path.join(repoRoot, value);
+}
+function selectString(field, overrideValue, envValue, configValue, defaultValue, sources) {
+    const selected = selectValue(field, overrideValue, envValue, configValue, defaultValue, sources);
+    if (typeof selected !== "string" || selected.trim() === "")
+        throw new Error(`Invalid runtime config field ${field}: expected a non-empty string.`);
+    return selected;
+}
+function selectOptionalString(field, overrideValue, envValue, configValue, sources) {
+    const selected = selectValue(field, overrideValue, envValue, configValue, undefined, sources);
+    if (selected === undefined || selected === null || selected === "")
+        return undefined;
+    if (typeof selected !== "string")
+        throw new Error(`Invalid runtime config field ${field}: expected a string.`);
+    return selected;
+}
+function selectPositiveInteger(field, overrideValue, envValue, configValue, defaultValue, sources) {
+    return positiveInteger(field, selectValue(field, overrideValue, envValue, configValue, defaultValue, sources));
+}
+function selectOptionalPositiveInteger(field, overrideValue, envValue, configValue, sources) {
+    const selected = selectValue(field, overrideValue, envValue, configValue, undefined, sources);
+    if (selected === undefined || selected === null || selected === "")
+        return undefined;
+    return positiveInteger(field, selected);
+}
+function selectBoolean(field, overrideValue, envValue, configValue, defaultValue, sources) {
+    const selected = selectValue(field, overrideValue, envValue, configValue, defaultValue, sources);
+    if (typeof selected === "boolean")
+        return selected;
+    if (selected === "true")
+        return true;
+    if (selected === "false")
+        return false;
+    throw new Error(`Invalid runtime config field ${field}: expected boolean.`);
+}
+function selectSemanticMaxChunks(field, overrideValue, envValue, configValue, provider, sources) {
+    const selected = selectValue(field, overrideValue, envValue, configValue, undefined, sources);
+    if (selected === undefined || selected === null || selected === "")
+        return provider === "openai-compatible" ? 512 : undefined;
+    if (selected === "0" || (typeof selected === "string" && selected.toLowerCase() === "all"))
+        return undefined;
+    return positiveInteger(field, selected);
+}
+function selectValue(field, overrideValue, envValue, configValue, defaultValue, sources) {
+    if (overrideValue !== undefined) {
+        sources[field] = "override";
+        return overrideValue;
+    }
+    if (envValue !== undefined) {
+        sources[field] = "env";
+        return envValue;
+    }
+    if (configValue !== undefined) {
+        sources[field] = "config";
+        return configValue;
+    }
+    sources[field] = "default";
+    return defaultValue;
+}
+function normalizeEmbeddingProvider(value) {
+    if (value === "openai")
+        return "openai-compatible";
+    return enumValue(value, ["deterministic", "openai-compatible"], "embeddingProvider");
+}
+function enumValue(value, allowed, field) {
+    if (allowed.includes(value))
+        return value;
+    throw new Error(`Invalid runtime config field ${field}: expected one of ${allowed.join(", ")}, got ${value}.`);
+}
+function positiveInteger(field, value) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid runtime config field ${field}: expected positive integer, got ${String(value)}.`);
+    }
+    return parsed;
+}

package/dist/src/config/semantic-runtime.d.ts

@@ -0,0 +1,24 @@
+import type { EmbeddingProvider, SemanticStore } from "../core/contracts.js";
+export type SemanticStoreKind = "memory" | "lancedb";
+export type EmbeddingProviderKind = "deterministic" | "openai-compatible";
+export interface SemanticRuntimeConfig {
+    semanticStore: SemanticStoreKind;
+    embeddingProvider: EmbeddingProviderKind;
+    lanceDbUri?: string;
+    lanceDbTableName: string;
+    embeddingBaseUrl?: string;
+    embeddingModel?: string;
+    embeddingDimensions?: number;
+    embeddingRequestDimensions: boolean;
+    embeddingBatchSize: number;
+    embeddingConcurrency: number;
+    semanticMaxChunks?: number;
+}
+export interface SemanticRuntimeComponents {
+    semanticStore: SemanticStore;
+    embeddingProvider: EmbeddingProvider;
+    config: SemanticRuntimeConfig;
+}
+export declare function createSemanticRuntimeFromEnv(env?: NodeJS.ProcessEnv, cwd?: string): SemanticRuntimeComponents;
+export declare function createSemanticRuntimeFromConfig(config: SemanticRuntimeConfig, env?: Partial<Pick<NodeJS.ProcessEnv, "RAGCODE_EMBEDDING_API_KEY">>): SemanticRuntimeComponents;
+export declare function readSemanticRuntimeConfig(env?: NodeJS.ProcessEnv, cwd?: string): SemanticRuntimeConfig;

package/dist/src/config/semantic-runtime.js

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { DeterministicEmbeddingProvider } from "../semantic/deterministic-embedding.js";
+import { InMemorySemanticStore } from "../semantic/in-memory-semantic-store.js";
+import { LanceSemanticStore } from "../semantic/lance-semantic-store.js";
+import { OpenAICompatibleEmbeddingProvider } from "../semantic/openai-compatible-embedding.js";
+export function createSemanticRuntimeFromEnv(env = process.env, cwd = process.cwd()) {
+    const config = readSemanticRuntimeConfig(env, cwd);
+    return createSemanticRuntimeFromConfig(config, env);
+}
+export function createSemanticRuntimeFromConfig(config, env = process.env) {
+    const embeddingProvider = createEmbeddingProvider(config, env);
+    const semanticStore = createSemanticStore(config, embeddingProvider);
+    return { semanticStore, embeddingProvider, config };
+}
+export function readSemanticRuntimeConfig(env = process.env, cwd = process.cwd()) {
+    const semanticStore = enumValue(env.RAGCODE_SEMANTIC_STORE, ["memory", "lancedb"], "memory");
+    const embeddingProvider = enumValue(env.RAGCODE_EMBEDDING_PROVIDER, ["deterministic", "openai-compatible"], "deterministic");
+    const embeddingDimensions = optionalPositiveInteger(env.RAGCODE_EMBEDDING_DIMENSIONS);
+    return {
+        semanticStore,
+        embeddingProvider,
+        lanceDbUri: env.RAGCODE_LANCEDB_URI ?? path.join(cwd, ".ragcode", "lancedb"),
+        lanceDbTableName: env.RAGCODE_LANCEDB_TABLE ?? "code_chunks",
+        embeddingBaseUrl: env.RAGCODE_EMBEDDING_BASE_URL ?? "https://api.openai.com/v1",
+        embeddingModel: env.RAGCODE_EMBEDDING_MODEL ?? (embeddingProvider === "openai-compatible" ? "text-embedding-3-small" : undefined),
+        embeddingDimensions,
+        embeddingRequestDimensions: env.RAGCODE_EMBEDDING_REQUEST_DIMENSIONS === "true",
+        embeddingBatchSize: optionalPositiveInteger(env.RAGCODE_EMBEDDING_BATCH_SIZE) ?? 64,
+        embeddingConcurrency: optionalPositiveInteger(env.RAGCODE_EMBEDDING_CONCURRENCY) ?? 1,
+        semanticMaxChunks: semanticMaxChunks(env.RAGCODE_SEMANTIC_MAX_CHUNKS, embeddingProvider)
+    };
+}
+function createEmbeddingProvider(config, env) {
+    if (config.embeddingProvider === "deterministic") {
+        return new DeterministicEmbeddingProvider(config.embeddingDimensions ?? 64);
+    }
+    return new OpenAICompatibleEmbeddingProvider({
+        apiKey: env.RAGCODE_EMBEDDING_API_KEY ?? "",
+        model: config.embeddingModel ?? "text-embedding-3-small",
+        baseUrl: config.embeddingBaseUrl,
+        dimensions: config.embeddingDimensions,
+        requestDimensions: config.embeddingRequestDimensions
+    });
+}
+function createSemanticStore(config, provider) {
+    if (config.semanticStore === "memory")
+        return new InMemorySemanticStore();
+    return new LanceSemanticStore(config.lanceDbUri ?? ".ragcode/lancedb", {
+        tableName: config.lanceDbTableName,
+        vectorDimensions: provider.dimensions,
+        embeddingProfile: {
+            provider: config.embeddingProvider,
+            model: config.embeddingModel,
+            baseUrl: config.embeddingBaseUrl,
+            requestDimensions: config.embeddingRequestDimensions
+        },
+        embeddingBatchSize: config.embeddingBatchSize,
+        embeddingConcurrency: config.embeddingConcurrency,
+        maxChunks: config.semanticMaxChunks,
+        onProgress: (progress) => {
+            if (process.env.RAGCODE_EMBEDDING_PROGRESS === "false")
+                return;
+            const percent = Math.round((progress.completedChunks / progress.totalChunks) * 100);
+            const elapsedSeconds = Math.max(1, Math.round(progress.elapsedMs / 1000));
+            console.error(`[ragcode] embedded ${progress.completedChunks}/${progress.totalChunks} chunks (${percent}%) batch ${progress.batchIndex}/${progress.batchCount} elapsed ${elapsedSeconds}s`);
+        }
+    });
+}
+function semanticMaxChunks(value, provider) {
+    if (value === "0" || value?.toLowerCase() === "all")
+        return undefined;
+    return optionalPositiveInteger(value) ?? (provider === "openai-compatible" ? 512 : undefined);
+}
+function enumValue(value, allowed, fallback) {
+    if (!value)
+        return fallback;
+    if (allowed.includes(value))
+        return value;
+    throw new Error(`Invalid semantic runtime value "${value}". Expected one of: ${allowed.join(", ")}.`);
+}
+function optionalPositiveInteger(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid positive integer: ${value}`);
+    }
+    return parsed;
+}

package/dist/src/context/context-builder.d.ts

@@ -0,0 +1,20 @@
+import type { ContextPack, ContextRequest, DirtyFile, GraphEdge, SearchHit } from "../core/types.js";
+export interface ContextBuildMetadata {
+    projectId: string;
+    repoRoot: string;
+    indexedAtMs: number;
+    skippedFiles: Array<{
+        filePath: string;
+        reason: string;
+    }>;
+    indexGeneration?: number;
+    staleFiles?: string[];
+    pendingFiles?: string[];
+    indexingFiles?: string[];
+    dirtyFiles?: DirtyFile[];
+    burstMode?: boolean;
+    droppedEvents?: number;
+}
+export declare class ContextBuilder {
+    build(request: ContextRequest, hits: SearchHit[], edges: GraphEdge[] | undefined, metadata: ContextBuildMetadata): ContextPack;
+}