@askdb/config 0.3.0-beta.1

package/dist/runtime-store.d.ts

@@ -0,0 +1,21 @@
+import type { AskDbConfig } from "./types.js";
+export type AskDbRuntimeStore = {
+    readonly structured: AskDbConfig;
+    /** Canonical string map from {@link flattenAskDbConfig} (same keys as former merged `process.env`). */
+    readonly flat: Readonly<Record<string, string>>;
+};
+export declare function setAskDbRuntime(data: AskDbRuntimeStore): void;
+export declare function clearAskDbRuntime(): void;
+export declare function getAskDbRuntimeStore(): AskDbRuntimeStore;
+/** Build an env-shaped map for `@askdb/core` from the flattened runtime snapshot (not `process.env`). */
+export declare function flatToAiEnv(flat: Readonly<Record<string, string>>): Record<string, string | undefined>;
+/**
+ * Merge AskDB flat keys into a base env map (e.g. for spawning child processes).
+ * Does not read `process.env` itself.
+ */
+export declare function mergeAskDbFlatIntoEnvMap(base: NodeJS.ProcessEnv, flat: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
+/** @internal Tests only — replaces the runtime store without loading from disk. */
+export declare function setAskDbRuntimeForTests(data: AskDbRuntimeStore): void;
+/** @internal Tests only. */
+export declare function resetAskDbRuntimeForTests(): void;
+//# sourceMappingURL=runtime-store.d.ts.map

package/dist/runtime-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-store.d.ts","sourceRoot":"","sources":["../src/runtime-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD,CAAC;AAIF,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAE7D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,CAQxD;AAED,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAEtG;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,CAAC,UAAU,EACvB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACrC,MAAM,CAAC,UAAU,CAQnB;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAErE;AAED,4BAA4B;AAC5B,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/runtime-store.js

@@ -0,0 +1,40 @@
+let stored;
+export function setAskDbRuntime(data) {
+    stored = data;
+}
+export function clearAskDbRuntime() {
+    stored = undefined;
+}
+export function getAskDbRuntimeStore() {
+    if (!stored) {
+        throw new Error("AskDB runtime is not initialized. Call bootstrapAskDbEnv() (or bootstrapAskDbRuntime()) from @askdb/config after startup, " +
+            "typically with the project cwd, and ensure askdb.config.* exists.");
+    }
+    return stored;
+}
+/** Build an env-shaped map for `@askdb/core` from the flattened runtime snapshot (not `process.env`). */
+export function flatToAiEnv(flat) {
+    return { ...flat };
+}
+/**
+ * Merge AskDB flat keys into a base env map (e.g. for spawning child processes).
+ * Does not read `process.env` itself.
+ */
+export function mergeAskDbFlatIntoEnvMap(base, flat) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(flat)) {
+        if (v.trim() !== "") {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/** @internal Tests only — replaces the runtime store without loading from disk. */
+export function setAskDbRuntimeForTests(data) {
+    stored = data;
+}
+/** @internal Tests only. */
+export function resetAskDbRuntimeForTests() {
+    stored = undefined;
+}
+//# sourceMappingURL=runtime-store.js.map

package/dist/runtime-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-store.js","sourceRoot":"","sources":["../src/runtime-store.ts"],"names":[],"mappings":"AAQA,IAAI,MAAqC,CAAC;AAE1C,MAAM,UAAU,eAAe,CAAC,IAAuB;IACrD,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,SAAS,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,4HAA4H;YAC1H,mEAAmE,CACtE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,WAAW,CAAC,IAAsC;IAChE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAuB,EACvB,IAAsC;IAEtC,MAAM,GAAG,GAAsB,EAAE,GAAG,IAAI,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACpB,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,uBAAuB,CAAC,IAAuB;IAC7D,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,yBAAyB;IACvC,MAAM,GAAG,SAAS,CAAC;AACrB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,169 @@
+import type { AskDbAiProviderId, AskDbIntrospectionProvider, AskDbLogLevel, AskDbModeV1, AskDbRagEmbedder, AskDbRagStore } from "./constants.js";
+/**
+ * Authoring-time AskDB configuration: nested groups (`ai`, `database`, `introspection`, `rag`, …)
+ * passed to {@link defineConfig} in `askdb.config.*`, then flattened to canonical env keys for the runtime snapshot.
+ *
+ * Use with TypeScript’s `satisfies` operator to validate the object literal without widening it, e.g.
+ * `defineConfig({ ... } satisfies AskDbConfig)` or `const cfg = { ... } satisfies AskDbConfig`.
+ *
+ */
+export type OpenaiConfig = {
+    apiKey?: string;
+    baseUrl?: string;
+    /** When unset, `flattenAskDbConfig` applies the default OpenAI chat model (see `@askdb/config` defaults). */
+    model?: string;
+};
+export type AzureConfig = {
+    apiKey?: string;
+    secondaryApiKey?: string;
+    baseUrl?: string;
+    /** When unset, `flattenAskDbConfig` applies the default Azure deployment name (see `@askdb/config` defaults). */
+    model?: string;
+    apiVersion?: string;
+};
+export type FoundryConfig = {
+    apiKey?: string;
+    secondaryApiKey?: string;
+    model?: string;
+    apiVersion?: string;
+    baseUrl?: string;
+};
+/** Placeholder for future providers — not flattened today. */
+export type AnthropicConfig = Record<string, never>;
+export type GoogleConfig = Record<string, never>;
+export type OpenaiRagEmbedderConfig = {
+    model?: string;
+    /** Raw env string or number; positive integer parsed in {@link flattenAskDbConfig}, else derived from `model`. */
+    dimension?: string | number;
+    apiKey?: string;
+    baseUrl?: string;
+};
+export type FileStoreConfig = {
+    /** Passed to `createFileStore({ basePath })` — vector files use `<basePath>.embeddings.*`. */
+    basePath?: string;
+    autoFlush?: boolean;
+};
+/** In-memory store has no env-backed options today. */
+export type MemoryStoreConfig = Record<string, never>;
+export type PgvectorStoreConfig = {
+    /** Connection string for pgvector (maps to `ASKDB_PGVECTOR_URL`). */
+    databaseUrl?: string;
+    table?: string;
+    /** Positive integer from env or number; when unset, matches resolved RAG embedder dimensions in {@link flattenAskDbConfig}. */
+    dimensions?: string | number;
+    /** When unset, {@link flattenAskDbConfig} uses `hnsw`. */
+    indexStrategy?: string;
+};
+/**
+ * Root shape for `export default defineConfig({ ... })` in `askdb.config.*`.
+ *
+ * - **`ai`**: LLM provider + discriminated `providerConfig` branch (`openai` | `azure` | `foundry`).
+ * - **`database`**: primary app DB (Postgres today); supplies default `DATABASE_URL`.
+ * - **`introspection`**: Postgres vs Prisma engine; Postgres may omit `databaseUrl` to reuse `database`.
+ * - **`rag`**: embedder + store branches flattened to `ASKDB_RAG_*` / `ASKDB_PGVECTOR_URL` / file paths.
+ * - **`logging` | `modes` | `host`**: optional operational defaults.
+ */
+export type AskDbConfig = {
+    ai: {
+        provider: AskDbAiProviderId;
+        providerConfig: {
+            openai?: OpenaiConfig;
+            azure?: AzureConfig;
+            foundry?: FoundryConfig;
+            anthropic?: AnthropicConfig;
+            google?: GoogleConfig;
+        };
+    };
+    database: {
+        provider: "postgres";
+        providerConfig: {
+            /**
+             * When unset/blank, `flattenAskDbConfig` uses the package default local Postgres URL.
+             * Use `env("DATABASE_URL")` (or another key) in `askdb.config.*` to supply a URL from `.env`.
+             */
+            postgres: {
+                databaseUrl?: string;
+            };
+        };
+    };
+    introspection: {
+        provider: AskDbIntrospectionProvider;
+        providerConfig: {
+            postgres?: {
+                /**
+                 * When omitted or blank, live introspection reuses the resolved `DATABASE_URL` from the
+                 * `database` section. Set this only for an introspection-only URL.
+                 */
+                databaseUrl?: string;
+            };
+            prisma?: {
+                schemaPath?: string;
+            };
+        };
+        /**
+         * Default introspection output directory (maps to `ASKDB_INTROSPECT_OUT`).
+         * When unset/blank, `flattenAskDbConfig` uses the package default `./askdb/`.
+         */
+        outputDir?: string;
+    };
+    rag: {
+        embedder: AskDbRagEmbedder;
+        embedderConfig: {
+            openai?: OpenaiRagEmbedderConfig;
+        };
+        store: AskDbRagStore;
+        storeConfig: {
+            file?: FileStoreConfig;
+            memory?: MemoryStoreConfig;
+            pgvector?: PgvectorStoreConfig;
+        };
+    };
+    logging?: {
+        level?: AskDbLogLevel;
+        correlationId?: string;
+        /** Maps to `ASKDB_LOG_FILE`. */
+        logFile?: string;
+        /** When true, maps to `ASKDB_LOG_STDOUT=true`. */
+        logStdout?: boolean;
+    };
+    modes?: {
+        askdbMode?: AskDbModeV1;
+        omitSensitiveFromPrompt?: boolean;
+    };
+    host?: {
+        schemaPath?: string;
+        schemaJson?: string;
+    };
+    /** Deterministic NL→SQL for tests / local dev (maps to `ASKDB_MOCK_SQL`). */
+    dev?: {
+        mockSql?: string;
+    };
+    /** Default listen options for `askdb-tui` / other CLIs that need a model id. */
+    tui?: {
+        model?: string;
+    };
+    /** Studio browser server and optional RAG overrides. */
+    studio?: {
+        model?: string;
+        listen?: {
+            host?: string;
+            port?: number;
+        };
+        rag?: {
+            embedder?: string;
+            dimensions?: string | number;
+            apiKey?: string;
+            baseUrl?: string;
+            model?: string;
+        };
+    };
+    /** HTTP API server defaults (first-party `apps/http-api`). */
+    httpApi?: {
+        listen?: {
+            /** When unset, servers default to `3000`. Use `env("PORT")` for platforms that inject `PORT`. */
+            port?: number;
+            host?: string;
+        };
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@askdb/config",
+  "version": "0.3.0-beta.1",
+  "description": "AskDB configuration helpers: Prisma-style env() and askdb.config file discovery for first-party apps.",
+  "keywords": [
+    "askdb",
+    "config",
+    "environment"
+  ],
+  "homepage": "https://github.com/Ygilany/AskDB#readme",
+  "bugs": {
+    "url": "https://github.com/Ygilany/AskDB/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ygilany/AskDB.git",
+    "directory": "packages/config"
+  },
+  "license": "Apache-2.0",
+  "author": "Yahya Gilany",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "dotenv": "^16.6.1",
+    "jiti": "^2.4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run --config ../../vitest.config.ts"
+  }
+}