@futdevpro/nts-dynamo 1.15.56 → 1.15.58

package/build/_modules/ai/_services/lmstudio-embedding.control-service.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_LMStudio_Embedding_ControlService = void 0;
+const ai_1 = require("@futdevpro/fsm-dynamo/ai");
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const ai_embedding_service_base_1 = require("./ai-embedding.service-base");
+const global_settings_const_1 = require("../../../_collections/global-settings.const");
+/**
+ * `DyNTS_LMStudio_Embedding_ControlService` (BFR-AM-002) — OpenAI-kompatibilis **lokális** embedding
+ * adapter `fetch`-en (Node 20 global `fetch`, így a Dynamo NEM hoz be provider-specifikus SDK-t a
+ * lokális path-hoz). A FAM `FAM_LMStudio_EmbeddingProvider` workaround-ját emeli bedrock-szintre.
+ *
+ * A `baseUrl` + `modelId` config-ot a constructor-on kapja (mint a `DyNTS_OAI_Embedding_ControlService`
+ * a `DyFM_OAI_Settings`-et). A `${baseUrl}/embeddings` POST-ra a `{ model, input }` body-t küldi, a
+ * `data[].embedding` sorrendje == a `texts` sorrendje.
+ *
+ * **Cost-event (BFR-AM-007):** minden sikeres call után `emitCostEvent`-tel jelez (callType
+ * `embedding-single` / `embedding-batch`, provider `'lm-studio'`). Lokális futás → nincs USD-költség,
+ * a token-fogyasztás a `usage`-ből (ha az endpoint adja), különben becsült (4 char ≈ 1 token).
+ */
+class DyNTS_LMStudio_Embedding_ControlService extends ai_embedding_service_base_1.DyNTS_AI_Embedding_ServiceBase {
+    /** A provider-azonosító a `LocalAI` enum-érték (LM Studio = lokális OpenAI-kompatibilis endpoint). */
+    aiProvider = ai_1.DyFM_AI_Provider.LocalAI;
+    /** A cost-event provider-string (a `DyNTS_AI_CostEvent.provider` szabad-string mezőjéhez). */
+    costProvider = 'lm-studio';
+    /** LM Studio (OpenAI-kompatibilis lokális) capability-k: csak embedding-et igénylünk innen. */
+    capabilities = {
+        chat: false,
+        embeddings: true,
+        imageGeneration: false,
+        vision: false,
+        audioGeneration: false,
+        audioAnalysis: false,
+        functionCalling: false,
+        streaming: false,
+        batchOperations: true,
+        supportedModelTypes: [],
+    };
+    /** Az OpenAI-kompatibilis endpoint base URL-je (trailing slash-mentes). */
+    baseUrl;
+    /** Opcionális Bearer token. */
+    apiKey;
+    /**
+     * @param set baseUrl + opc. apiKey + opc. onCostEvent. A `baseUrl` kötelező — ha üres, a
+     *   `DyNTS-LMS-ECS-CFG` hibát dobjuk (lokális endpoint nincs konfigurálva).
+     */
+    constructor(set) {
+        super();
+        if (!set?.baseUrl || !set.baseUrl.trim().length) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                ...this.getDefaultErrorSettings('constructor', new Error('LM Studio baseUrl is required (OpenAI-compatible local endpoint)'), 'DyNTS_LMStudio_Embedding_ControlService'),
+                errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-LMS-ECS-CFG`,
+            });
+        }
+        this.baseUrl = this.trimTrailingSlashes(set.baseUrl.trim());
+        this.apiKey = set.apiKey;
+        if (set.onCostEvent) {
+            this.onCostEvent = set.onCostEvent;
+        }
+    }
+    /**
+     * Az LM Studio client-et nem SDK-val, hanem `fetch`-csel hívjuk; a `setup` a `baseUrl` (és
+     * opcionálisan az `apiKey`) átkonfigurálását teszi lehetővé (a base-szerződés egységessége miatt).
+     */
+    setup(config) {
+        if (config?.baseURL) {
+            this.baseUrl = this.trimTrailingSlashes(config.baseURL);
+        }
+        if (config?.apiKey) {
+            this.apiKey = config.apiKey;
+        }
+    }
+    /**
+     * Egy-szöveg embedding (a `createEmbeddings` egyelemű alakja). `fullResponse=true` esetén a
+     * teljes (OpenAI-alakú) válasz-objektumot adja vissza, különben a tiszta `number[]`-t.
+     */
+    async createEmbedding(set) {
+        try {
+            if (!set.text) {
+                throw new fsm_dynamo_1.DyFM_Error({
+                    ...this.getDefaultErrorSettings('createEmbedding', new Error('text is required'), set.issuer),
+                    errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-LMS-ECS-CE1`,
+                });
+            }
+            const start = Date.now();
+            const response = await this.callEmbeddingsEndpoint(set.model, set.text, set.issuer);
+            const durationMs = Date.now() - start;
+            this.emitLmStudioCostEvent('embedding-single', set.model, [set.text], response, durationMs, set.issuer);
+            if (set.fullResponse) {
+                return response;
+            }
+            return response.data[0].embedding;
+        }
+        catch (error) {
+            if (error instanceof fsm_dynamo_1.DyFM_Error) {
+                throw error;
+            }
+            throw new fsm_dynamo_1.DyFM_Error({
+                ...this.getDefaultErrorSettings('createEmbedding', error, set.issuer),
+                errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-LMS-ECS-CE0`,
+            });
+        }
+    }
+    /**
+     * Batch-embedding az OpenAI-kompatibilis `/embeddings` végpontra. A `texts` sorrendje == a
+     * visszaadott `number[][]` sorrendje. `fullResponse=true` esetén a teljes válasz-objektum.
+     */
+    async createEmbeddings(set) {
+        try {
+            if (!set.texts) {
+                throw new fsm_dynamo_1.DyFM_Error({
+                    ...this.getDefaultErrorSettings('createEmbeddings', new Error('texts is required'), set.issuer),
+                    errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-LMS-ECS-CES1`,
+                });
+            }
+            const start = Date.now();
+            const response = await this.callEmbeddingsEndpoint(set.model, set.texts, set.issuer);
+            const durationMs = Date.now() - start;
+            this.emitLmStudioCostEvent('embedding-batch', set.model, set.texts, response, durationMs, set.issuer);
+            if (set.fullResponse) {
+                return response;
+            }
+            return response.data.map((item) => item.embedding);
+        }
+        catch (error) {
+            if (error instanceof fsm_dynamo_1.DyFM_Error) {
+                throw error;
+            }
+            throw new fsm_dynamo_1.DyFM_Error({
+                ...this.getDefaultErrorSettings('createEmbeddings', error, set.issuer),
+                errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-LMS-ECS-CES0`,
+            });
+        }
+    }
+    /**
+     * Embedding model-info (a `DyFM_DAI_EmbeddingInfo` szerződés szerint). A provider `LocalAI`, a
+     * model a megadott azonosító (a lokális endpoint natív dimenzióját nem ismerjük előre).
+     */
+    getEmbeddingInfo(model) {
+        return {
+            provider: ai_1.DyFM_AI_Provider.LocalAI,
+            model: model,
+        };
+    }
+    /**
+     * Provider-elérhetőség: egy minimál embedding-próba (rövid token). Ha a hívás dob (endpoint down /
+     * model hiányzik), `false`. Soha nem propagál hibát (try/catch → false).
+     */
+    async testConnection(issuer) {
+        try {
+            const vectors = await this.createEmbeddings({
+                texts: ['ping'],
+                model: this.defaultProbeModel(),
+                fullResponse: false,
+                issuer: issuer,
+            });
+            return Array.isArray(vectors) && vectors.length === 1 && vectors[0].length > 0;
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.error('DyNTS_LMStudio_Embedding_ControlService', 'testConnection', 'Connection test failed', {
+                error: error,
+                issuer: issuer,
+            });
+            return false;
+        }
+    }
+    // =========================================================================
+    // belső: fetch + parse + cost-event
+    // =========================================================================
+    /**
+     * Az OpenAI-kompatibilis `/embeddings` POST-hívás `fetch`-csel. A `input` lehet egyetlen string
+     * vagy string-tömb (mindkettőt az OpenAI-spec megengedi). A választ `CreateEmbeddingResponse`-alakra
+     * normalizáljuk (a `data[].embedding`-eket kivonatoljuk). HTTP-/parse-hiba deskriptív üzenettel dobódik.
+     */
+    async callEmbeddingsEndpoint(model, input, issuer) {
+        const url = `${this.baseUrl}/embeddings`;
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey && this.apiKey.trim().length) {
+            headers.Authorization = `Bearer ${this.apiKey.trim()}`;
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: headers,
+            body: JSON.stringify({ model: model, input: input }),
+        });
+        const rawText = await response.text();
+        if (!response.ok) {
+            throw new Error(`LM Studio (OpenAI-compatible) embeddings HTTP ${response.status} | url=${url} | `
+                + `model=${model} | body=${this.snapshot(rawText)} | issuer=${issuer}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch {
+            throw new Error(`LM Studio embeddings: non-JSON response | url=${url} | model=${model} | body=${this.snapshot(rawText)}`);
+        }
+        const expectedCount = Array.isArray(input) ? input.length : 1;
+        return this.normalizeResponse(parsed, expectedCount, url, model);
+    }
+    /**
+     * A nyers (OpenAI-kompatibilis) választ `CreateEmbeddingResponse`-alakra normalizálja: a `data[]`-ból
+     * a `embedding` tömböket emeli ki (csak véges number-eket), a darabszámot ellenőrzi (1:1 a `texts`-szel),
+     * és átveszi a `usage`-t ha van (a cost-event token-számához). Hibás/hiányzó mező → deskriptív hiba.
+     */
+    normalizeResponse(json, expectedCount, url, modelId) {
+        if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+            throw new Error(`LM Studio embeddings: invalid response object | url=${url} | model=${modelId}`);
+        }
+        const dataRaw = Reflect.get(json, 'data');
+        if (!Array.isArray(dataRaw)) {
+            throw new Error(`LM Studio embeddings: missing data array | url=${url} | model=${modelId}`);
+        }
+        const data = [];
+        let index = 0;
+        for (const item of dataRaw) {
+            if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+                continue;
+            }
+            const embRaw = Reflect.get(item, 'embedding');
+            if (!Array.isArray(embRaw)) {
+                continue;
+            }
+            const vec = embRaw.filter((x) => typeof x === 'number' && Number.isFinite(x));
+            if (vec.length) {
+                data.push({ object: 'embedding', embedding: vec, index: index });
+                index++;
+            }
+        }
+        if (data.length !== expectedCount) {
+            throw new Error(`LM Studio embeddings: expected ${expectedCount} vectors, got ${data.length} | url=${url} | model=${modelId}`);
+        }
+        const usageRaw = Reflect.get(json, 'usage');
+        const promptTokens = this.readNumber(usageRaw, 'prompt_tokens');
+        const totalTokens = this.readNumber(usageRaw, 'total_tokens');
+        return {
+            object: 'list',
+            model: modelId,
+            data: data,
+            usage: {
+                prompt_tokens: promptTokens,
+                total_tokens: totalTokens || promptTokens,
+            },
+        };
+    }
+    /**
+     * Cost-event emit (BFR-AM-007). A token a `usage`-ből (ha az endpoint adta), különben becsült
+     * (4 char ≈ 1 token, defenzív lokális heurisztika). A provider mindig `'lm-studio'` string.
+     */
+    emitLmStudioCostEvent(callType, model, texts, response, durationMs, issuer) {
+        const reportedInput = response.usage?.prompt_tokens ?? 0;
+        const input = reportedInput || this.estimateTokens(texts);
+        const total = response.usage?.total_tokens || input;
+        this.emitCostEvent({
+            callType: callType,
+            provider: this.costProvider,
+            model: model,
+            tokensUsed: {
+                input: input,
+                total: total,
+            },
+            durationMs: durationMs,
+            issuer: issuer,
+            timestamp: new Date(),
+        });
+    }
+    /** Becsült token-szám lokális endpoint-hoz (ha nincs `usage`): 4 char ≈ 1 token. */
+    estimateTokens(texts) {
+        let chars = 0;
+        for (const text of texts) {
+            chars += (text ?? '').length;
+        }
+        return Math.max(1, Math.ceil(chars / 4));
+    }
+    /** A `testConnection` próba-modellje (env-override-olható, default a FAM-mintára). */
+    defaultProbeModel() {
+        return process.env.LMSTUDIO_EMBEDDING_MODEL || 'nomic-embed-text-v1.5';
+    }
+    /** Trailing `/`-ek levágása (kettős slash elkerülése a `/embeddings` join-nál). */
+    trimTrailingSlashes(value) {
+        return value.replace(/\/+$/, '');
+    }
+    /** Rövid, biztonságos válasz-snapshot a hiba-üzenethez (max 300 char). */
+    snapshot(value) {
+        const trimmed = (value ?? '').slice(0, 300);
+        return trimmed.length === 300 ? `${trimmed}…` : trimmed;
+    }
+    /** Egy number mező típusbiztos kiolvasása egy ismeretlen objektumból (hiány → 0). */
+    readNumber(obj, key) {
+        if (obj === null || typeof obj !== 'object') {
+            return 0;
+        }
+        const value = Reflect.get(obj, key);
+        return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+    }
+}
+exports.DyNTS_LMStudio_Embedding_ControlService = DyNTS_LMStudio_Embedding_ControlService;
+//# sourceMappingURL=lmstudio-embedding.control-service.js.map

package/build/_modules/ai/_services/lmstudio-embedding.control-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lmstudio-embedding.control-service.js","sourceRoot":"","sources":["../../../../src/_modules/ai/_services/lmstudio-embedding.control-service.ts"],"names":[],"mappings":"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"}

package/build/_modules/ai/index.d.ts

@@ -6,4 +6,7 @@ export * from './_services/ai-llm.service-base';
 export * from './_services/ai-llm-chat.service-base';
 export * from './_services/ai-embedding.service-base';
 export * from './_services/ai-user-key.service-base';
+export * from './_services/lmstudio-embedding.control-service';
+export * from './_services/ai-embedding-mock.service';
+export * from './_services/ai-embedding-provider.registry';
 //# sourceMappingURL=index.d.ts.map

package/build/_modules/ai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":"AACA,cAAc,0BAA0B,CAAC;AAGzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+CAA+C,CAAC;AAG9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":"AACA,cAAc,0BAA0B,CAAC;AAGzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+CAA+C,CAAC;AAG9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC"}

package/build/_modules/ai/index.js

@@ -12,4 +12,8 @@ tslib_1.__exportStar(require("./_services/ai-llm.service-base"), exports);
 tslib_1.__exportStar(require("./_services/ai-llm-chat.service-base"), exports);
 tslib_1.__exportStar(require("./_services/ai-embedding.service-base"), exports);
 tslib_1.__exportStar(require("./_services/ai-user-key.service-base"), exports);
+// Concrete Embedding Services + provider-dispatch (BFR-AM-002 / 007 / 008)
+tslib_1.__exportStar(require("./_services/lmstudio-embedding.control-service"), exports);
+tslib_1.__exportStar(require("./_services/ai-embedding-mock.service"), exports);
+tslib_1.__exportStar(require("./_services/ai-embedding-provider.registry"), exports);
 //# sourceMappingURL=index.js.map

package/build/_modules/ai/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":";;;AAAA,qBAAqB;AACrB,mEAAyC;AAEzC,uCAAuC;AACvC,wEAA8C;AAC9C,wFAA8D;AAE9D,oBAAoB;AACpB,+EAAqD;AACrD,0EAAgD;AAChD,+EAAqD;AACrD,gFAAsD;AACtD,+EAAqD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":";;;AAAA,qBAAqB;AACrB,mEAAyC;AAEzC,uCAAuC;AACvC,wEAA8C;AAC9C,wFAA8D;AAE9D,oBAAoB;AACpB,+EAAqD;AACrD,0EAAgD;AAChD,+EAAqD;AACrD,gFAAsD;AACtD,+EAAqD;AAErD,2EAA2E;AAC3E,yFAA+D;AAC/D,gFAAsD;AACtD,qFAA2D"}

package/build/_modules/data-readers/_collections/dynts-sqlite-reader.util.d.ts

@@ -0,0 +1,59 @@
+import { DyNTS_SqliteColumnInfo } from '../_models/interfaces/dynts-sqlite-reader.interface';
+/**
+ * `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) — **read-only** SQLite reader statikus util. Egy IZOLÁLT,
+ * opcionális natív függőséggel (`better-sqlite3`, read-only mode) ad általános, domain-agnosztikus
+ * SQLite-olvasást: `listTables` / `getSchema` / `readTable` / `query` (SELECT-only).
+ *
+ * **Read-only garancia (kétréteg):**
+ *   1. a DB MINDIG `{ readonly: true }`-vel nyílik (a SQLite-engine elutasít minden írást),
+ *   2. a `query()` ráadásul forrás-szinten egy **SELECT-only guard**-ot tesz (csak `SELECT`/`WITH`
+ *      kezdetű, single-statement SQL fut) — így a destruktív SQL még a DB-rétegig sem jut el.
+ *
+ * **Fail-soft (no-silent-failure):** hiányzó `path` / nem-létező fájl / megnyitás-hiba / tiltott SQL
+ * → tiszta, strukturált `DyFM_Error` (errorCode + deskriptív message), NEM hang/crash/néma-[]. A DB
+ * MINDIG zárul (try/finally).
+ *
+ * **Opcionális natív dep:** a `better-sqlite3` peer-dep `optional:true` — a consumer CSAK akkor adja
+ * hozzá, ha SQLite-ot olvas. A `/mcp`-vel diszjunkt; ez a util egy import-ban él, így a require
+ * tényleges hívásig (statikus metódus) nem terheli a nem-SQLite consumert.
+ */
+export declare class DyNTS_Sqlite_Reader_Util {
+    /** A hibák issuer-e (a strukturált DyFM_Error-okhoz). */
+    private static readonly issuer;
+    /** A `query()` SELECT-only guard regex-e: a (trimmelt, lowercase) SQL `select`/`with`-tel kezdődik. */
+    private static readonly SELECT_ONLY;
+    /**
+     * Egy tábla ÖSSZES sorának read-only olvasása (`SELECT * FROM <table>`). A `table` nevet
+     * `sqlite_master` ellen validáljuk (csak létező táblanév fut, így nincs SQL-injekciós felület a
+     * tábla-néven). Nem-létező tábla → strukturált hiba (NEM néma-[]).
+     */
+    static readTable(dbPath: string, table: string): unknown[];
+    /**
+     * Egy tetszőleges **SELECT-only** lekérdezés read-only futtatása. A guard elutasít minden nem-SELECT
+     * (insert/update/delete/drop/attach/pragma-write/…) SQL-t → `DyNTS-SQLITE-READONLY-001`. A
+     * `params` opcionális prepared-statement paraméterek (pozícionális `?` vagy named `@x`).
+     */
+    static query(dbPath: string, sql: string, params?: unknown[] | {
+        [key: string]: unknown;
+    }): unknown[];
+    /** A DB ÖSSZES (nem-belső) táblanevének read-only listája (`sqlite_master`, ABC-sorrendben). */
+    static listTables(dbPath: string): string[];
+    /**
+     * Egy tábla séma-leírása (`PRAGMA table_info(<table>)` — a SQLite read-only introspekciója). A
+     * `table` nevet `sqlite_master` ellen validáljuk (nem-létező → strukturált hiba). Az oszlop-info
+     * (`cid`/`name`/`type`/`notNull`/`defaultValue`/`primaryKey`) normalizált shape-ben tér vissza.
+     */
+    static getSchema(dbPath: string, table: string): DyNTS_SqliteColumnInfo[];
+    /**
+     * A DB read-only megnyitása + a callback futtatása + GARANTÁLT zárás (try/finally). A `path`
+     * validálva (üres/nem-létező → strukturált hiba); a megnyitás-/olvasás-hibát strukturált
+     * `DyFM_Error`-rá fordítjuk (a már-DyFM_Error-t NEM csomagoljuk újra). A `readonly:true` az
+     * első védvonal (a SQLite-engine elutasít minden írást).
+     */
+    private static withDb;
+    /** A SELECT-only guard: nem-SELECT/WITH kezdetű VAGY multi-statement SQL → strukturált hiba. */
+    private static assertSelectOnly;
+    /** Egy tábla létezésének read-only ellenőrzése (`sqlite_master`). */
+    private static tableExists;
+}
+//# sourceMappingURL=dynts-sqlite-reader.util.d.ts.map

package/build/_modules/data-readers/_collections/dynts-sqlite-reader.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynts-sqlite-reader.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/data-readers/_collections/dynts-sqlite-reader.util.ts"],"names":[],"mappings":"AAMA,OAAO,EACH,sBAAsB,EAEzB,MAAM,qDAAqD,CAAC;AAE7D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,wBAAwB;IAEjC,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAEpE,uGAAuG;IACvG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAErE;;;;OAIG;WACW,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;IAcjE;;;;OAIG;WACW,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,OAAO,EAAE;IAU5G,gGAAgG;WAClF,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IASlD;;;;OAIG;WACW,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,sBAAsB,EAAE;IAyBhF;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,MAAM;IAqCrB,gGAAgG;IAChG,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAoB/B,qEAAqE;IACrE,OAAO,CAAC,MAAM,CAAC,WAAW;CAK7B"}

package/build/_modules/data-readers/_collections/dynts-sqlite-reader.util.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_Sqlite_Reader_Util = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const better_sqlite3_1 = tslib_1.__importDefault(require("better-sqlite3"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+/**
+ * `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) — **read-only** SQLite reader statikus util. Egy IZOLÁLT,
+ * opcionális natív függőséggel (`better-sqlite3`, read-only mode) ad általános, domain-agnosztikus
+ * SQLite-olvasást: `listTables` / `getSchema` / `readTable` / `query` (SELECT-only).
+ *
+ * **Read-only garancia (kétréteg):**
+ *   1. a DB MINDIG `{ readonly: true }`-vel nyílik (a SQLite-engine elutasít minden írást),
+ *   2. a `query()` ráadásul forrás-szinten egy **SELECT-only guard**-ot tesz (csak `SELECT`/`WITH`
+ *      kezdetű, single-statement SQL fut) — így a destruktív SQL még a DB-rétegig sem jut el.
+ *
+ * **Fail-soft (no-silent-failure):** hiányzó `path` / nem-létező fájl / megnyitás-hiba / tiltott SQL
+ * → tiszta, strukturált `DyFM_Error` (errorCode + deskriptív message), NEM hang/crash/néma-[]. A DB
+ * MINDIG zárul (try/finally).
+ *
+ * **Opcionális natív dep:** a `better-sqlite3` peer-dep `optional:true` — a consumer CSAK akkor adja
+ * hozzá, ha SQLite-ot olvas. A `/mcp`-vel diszjunkt; ez a util egy import-ban él, így a require
+ * tényleges hívásig (statikus metódus) nem terheli a nem-SQLite consumert.
+ */
+class DyNTS_Sqlite_Reader_Util {
+    /** A hibák issuer-e (a strukturált DyFM_Error-okhoz). */
+    static issuer = 'DyNTS_Sqlite_Reader_Util';
+    /** A `query()` SELECT-only guard regex-e: a (trimmelt, lowercase) SQL `select`/`with`-tel kezdődik. */
+    static SELECT_ONLY = /^\s*(select|with)\b/i;
+    /**
+     * Egy tábla ÖSSZES sorának read-only olvasása (`SELECT * FROM <table>`). A `table` nevet
+     * `sqlite_master` ellen validáljuk (csak létező táblanév fut, így nincs SQL-injekciós felület a
+     * tábla-néven). Nem-létező tábla → strukturált hiba (NEM néma-[]).
+     */
+    static readTable(dbPath, table) {
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            if (!DyNTS_Sqlite_Reader_Util.tableExists(db, table)) {
+                throw new fsm_dynamo_1.DyFM_Error({
+                    errorCode: 'DyNTS-SQLITE-READ-002',
+                    message: `Table '${table}' does not exist in the SQLite DB: '${dbPath}'.`,
+                    issuer: DyNTS_Sqlite_Reader_Util.issuer,
+                });
+            }
+            // A `table` itt már egy igazolt, létező táblanév (sqlite_master), nem nyers user-input.
+            return db.prepare(`SELECT * FROM "${table}"`).all();
+        });
+    }
+    /**
+     * Egy tetszőleges **SELECT-only** lekérdezés read-only futtatása. A guard elutasít minden nem-SELECT
+     * (insert/update/delete/drop/attach/pragma-write/…) SQL-t → `DyNTS-SQLITE-READONLY-001`. A
+     * `params` opcionális prepared-statement paraméterek (pozícionális `?` vagy named `@x`).
+     */
+    static query(dbPath, sql, params) {
+        DyNTS_Sqlite_Reader_Util.assertSelectOnly(sql);
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            const statement = db.prepare(sql);
+            // A `better-sqlite3` `.all()` csak read-statement-en ad sort; write-statement-en dobna —
+            // a SELECT-only guard ezt már a forrás-rétegben kizárja (defenzív kettősség).
+            return params === undefined ? statement.all() : statement.all(params);
+        });
+    }
+    /** A DB ÖSSZES (nem-belső) táblanevének read-only listája (`sqlite_master`, ABC-sorrendben). */
+    static listTables(dbPath) {
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            const rows = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all();
+            return rows.map((row) => row.name);
+        });
+    }
+    /**
+     * Egy tábla séma-leírása (`PRAGMA table_info(<table>)` — a SQLite read-only introspekciója). A
+     * `table` nevet `sqlite_master` ellen validáljuk (nem-létező → strukturált hiba). Az oszlop-info
+     * (`cid`/`name`/`type`/`notNull`/`defaultValue`/`primaryKey`) normalizált shape-ben tér vissza.
+     */
+    static getSchema(dbPath, table) {
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            if (!DyNTS_Sqlite_Reader_Util.tableExists(db, table)) {
+                throw new fsm_dynamo_1.DyFM_Error({
+                    errorCode: 'DyNTS-SQLITE-READ-002',
+                    message: `Table '${table}' does not exist in the SQLite DB: '${dbPath}'.`,
+                    issuer: DyNTS_Sqlite_Reader_Util.issuer,
+                });
+            }
+            const rows = db.pragma(`table_info("${table}")`);
+            return rows.map((row) => ({
+                cid: row.cid,
+                name: row.name,
+                type: row.type,
+                notNull: row.notnull === 1,
+                defaultValue: row.dflt_value,
+                primaryKey: row.pk > 0,
+            }));
+        });
+    }
+    // =========================================================================
+    // Belső segédek (read-only megnyitás + guard-ok)
+    // =========================================================================
+    /**
+     * A DB read-only megnyitása + a callback futtatása + GARANTÁLT zárás (try/finally). A `path`
+     * validálva (üres/nem-létező → strukturált hiba); a megnyitás-/olvasás-hibát strukturált
+     * `DyFM_Error`-rá fordítjuk (a már-DyFM_Error-t NEM csomagoljuk újra). A `readonly:true` az
+     * első védvonal (a SQLite-engine elutasít minden írást).
+     */
+    static withDb(dbPath, work, options) {
+        if (!dbPath || !dbPath.trim().length) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READ-001',
+                message: 'A SQLite read requires a non-empty `dbPath` (path to the `.db` file).',
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+        if (!fs.existsSync(dbPath)) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READ-001',
+                message: `The SQLite DB file was not found: '${dbPath}'.`,
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+        let db = undefined;
+        try {
+            db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
+            return work(db);
+        }
+        catch (error) {
+            if (error instanceof fsm_dynamo_1.DyFM_Error) {
+                throw error;
+            }
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READ-003',
+                message: `Opening/reading the SQLite DB failed: '${dbPath}'.\n  error: `
+                    + `${fsm_dynamo_1.DyFM_Error.getErrorMessage(error)}`,
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+                error: error,
+            });
+        }
+        finally {
+            if (db) {
+                db.close();
+            }
+        }
+    }
+    /** A SELECT-only guard: nem-SELECT/WITH kezdetű VAGY multi-statement SQL → strukturált hiba. */
+    static assertSelectOnly(sql) {
+        const trimmed = (sql ?? '').trim();
+        if (!trimmed.length || !DyNTS_Sqlite_Reader_Util.SELECT_ONLY.test(trimmed)) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READONLY-001',
+                message: 'Only read-only SELECT/WITH queries are allowed (the reader is read-only).',
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+        // Multi-statement (`;` után további nem-üres tartalom) tiltott — egy SELECT mögé nem rejthető írás.
+        const withoutTrailingSemicolon = trimmed.replace(/;\s*$/, '');
+        if (withoutTrailingSemicolon.includes(';')) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READONLY-001',
+                message: 'Multi-statement SQL is not allowed (only a single read-only SELECT/WITH).',
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+    }
+    /** Egy tábla létezésének read-only ellenőrzése (`sqlite_master`). */
+    static tableExists(db, table) {
+        const found = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(table);
+        return Boolean(found);
+    }
+}
+exports.DyNTS_Sqlite_Reader_Util = DyNTS_Sqlite_Reader_Util;
+//# sourceMappingURL=dynts-sqlite-reader.util.js.map

package/build/_modules/data-readers/_collections/dynts-sqlite-reader.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynts-sqlite-reader.util.js","sourceRoot":"","sources":["../../../../src/_modules/data-readers/_collections/dynts-sqlite-reader.util.ts"],"names":[],"mappings":"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"}

package/build/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) shared shape-jei. Egy fájlban a szorosan összetartozó
+ * SQLite-reader I/O-típusok (`*.interface.ts` az egy-export-per-file konvenció ismert kivétele a
+ * tightly-coupled shape-ekre).
+ */
+/**
+ * Egy SQLite tábla egy oszlopának normalizált séma-leírása (a `getSchema()` ezt adja). A nyers
+ * `PRAGMA table_info` sort fordítjuk erre az SDK-független, stabil shape-re.
+ */
+export interface DyNTS_SqliteColumnInfo {
+    /** Az oszlop pozíciós azonosítója a táblában (`PRAGMA table_info.cid`). */
+    cid: number;
+    /** Az oszlop neve. */
+    name: string;
+    /** A deklarált oszlop-típus (SQLite affinity-string, pl. `TEXT`/`INTEGER`; lehet üres). */
+    type: string;
+    /** `true`, ha az oszlop `NOT NULL`. */
+    notNull: boolean;
+    /** Az oszlop default-értéke (deklarált literál string-ként), vagy `null` ha nincs. */
+    defaultValue: string | null;
+    /** `true`, ha az oszlop a primary key (vagy annak része). */
+    primaryKey: boolean;
+}
+/**
+ * A read-only megnyitás opciói (jövő-proof bővítő-pont). MVP: üres — a reader MINDIG `readonly:true`
+ * + `fileMustExist:true` módban nyit; ez az interface a későbbi, NON-breaking bővítésnek tart helyet.
+ */
+export interface DyNTS_SqliteReadOptions {
+    /** Reserved (jövőbeli, NON-breaking opciók — pl. timeout/verbose). */
+    reserved?: never;
+}
+//# sourceMappingURL=dynts-sqlite-reader.interface.d.ts.map

package/build/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynts-sqlite-reader.interface.d.ts","sourceRoot":"","sources":["../../../../../src/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACpC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,KAAK,CAAC;CACpB"}

package/build/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * A `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) shared shape-jei. Egy fájlban a szorosan összetartozó
+ * SQLite-reader I/O-típusok (`*.interface.ts` az egy-export-per-file konvenció ismert kivétele a
+ * tightly-coupled shape-ekre).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=dynts-sqlite-reader.interface.js.map

package/build/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynts-sqlite-reader.interface.js","sourceRoot":"","sources":["../../../../../src/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/build/_modules/data-readers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './_models/interfaces/dynts-sqlite-reader.interface';
+export * from './_collections/dynts-sqlite-reader.util';
+//# sourceMappingURL=index.d.ts.map