@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/mcp/_services/fam-write-tool.service.js

@@ -0,0 +1,460 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_WriteTool_Service = void 0;
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_entry_data_model_1 = require("../../../_models/data-models/fam-entry.data-model");
+const embedding_1 = require("../../embedding");
+const ingest_1 = require("../../ingest");
+const migration_1 = require("../../migration");
+const scope_reference_1 = require("../../scope-reference");
+const fam_mcp_interface_1 = require("../_models/interfaces/fam-mcp.interface");
+/**
+ * `FAM_WriteTool_Service` (SP-6.3, dsgn-003 §3) — a `write` core-tool **döntési kapuja**. Singleton.
+ * **MINDIG pontosan 1 `table`**; a scope KÖTELEZŐ minden tartalom-műveletnél (`create`/`scan-*`/
+ * `import`, dsgn-002 §3.2). EGY belépési pont (`handle`), amit MIND az MCP-tool, MIND a REST `POST
+ * /write` hív (transport-paritás, SP-6.5).
+ *
+ * A handler egy **operation-router** — NEM implementál CRUD/scan/embed logikát, csak validál + scope-ot
+ * old fel + a már megépített rétegekre delegál:
+ *   - `create`/`update`/`delete` → MP-1 CRUD (`FAM_Entry_DataService`; `delete` = soft-delete default),
+ *   - `scan-file`/`scan-folder`/`scan-project` → MP-4 (`FAM_Ingest_ControlService`),
+ *   - `re-embed` → MP-2 (`FAM_EmbeddingPipeline_ControlService`),
+ *   - `import` → **MP-11** (`FAM_ClaudeMemImport_ControlService.run` thin-wrapper, dsgn-009 — NEM vak bulk-insert).
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő DataService mezőt; minden
+ * DB-művelet előtt lazy `new FAM_Entry_DataService`.
+ */
+class FAM_WriteTool_Service {
+    static _instance;
+    /** Default issuer (a validációs / scope hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_WriteTool_Service';
+    static getInstance() {
+        if (!FAM_WriteTool_Service._instance) {
+            FAM_WriteTool_Service._instance = new FAM_WriteTool_Service();
+        }
+        return FAM_WriteTool_Service._instance;
+    }
+    /**
+     * A `write` core-handler (dsgn-003 §3). Validál (pontosan 1 table) → operation-router. A dobott
+     * `DyFM_Error` (validáció / scope / réteg-hiba) az adaptor/REST-rétegen át strukturált hibává
+     * fordul; a részleges scan-hiba a kimenet `scan.status='partial-failed'`-ban látszik (nem dob).
+     */
+    async handle(input) {
+        this.validate(input);
+        switch (input.operation) {
+            case fam_mcp_interface_1.FAM_WriteOperation.create:
+                return this.handleCreate(input);
+            case fam_mcp_interface_1.FAM_WriteOperation.update:
+                return this.handleUpdate(input);
+            case fam_mcp_interface_1.FAM_WriteOperation.delete:
+                return this.handleDelete(input);
+            case fam_mcp_interface_1.FAM_WriteOperation.scanFile:
+            case fam_mcp_interface_1.FAM_WriteOperation.scanFolder:
+            case fam_mcp_interface_1.FAM_WriteOperation.scanProject:
+                return this.handleScan(input);
+            case fam_mcp_interface_1.FAM_WriteOperation.reEmbed:
+                return this.handleReEmbed(input);
+            case fam_mcp_interface_1.FAM_WriteOperation.import:
+                return this.handleImport(input);
+            default:
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                    message: `Ismeretlen write-operation: '${input.operation}'. Megengedett: create | update | `
+                        + 'delete | scan-file | scan-folder | scan-project | re-embed | import.',
+                    issuer: this.issuer,
+                    context: { operation: 'write-validate' },
+                });
+        }
+    }
+    // =========================================================================
+    // Validáció (dsgn-003 §3.1 / §6.3)
+    // =========================================================================
+    /**
+     * Alap-validáció (DB-független, a delegálás ELŐTT): a `table` + az `operation` kötelező (a
+     * pontos-1-table a típus garantálja); az `update`/`delete` `target`-et igényel. Így a precíz
+     * validációs kód (`FAM-VAL-WRITE-003`) MIELŐTT bármilyen data-service / DB-művelet fut.
+     */
+    validate(input) {
+        if (!input || !input.table) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: 'A `write` PONTOSAN egy `table`-t igényel (a 6 fő tár vagy `reference`).',
+                issuer: this.issuer,
+                context: { operation: 'write-validate' },
+            });
+        }
+        if (!input.operation) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: 'A `write` `operation`-t igényel (create | update | delete | scan-* | re-embed | import).',
+                issuer: this.issuer,
+                context: { operation: 'write-validate', table: input.table },
+            });
+        }
+        const needsTarget = input.operation === fam_mcp_interface_1.FAM_WriteOperation.update || input.operation === fam_mcp_interface_1.FAM_WriteOperation.delete;
+        if (needsTarget && (!input.target || !input.target.by || !input.target.value)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteTargetAmbiguous,
+                message: 'Az `update`/`delete` művelethez `target` kötelező ({ by: id|sourceFilePath|query, value }).',
+                issuer: this.issuer,
+                context: { operation: 'write-validate', table: input.table },
+            });
+        }
+    }
+    // =========================================================================
+    // create / update / delete → MP-1 CRUD (FAM_Entry_DataService)
+    // =========================================================================
+    /**
+     * `create` (dsgn-003 §3.1) → MP-1 insert + MP-2 embed. A scope KÖTELEZŐ (MP-3 `resolveForWrite`);
+     * a `content` kötelező. A persist UTÁN auto-embed (`embedAndPersist`) — az embed-hiba az entry-t
+     * `error`-státuszba teszi + persistál (no-silent-failure, NEM dob ide).
+     */
+    async handleCreate(input) {
+        if (!input.content || !input.content.trim().length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: 'A `create` művelethez `content` kötelező (a vektorizálandó, ember-olvasható szöveg).',
+                issuer: this.issuer,
+                context: { operation: 'write-create', table: input.table },
+            });
+        }
+        const resolve = await this.resolveScope(input);
+        const registryEntry = this.requireRegistryEntry(input.table, 'write-create');
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const entry = new fam_entry_data_model_1.FAM_Entry({
+            table: input.table,
+            kind: input.kind,
+            tags: input.tags ?? [],
+            content: input.content,
+            scopePath: resolve.scopePath,
+            weight: input.weight,
+            importance: input.importance,
+            embeddingStatus: 'pending',
+            addedBy: 'agent-write',
+            source: this.agentSource(),
+            ...(input.fields ?? {}),
+        });
+        const saved = await dataService.saveData(entry);
+        const createdId = saved._id ?? '';
+        const embedOutcome = await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().embedAndPersist({
+            table: input.table, entry: saved, callType: 'embed-write',
+        });
+        const warnings = embedOutcome.status === 'error'
+            ? ['Az entry mentve, de az embedding sikertelen (érdemes ellenőrizni az embedding-providert; `re-embed`).']
+            : [];
+        return this.baseOutput({
+            operation: input.operation, table: input.table, scopePath: resolve.scopePath,
+            uncertaintyNotes: resolve.uncertaintyNotes, created: createdId ? [createdId] : [], warnings: warnings,
+        });
+    }
+    /**
+     * `update` (dsgn-003 §3.1) → MP-1 modify + (ha content változott) MP-2 re-embed. A `target`
+     * kötelező (`id`/`sourceFilePath`/`query`). A scope opcionális update-nél (a meglévő entry scope-ja
+     * marad, ha nincs új). A content-frissítés UTÁN auto-embed.
+     */
+    async handleUpdate(input) {
+        const registryEntry = this.requireRegistryEntry(input.table, 'write-update');
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const targetEntry = await this.resolveTarget(input, dataService, 'write-update');
+        // Mező-frissítés (csak a megadott mezők; a content-változás re-embedet vált).
+        const contentChanged = input.content !== undefined && input.content !== targetEntry.content;
+        if (input.content !== undefined) {
+            targetEntry.content = input.content;
+            targetEntry.embeddingStatus = 'pending';
+        }
+        if (input.kind !== undefined) {
+            targetEntry.kind = input.kind;
+        }
+        if (input.tags !== undefined) {
+            targetEntry.tags = input.tags;
+        }
+        if (input.weight !== undefined) {
+            targetEntry.weight = input.weight;
+        }
+        if (input.importance !== undefined) {
+            targetEntry.importance = input.importance;
+        }
+        if (input.fields) {
+            Object.assign(targetEntry, input.fields);
+        }
+        const saved = await dataService.saveData(targetEntry);
+        const updatedId = saved._id ?? '';
+        const warnings = [];
+        if (contentChanged) {
+            const embedOutcome = await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().embedAndPersist({
+                table: input.table, entry: saved, callType: 'embed-write',
+            });
+            if (embedOutcome.status === 'error') {
+                warnings.push('Az entry frissítve, de a re-embed sikertelen (ellenőrizd az embedding-providert).');
+            }
+        }
+        return this.baseOutput({
+            operation: input.operation, table: input.table,
+            scopePath: (saved.scopePath ?? []),
+            uncertaintyNotes: [], updated: updatedId ? [updatedId] : [], warnings: warnings,
+        });
+    }
+    /**
+     * `delete` (dsgn-003 §3.1) → MP-1 **soft-delete** (default; a hard-delete csak admin-capability,
+     * NEM érhető el a `write` tool-ról). A `target` kötelező. A `DyNTS_DataService.deleteData(id)` az
+     * `absolute=false` alapértékkel soft-delete-et végez (archív → history).
+     */
+    async handleDelete(input) {
+        const registryEntry = this.requireRegistryEntry(input.table, 'write-delete');
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const targetEntry = await this.resolveTarget(input, dataService, 'write-delete');
+        const deletedId = targetEntry._id ?? '';
+        if (deletedId) {
+            // absolute=false → soft-delete (a Dynamo-konvenció: a _deleted marker, archív collection).
+            await dataService.deleteData(deletedId, false);
+        }
+        return this.baseOutput({
+            operation: input.operation, table: input.table,
+            scopePath: (targetEntry.scopePath ?? []),
+            uncertaintyNotes: [], deleted: deletedId ? [deletedId] : [], warnings: [],
+        });
+    }
+    // =========================================================================
+    // scan-* → MP-4 (FAM_Ingest_ControlService)
+    // =========================================================================
+    /**
+     * `scan-file`/`scan-folder`/`scan-project` (dsgn-003 §3.1) → MP-4 ingest-pipeline. A scope
+     * KÖTELEZŐ + a `scan.path` kötelező; a per-fájl hiba NEM buktatja a run-t (`status:'partial-failed'`).
+     * A scope-resolve-ot az ingest-orchestrátor MAGA végzi (a raw scopePath-ot kapja).
+     */
+    async handleScan(input) {
+        const scopePath = this.requireScope(input, 'write-scan');
+        const scan = this.requireScan(input);
+        const request = {
+            path: scan.path,
+            scopePath: scopePath,
+            include: scan.include,
+            exclude: scan.exclude,
+            dryRun: scan.dryRun,
+            issuer: this.issuer,
+        };
+        let summary;
+        if (input.operation === fam_mcp_interface_1.FAM_WriteOperation.scanFile) {
+            summary = await ingest_1.FAM_Ingest_ControlService.getInstance().scanFile(request);
+        }
+        else if (input.operation === fam_mcp_interface_1.FAM_WriteOperation.scanFolder) {
+            summary = await ingest_1.FAM_Ingest_ControlService.getInstance().scanFolder(request);
+        }
+        else {
+            summary = await ingest_1.FAM_Ingest_ControlService.getInstance().scanProject(request);
+        }
+        const warnings = summary.status === 'failed'
+            ? ['A scan a fájl-bejárás előtt megállt (lásd a hibákat a `list_errors`-ban).']
+            : summary.status === 'partial-failed'
+                ? ['A scan részben sikerült — egyes fájlok kihagyva (lásd `list_errors`).']
+                : [];
+        return {
+            operation: input.operation, table: input.table, ok: summary.status !== 'failed',
+            created: [], updated: [], deleted: [], scopePath: summary.scopePath,
+            scan: {
+                filesProcessed: summary.filesProcessed, chunks: summary.chunkCount,
+                verdicts: summary.verdicts, status: summary.status,
+            },
+            ingestRunId: summary.ingestRunId, uncertaintyNotes: [], warnings: warnings,
+        };
+    }
+    // =========================================================================
+    // re-embed → MP-2 (FAM_EmbeddingPipeline_ControlService)
+    // =========================================================================
+    /**
+     * `re-embed` (dsgn-003 §3.1) → MP-2. A `table` (és opc. `scopePath`) minden chunkját újra-embeddeli
+     * az AKTUÁLIS modellel. Ha scope adott → `reEmbedScope` (a raw scope-ot feloldjuk canonical-ra),
+     * egyébként `reEmbedTable` (teljes tár).
+     */
+    async handleReEmbed(input) {
+        this.requireRegistryEntry(input.table, 'write-re-embed');
+        let result;
+        let canonicalScope = [];
+        let uncertaintyNotes = [];
+        if (input.scopePath && input.scopePath.length) {
+            const resolve = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(input.scopePath);
+            canonicalScope = resolve.scopePath;
+            uncertaintyNotes = resolve.uncertaintyNotes;
+            result = await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().reEmbedScope(input.table, canonicalScope);
+        }
+        else {
+            result = await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().reEmbedTable(input.table);
+        }
+        return {
+            operation: input.operation, table: input.table, ok: result.failed === 0,
+            created: [], updated: [], deleted: [], scopePath: canonicalScope,
+            reEmbed: {
+                total: result.total, reembedded: result.reembedded, skipped: result.skipped, failed: result.failed,
+            },
+            ingestRunId: null, uncertaintyNotes: uncertaintyNotes,
+            warnings: result.failed ? [`${result.failed} chunk re-embedje sikertelen (lásd \`list_errors\`).`] : [],
+        };
+    }
+    // =========================================================================
+    // import → MP-11 thin-wrapper (claude-mem migráció; dsgn-009)
+    // =========================================================================
+    /**
+     * `import` (dsgn-003 §3.1, dsgn-009) → a MP-11 migrációs engine **thin-wrapper**-e. SOSEM vak
+     * bulk-insert (dsgn-003 §4.2): a `FAM_ClaudeMemImport_ControlService.run`-t hívja (a teljes
+     * preview→map→run folyamat `run`-fázisa: dedup-skip + map + persist + embed egy batchId alatt). A
+     * finomhangolt preview/map/rollback a capabilities import-katalógusán érhető el; ez a write-belépés
+     * az alapértelmezett, egylépéses import. **Egyirányú** (dsgn-009 §7) — nincs reverse.
+     *
+     * A `run` eredményét a `write` kimenetre képezi: az `ingested` az `created`-ben (a batchId mint
+     * összegző), a `batchId` az `ingestRunId`-ben; a `failed>0` a `warnings`-ban + a `status` az
+     * `ok`-ban. A strukturált `errors[]` a `run`-ban MÁR persistált (no-silent-failure).
+     */
+    async handleImport(input) {
+        const importOptions = input.import;
+        if (!importOptions || !importOptions.source) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: 'Az `import` művelethez `import` blokk kötelező ({ source, from?, path? }) — a forrás '
+                    + '(MVP1: `claude-mem`) + a csatorna (`export-json`/`sqlite`/`worker-api`) + az útvonal.',
+                issuer: this.issuer,
+                context: { operation: 'write-import', table: input.table },
+            });
+        }
+        const request = {
+            source: importOptions.source,
+            from: this.toImportFrom(importOptions.from),
+            path: importOptions.path,
+        };
+        const result = await migration_1.FAM_ClaudeMemImport_ControlService.getInstance().run(request);
+        const warnings = [];
+        if (result.failed) {
+            warnings.push(`${result.failed} rekord importja sikertelen (lásd \`list_errors\`); a batch `
+                + `${result.status}. batchId='${result.batchId}' (visszavonható: \`rollback_import\`).`);
+        }
+        if (result.skipped) {
+            warnings.push(`${result.skipped} rekord dedup-skip-elve (már importált / duplikált tartalom) — `
+                + 'nem keletkezett duplikátum, nem embeddelődtek újra.');
+        }
+        return {
+            operation: input.operation, table: input.table, ok: result.ok,
+            created: [], updated: [], deleted: [], scopePath: [],
+            ingestRunId: result.batchId,
+            uncertaintyNotes: result.uncertaintyNotes, warnings: warnings,
+        };
+    }
+    /** Egy `from` string → `FAM_ClaudeMemSource_Type` (vagy undefined → a engine default export-json). */
+    toImportFrom(from) {
+        return from
+            ? Object.values(migration_1.FAM_ClaudeMemSource_Type).find((source) => source === from)
+            : undefined;
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /**
+     * A scope-resolve (MP-3 `resolveForWrite`) a tartalom-műveletekhez (`create`). A scope KÖTELEZŐ
+     * (üres → `FAM-SCOPE-WRITE-001` az engine-ben). Van-match-bizonytalan → `uncertaintyNotes` (nem hiba).
+     */
+    async resolveScope(input) {
+        const scopePath = this.requireScope(input, 'write-resolve');
+        return scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(scopePath);
+    }
+    /** A scope-kötelezőség enforcement (create/scan/import) — hiánya → `FAM-SCOPE-WRITE-001`. */
+    requireScope(input, operation) {
+        if (!input.scopePath || !input.scopePath.length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scopeWriteRequired,
+                message: 'A scope KÖTELEZŐ a tartalom-műveleteknél (create/scan-*/import) — adj meg legalább '
+                    + 'egy layert (pl. organization/project) a `scopePath`-ban.',
+                issuer: this.issuer,
+                context: { operation: operation, table: input.table },
+            });
+        }
+        return input.scopePath;
+    }
+    /** A `scan` blokk kötelezőség-enforcement (scan-* esetén). */
+    requireScan(input) {
+        if (!input.scan || !input.scan.path) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: 'A `scan-*` művelethez `scan.path` kötelező (a scan-gyökér file/folder/project).',
+                issuer: this.issuer,
+                context: { operation: 'write-scan', table: input.table },
+            });
+        }
+        return input.scan;
+    }
+    /**
+     * Az update/delete cél-entry feloldása (`target`: `id`/`sourceFilePath`/`query`). A `query`-mód
+     * MVP1-ben sourceFilePath/exact-content helyett egyszerű (a vektor-keresés a `read` dolga) — a
+     * `query` itt a `content` substring-jét keresi. Nem egyértelmű cél → `FAM-VAL-WRITE-003`.
+     */
+    async resolveTarget(input, dataService, operation) {
+        const target = input.target;
+        if (!target || !target.by || !target.value) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteTargetAmbiguous,
+                message: 'Az `update`/`delete` művelethez `target` kötelező ({ by: id|sourceFilePath|query, value }).',
+                issuer: this.issuer,
+                context: { operation: operation, table: input.table },
+            });
+        }
+        if (target.by === 'id') {
+            const byId = await dataService.findData({ _id: target.value }, true);
+            if (!byId || !byId._id) {
+                throw this.targetNotFound(input, target, operation);
+            }
+            return byId;
+        }
+        const filter = target.by === 'sourceFilePath'
+            ? { sourceFilePath: target.value }
+            : { content: target.value };
+        const matches = await dataService.findDataList(filter);
+        if (!matches.length) {
+            throw this.targetNotFound(input, target, operation);
+        }
+        if (matches.length > 1) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteTargetAmbiguous,
+                message: `A '${target.by}'='${target.value}' cél több (${matches.length}) entry-re illeszkedik — `
+                    + 'pontosíts (`by:id` egyedi azonosítóval).',
+                issuer: this.issuer,
+                context: { operation: operation, table: input.table },
+            });
+        }
+        return matches[0];
+    }
+    /** A cél nem található → `FAM-VAL-WRITE-003` (deskriptív). */
+    targetNotFound(input, target, operation) {
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteTargetAmbiguous,
+            message: `A '${target.by}'='${target.value}' cél nem található a(z) '${input.table}' tárban.`,
+            issuer: this.issuer,
+            context: { operation: operation, table: input.table },
+        });
+    }
+    /** A `table` store-registry bejegyzése (a 6 fő tárra). Hiányzó (pl. `reference`) → leíró hiba. */
+    requireRegistryEntry(table, operation) {
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+        if (!registryEntry) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteReferenceContent,
+                message: `A(z) '${table}' tár nem fogad tartalom-CRUD-ot ezen az úton (a 6 fő tár: rules/documents/`
+                    + 'codebase/knowledge/coding_patterns/memory). A `reference` helper-tár külön capability-n kezelt.',
+                issuer: this.issuer,
+                context: { operation: operation, table: table },
+            });
+        }
+        return registryEntry;
+    }
+    /** Az agent-write provenance (a `write` tool minden create-je `agent`-forrású). */
+    agentSource() {
+        return { type: 'agent' };
+    }
+    /** A `write` kimenet alap-burka (a per-operation handlerek ezt töltik ki). */
+    baseOutput(set) {
+        return {
+            operation: set.operation, table: set.table, ok: true,
+            created: set.created ?? [], updated: set.updated ?? [], deleted: set.deleted ?? [],
+            scopePath: set.scopePath, ingestRunId: null,
+            uncertaintyNotes: set.uncertaintyNotes, warnings: set.warnings,
+        };
+    }
+}
+exports.FAM_WriteTool_Service = FAM_WriteTool_Service;

package/build/src/_modules/mcp/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * `mcp` modul barrel (MP-6, dsgn-003) — az MCP-szerver + a 3 core-tool + a capability-registry
+ * publikus felülete. A fogyasztók: az `index.ts` (CLI entry: `fam start` → `FAM_McpServer_Service`),
+ * a REST-réteg (`_routes/server/api`, SP-6.5: a transport-agnosztikus core `FAM_*Tool_Service`-ek a
+ * REST-mirrorhoz), és a contract-tesztek (advertised-tool + diszjunkció).
+ *
+ * Boundary (dsgn-003 §5, BFR-AM-003): a `FAM_Mcp_Adapter` az EGYETLEN choke-pont a hivatalos
+ * `@modelcontextprotocol/sdk` köré — a bedrock `DyNTS_Mcp_*` (MP-15) csere itt non-breaking. A 3
+ * core-tool + a capability-registry transport-agnosztikus (MCP stdio + REST UGYANEZT hívja).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_WriteOperation = exports.FAM_CapabilityCategory = exports.FAM_CapabilityRegistry = exports.FAM_CapabilitiesTool_Service = exports.FAM_WriteTool_Service = exports.FAM_ReadTool_Service = exports.FAM_CORE_TOOLS = exports.FAM_McpServer_Service = exports.FAM_Mcp_Adapter = void 0;
+// SP-6.1 — MCP infra (adaptor + szerver-orchestrátor)
+var fam_mcp_adapter_service_1 = require("./_services/fam-mcp-adapter.service");
+Object.defineProperty(exports, "FAM_Mcp_Adapter", { enumerable: true, get: function () { return fam_mcp_adapter_service_1.FAM_Mcp_Adapter; } });
+var fam_mcp_server_service_1 = require("./_services/fam-mcp-server.service");
+Object.defineProperty(exports, "FAM_McpServer_Service", { enumerable: true, get: function () { return fam_mcp_server_service_1.FAM_McpServer_Service; } });
+var fam_core_tools_const_1 = require("./_collections/fam-core-tools.const");
+Object.defineProperty(exports, "FAM_CORE_TOOLS", { enumerable: true, get: function () { return fam_core_tools_const_1.FAM_CORE_TOOLS; } });
+// SP-6.2 — `read` core-handler (transport-agnosztikus; REST + MCP UGYANEZT hívja)
+var fam_read_tool_service_1 = require("./_services/fam-read-tool.service");
+Object.defineProperty(exports, "FAM_ReadTool_Service", { enumerable: true, get: function () { return fam_read_tool_service_1.FAM_ReadTool_Service; } });
+// SP-6.3 — `write` core-handler (operation-router; transport-agnosztikus)
+var fam_write_tool_service_1 = require("./_services/fam-write-tool.service");
+Object.defineProperty(exports, "FAM_WriteTool_Service", { enumerable: true, get: function () { return fam_write_tool_service_1.FAM_WriteTool_Service; } });
+// SP-6.4 — `capabilities` core-handler + special-tool registry
+var fam_capabilities_tool_service_1 = require("./_services/fam-capabilities-tool.service");
+Object.defineProperty(exports, "FAM_CapabilitiesTool_Service", { enumerable: true, get: function () { return fam_capabilities_tool_service_1.FAM_CapabilitiesTool_Service; } });
+var fam_capability_registry_service_1 = require("./_services/fam-capability-registry.service");
+Object.defineProperty(exports, "FAM_CapabilityRegistry", { enumerable: true, get: function () { return fam_capability_registry_service_1.FAM_CapabilityRegistry; } });
+// shared vokabulár (a REST-réteg + a contract-tesztek fogyasztják)
+var fam_mcp_interface_1 = require("./_models/interfaces/fam-mcp.interface");
+Object.defineProperty(exports, "FAM_CapabilityCategory", { enumerable: true, get: function () { return fam_mcp_interface_1.FAM_CapabilityCategory; } });
+Object.defineProperty(exports, "FAM_WriteOperation", { enumerable: true, get: function () { return fam_mcp_interface_1.FAM_WriteOperation; } });

package/build/src/_modules/migration/_collections/fam-claude-mem-normalize.util.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemNormalize_Util = void 0;
+const fam_claude_mem_interface_1 = require("../_models/interfaces/fam-claude-mem.interface");
+/**
+ * `FAM_ClaudeMemNormalize_Util` (SP-11.1) — a nyers forrás-rekordokat (observations / summaries /
+ * prompts / sessions) a KÖZÖS `FAM_ClaudeMemRecord` köztes shape-re normalizálja. MINDEN reader
+ * (export-JSON / SQLite / worker-api) ezt hívja, így a 3 forrás UGYANARRA a tartalomra UGYANAZT a
+ * normalizált rekordot adja (paritás — dsgn-009 §9.2). Statikus util (nincs DB-/external-függőség).
+ *
+ * A `sessions` rekordok NEM normalizálódnak entry-vé (dsgn-009 §2) — metaadatként mennek tovább
+ * (`project`→scope + sessionId/runId hidratálás). A `prompts` CSAK `includePrompts:true` esetén
+ * kerülnek a normalizált halmazba. A defenzív parse a hiányzó/drift-elt mezőket warning-gal jelzi
+ * (nem-néma drop, nem crash — dsgn-009 §9 acceptance).
+ */
+class FAM_ClaudeMemNormalize_Util {
+    /**
+     * A teljes forrás-halmaz normalizálása (SP-11.1). Az observation-ök + summary-k (+ opc. prompt-ok)
+     * a normalizált rekord-listába; a session-ök metaadatként; a nyers counts + defenzív warning-ok.
+     */
+    static normalizeAll(set) {
+        const records = [];
+        const warnings = [];
+        for (const observation of set.observations) {
+            const record = FAM_ClaudeMemNormalize_Util.normalizeObservation(observation, warnings);
+            if (record) {
+                records.push(record);
+            }
+        }
+        for (const summary of set.summaries) {
+            const record = FAM_ClaudeMemNormalize_Util.normalizeSummary(summary, warnings);
+            if (record) {
+                records.push(record);
+            }
+        }
+        // user_prompts CSAK includePrompts:true esetén (default OFF — dsgn-009 §2 / §9.7).
+        if (set.includePrompts) {
+            for (const prompt of set.prompts) {
+                const record = FAM_ClaudeMemNormalize_Util.normalizePrompt(prompt, warnings);
+                if (record) {
+                    records.push(record);
+                }
+            }
+        }
+        return {
+            from: set.from,
+            records: records,
+            sessions: set.sessions,
+            counts: {
+                observations: set.observations.length,
+                summaries: set.summaries.length,
+                prompts: set.prompts.length,
+                sessions: set.sessions.length,
+            },
+            warnings: warnings,
+        };
+    }
+    /**
+     * Egy observation normalizálása. A `id` hiányában nincs ELSŐDLEGES dedup-kulcs → warning + drop
+     * (a `contentHash` fallback nélküli rekord dedup-ja megbízhatatlan lenne). A `type` hiánya warning,
+     * de NEM drop (a default-mapping `change`-re esik vissza a mapperben).
+     */
+    static normalizeObservation(raw, warnings) {
+        const sourceRowId = FAM_ClaudeMemNormalize_Util.toStringId(raw.id);
+        if (!sourceRowId) {
+            warnings.push('Egy observation `id` nélkül érkezett (nincs elsődleges dedup-kulcs) — kihagyva.');
+            return null;
+        }
+        if (!raw.type) {
+            warnings.push(`Az observation '${sourceRowId}' 'type' nélkül érkezett — a default-mapping 'change'-re esik vissza.`);
+        }
+        return {
+            entity: fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.observation,
+            sourceRowId: sourceRowId,
+            sessionId: FAM_ClaudeMemNormalize_Util.cleanString(raw.session_id),
+            sdkSessionId: FAM_ClaudeMemNormalize_Util.cleanString(raw.sdk_session_id),
+            claudeSessionId: FAM_ClaudeMemNormalize_Util.cleanString(raw.claude_session_id),
+            project: FAM_ClaudeMemNormalize_Util.cleanString(raw.project),
+            title: FAM_ClaudeMemNormalize_Util.cleanString(raw.title),
+            subtitle: FAM_ClaudeMemNormalize_Util.cleanString(raw.subtitle),
+            narrative: FAM_ClaudeMemNormalize_Util.cleanString(raw.narrative),
+            text: FAM_ClaudeMemNormalize_Util.cleanString(raw.text),
+            facts: FAM_ClaudeMemNormalize_Util.cleanString(raw.facts),
+            concepts: FAM_ClaudeMemNormalize_Util.cleanStringArray(raw.concepts),
+            type: FAM_ClaudeMemNormalize_Util.cleanString(raw.type),
+            filesRead: FAM_ClaudeMemNormalize_Util.cleanStringArray(raw.files_read),
+            filesModified: FAM_ClaudeMemNormalize_Util.cleanStringArray(raw.files_modified),
+            createdAtEpoch: typeof raw.created_at_epoch === 'number' ? raw.created_at_epoch : undefined,
+        };
+    }
+    /**
+     * Egy session_summary normalizálása. A `importSourceId` kulcsa az `sdk_session_id`
+     * (`session_summaries:<sdk_session_id>`, dsgn-009 §3 tábla); hiányában a `id`-re esik vissza.
+     */
+    static normalizeSummary(raw, warnings) {
+        const sourceRowId = FAM_ClaudeMemNormalize_Util.cleanString(raw.sdk_session_id)
+            ?? FAM_ClaudeMemNormalize_Util.toStringId(raw.id);
+        if (!sourceRowId) {
+            warnings.push('Egy session_summary `sdk_session_id`/`id` nélkül érkezett — kihagyva.');
+            return null;
+        }
+        const text = FAM_ClaudeMemNormalize_Util.cleanString(raw.summary) ?? FAM_ClaudeMemNormalize_Util.cleanString(raw.text);
+        return {
+            entity: fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.sessionSummary,
+            sourceRowId: sourceRowId,
+            sdkSessionId: FAM_ClaudeMemNormalize_Util.cleanString(raw.sdk_session_id),
+            claudeSessionId: FAM_ClaudeMemNormalize_Util.cleanString(raw.claude_session_id),
+            project: FAM_ClaudeMemNormalize_Util.cleanString(raw.project),
+            title: FAM_ClaudeMemNormalize_Util.cleanString(raw.title),
+            text: text,
+            concepts: [],
+            filesRead: [],
+            filesModified: [],
+            createdAtEpoch: typeof raw.created_at_epoch === 'number' ? raw.created_at_epoch : undefined,
+        };
+    }
+    /**
+     * Egy user_prompt normalizálása (csak `includePrompts:true`). A `importSourceId` kulcsa a
+     * `claude_session_id`+`prompt_number` (`user_prompts:<claude_session_id>:<prompt_number>`).
+     */
+    static normalizePrompt(raw, warnings) {
+        const claudeSessionId = FAM_ClaudeMemNormalize_Util.cleanString(raw.claude_session_id);
+        const promptNumber = typeof raw.prompt_number === 'number' ? raw.prompt_number : undefined;
+        const sourceRowId = claudeSessionId !== undefined && promptNumber !== undefined
+            ? `${claudeSessionId}:${promptNumber}`
+            : FAM_ClaudeMemNormalize_Util.toStringId(raw.id);
+        if (!sourceRowId) {
+            warnings.push('Egy user_prompt azonosító nélkül érkezett — kihagyva.');
+            return null;
+        }
+        return {
+            entity: fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.userPrompt,
+            sourceRowId: sourceRowId,
+            sdkSessionId: FAM_ClaudeMemNormalize_Util.cleanString(raw.sdk_session_id),
+            claudeSessionId: claudeSessionId,
+            project: FAM_ClaudeMemNormalize_Util.cleanString(raw.project),
+            promptNumber: promptNumber,
+            title: FAM_ClaudeMemNormalize_Util.cleanString(raw.title),
+            text: FAM_ClaudeMemNormalize_Util.cleanString(raw.text),
+            concepts: [],
+            filesRead: [],
+            filesModified: [],
+            createdAtEpoch: typeof raw.created_at_epoch === 'number' ? raw.created_at_epoch : undefined,
+        };
+    }
+    /** Egy id (string vagy number) string-re — üres/undefined → ''. */
+    static toStringId(id) {
+        if (id === undefined || id === null) {
+            return '';
+        }
+        return String(id).trim();
+    }
+    /** Egy érték trim-elt string-ként (üres/nem-string → undefined). */
+    static cleanString(value) {
+        return typeof value === 'string' && value.trim().length ? value.trim() : undefined;
+    }
+    /** Egy érték string-tömbként (a nem-string elemek kiszűrve; nem-tömb → []). */
+    static cleanStringArray(value) {
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        return value.filter((item) => typeof item === 'string' && item.trim().length > 0)
+            .map((item) => item.trim());
+    }
+}
+exports.FAM_ClaudeMemNormalize_Util = FAM_ClaudeMemNormalize_Util;