@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/migration/_collections/fam-import-content-hash.util.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ImportContentHash_Util = void 0;
+const tslib_1 = require("tslib");
+const crypto = tslib_1.__importStar(require("crypto"));
+/**
+ * `FAM_ImportContentHash_Util` (SP-11.2, dsgn-009 §3) — a claude-mem import `contentHash`-e:
+ * `sha256(normalize(narrative + text + facts))`. A `normalize` a dsgn-009 §3 szerinti
+ * **whitespace-collapse + trim + lowercase** a hash-bemeneten — így az `importSourceId`-egyezés
+ * (1. lépcső) hiányában a `contentHash`-összevetés (2. lépcső) megbízhatóan kiszűri az azonos
+ * tartalmat más id alatt. Statikus util (egy implementáció — a fals-negatív dedup elkerülésére).
+ *
+ * **FIGYELEM:** ez a normalizálás SZÁNDÉKOSAN agresszívabb (lowercase + `\s+→' '`), mint a dsgn-004
+ * delta-detection `FAM_ContentHash_Util` (ami a SOR-szerkezetet megőrzi a kódstruktúra-jelentős
+ * sortörésekhez). Az import a TARTALMI ekvivalenciát keresi (más rendszerből importált, eltérő
+ * whitespace-/kis-nagybetű-formázású szöveg is duplikátum), ezért a teljes whitespace-collapse +
+ * lowercase a helyes — dsgn-009 §3.
+ */
+class FAM_ImportContentHash_Util {
+    /**
+     * Az import-tartalom SHA-256 ujjlenyomata (dsgn-009 §3). A `narrative`+`text`+`facts` összefűzve,
+     * normalizálva. Determinisztikus: ugyanaz a (normalizált) tartalom mindig ugyanazt a hash-t adja.
+     */
+    static hash(set) {
+        const composed = [set.narrative, set.text, set.facts]
+            .filter((part) => typeof part === 'string' && part.length > 0)
+            .join('\n');
+        return crypto.createHash('sha256').update(FAM_ImportContentHash_Util.normalize(composed)).digest('hex');
+    }
+    /**
+     * A dsgn-009 §3 normalizálás: minden whitespace-szekvencia EGY szóközre, trim, lowercase. Így a
+     * formázás-/kis-nagybetű-zaj NEM okoz fals-negatív content-dedup-ot.
+     */
+    static normalize(content) {
+        return content.replace(/\s+/g, ' ').trim().toLowerCase();
+    }
+}
+exports.FAM_ImportContentHash_Util = FAM_ImportContentHash_Util;

package/build/src/_modules/migration/_collections/fam-target-mapping.util.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_TargetMapping_Util = void 0;
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_claude_mem_interface_1 = require("../_models/interfaces/fam-claude-mem.interface");
+/**
+ * A §4 default target-mapping az observation `type`-okra (dsgn-009 §4 tábla). Ahol két tár jöhet szóba,
+ * az ELSŐ a default. A `decision`→knowledge, `bugfix`→coding_patterns, `feature`→memory,
+ * `refactor`→coding_patterns, `discovery`→knowledge, `change`→memory. Ismeretlen/hiányzó type → `change`.
+ */
+const OBSERVATION_TYPE_DEFAULTS = {
+    decision: { table: fam_table_type_enum_1.FAM_Table.knowledge, kind: 'knowledge', tags: ['decision_rationale'] },
+    bugfix: { table: fam_table_type_enum_1.FAM_Table.codingPatterns, kind: 'pattern', tags: ['debugging_pattern', 'bugfix'] },
+    feature: { table: fam_table_type_enum_1.FAM_Table.memory, kind: 'memory_entry', tags: ['development_history', 'feature'] },
+    refactor: { table: fam_table_type_enum_1.FAM_Table.codingPatterns, kind: 'pattern', tags: ['refactor'] },
+    discovery: { table: fam_table_type_enum_1.FAM_Table.knowledge, kind: 'knowledge', tags: ['fact', 'discovery'] },
+    change: { table: fam_table_type_enum_1.FAM_Table.memory, kind: 'memory_entry', tags: ['development_history', 'change'] },
+};
+/** A nem-observation entitások default-leképezése (dsgn-009 §4). */
+const ENTITY_DEFAULTS = {
+    [fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.sessionSummary]: { table: fam_table_type_enum_1.FAM_Table.memory, kind: 'summary', tags: ['session_history'] },
+    [fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.userPrompt]: { table: fam_table_type_enum_1.FAM_Table.memory, kind: 'user_prompt', tags: ['temporary_context'] },
+};
+/**
+ * `FAM_TargetMapping_Util` (SP-11.2, dsgn-009 §4) — egy normalizált claude-mem rekord → cél-leképezés
+ * (table + kind + tags + content). Statikus, tisztán determinista (nincs DB/async): a `project`→scope
+ * feloldás KÜLÖN, a engine-ben (MP-3 `resolveForWrite`) megy. A §4 default leképezést alkalmazza, majd
+ * az override-okat (`byType` / `byId`) ráhúzza; a `concepts[]` további tag-ekként hozzáfűződik.
+ */
+class FAM_TargetMapping_Util {
+    /**
+     * A `importSourceId` ELSŐDLEGES dedup-kulcs (dsgn-009 §3 tábla): `<forrás-tábla>:<row id>`. Az
+     * entitás-enum értéke MÁR a forrás-tábla neve (`observations` / `session_summaries` / `user_prompts`).
+     */
+    static importSourceId(record) {
+        return `${record.entity}:${record.sourceRowId}`;
+    }
+    /**
+     * A cél-tár + kind + tags feloldása (default → override). Az observation a `type`-ról, a
+     * summary/prompt az entitás-default-ról; ismeretlen → `change` (memory). Az override (`byId`
+     * elsőbbség a `byType` előtt) szelektíven felülír; a `concepts[]` mindig tag-ként hozzáfűződik
+     * (kivéve ha az override teljes tag-cserét ad — akkor is hozzáfűzzük a concept-eket a provenance-hoz).
+     */
+    static resolveTarget(set) {
+        const base = FAM_TargetMapping_Util.defaultFor(set.record);
+        const importSourceId = FAM_TargetMapping_Util.importSourceId(set.record);
+        const byType = set.record.type ? set.overrides?.byType?.[set.record.type] : undefined;
+        const byId = set.overrides?.byId?.[importSourceId];
+        // Precedencia: byId > byType > default.
+        const table = byId?.table ?? byType?.table ?? base.table;
+        const kind = byId?.kind ?? byType?.kind ?? base.kind;
+        const baseTags = byId?.tags ?? byType?.tags ?? base.tags;
+        // A concept-ek további tag-ekként (dedup-olva, üres kiszűrve) — provenance.
+        const tags = FAM_TargetMapping_Util.mergeTags(baseTags, set.record.concepts);
+        return { table: table, kind: kind, tags: tags };
+    }
+    /**
+     * A vektorizálandó content-kompozíció (dsgn-009 §4): `join(title, subtitle, narrative, text, facts)`.
+     * Az üres mezők kihagyva; sortöréssel fűzve (a szemantikai jel maximalizálásához). Summary/prompt
+     * esetén a `text` hordozza a tartalmat (a `narrative`/`facts` üres) — a join ezt is lefedi.
+     */
+    static composeContent(record) {
+        return [record.title, record.subtitle, record.narrative, record.text, record.facts]
+            .filter((part) => typeof part === 'string' && part.trim().length > 0)
+            .map((part) => part.trim())
+            .join('\n');
+    }
+    /** A default target egy rekordra: observation → `type`-default (ismeretlen → `change`); egyébként entitás-default. */
+    static defaultFor(record) {
+        if (record.entity === fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.observation) {
+            const type = record.type ?? 'change';
+            return OBSERVATION_TYPE_DEFAULTS[type] ?? OBSERVATION_TYPE_DEFAULTS.change;
+        }
+        return ENTITY_DEFAULTS[record.entity] ?? { table: fam_table_type_enum_1.FAM_Table.memory, kind: 'memory_entry', tags: [] };
+    }
+    /** A base-tag-ek + a concept-tag-ek egyesítése (rendezett dedup, üres kiszűrve). */
+    static mergeTags(baseTags, concepts) {
+        const seen = new Set();
+        const result = [];
+        for (const tag of [...baseTags, ...concepts]) {
+            const clean = (tag ?? '').trim();
+            if (clean.length && !seen.has(clean)) {
+                seen.add(clean);
+                result.push(clean);
+            }
+        }
+        return result;
+    }
+}
+exports.FAM_TargetMapping_Util = FAM_TargetMapping_Util;

package/build/src/_modules/migration/_enums/fam-claude-mem-source.type-enum.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemSource_Type = void 0;
+/**
+ * A claude-mem import forrás-csatorna (dsgn-009 §1 tábla). A `from` lokátor választja meg, melyik
+ * reader olvas: export-JSON (default, függőség-mentes), SQLite (build-only, BFR-AM-009 fallback),
+ * live worker-api (opcionális).
+ *
+ * Enum-konvenció (workspace base CLAUDE.md): key camelCase, value kebab-case (a wire-érték a
+ * dsgn-009 §1 string-je; ez kerül a `write.import.from` / capability `from` argumentumba).
+ */
+var FAM_ClaudeMemSource_Type;
+(function (FAM_ClaudeMemSource_Type) {
+    /** Export-JSON fájl (`<path>.json`) — MVP1 default, csak `JSON.parse` (függőség-mentes). */
+    FAM_ClaudeMemSource_Type["exportJson"] = "export-json";
+    /** SQLite DB (`~/.claude-mem/claude-mem.db`) — build-only izolált függőség (BFR-AM-009 fallback). */
+    FAM_ClaudeMemSource_Type["sqlite"] = "sqlite";
+    /** Live worker-api (`http://localhost:<port>`) — opcionális, csak ha a worker fut. */
+    FAM_ClaudeMemSource_Type["workerApi"] = "worker-api";
+})(FAM_ClaudeMemSource_Type || (exports.FAM_ClaudeMemSource_Type = FAM_ClaudeMemSource_Type = {}));

package/build/src/_modules/migration/_models/interfaces/fam-claude-mem.interface.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemEntity_Type = void 0;
+/**
+ * claude-mem migráció shared vokabulár (MP-11, dsgn-009). Egy fájlban a szorosan összetartozó
+ * import-/dedup-/mapping-/flow-típusok (`*.interface.ts` az egy-export-per-file konvenció ismert
+ * kivétele, mint a `fam-common.interface.ts`). A `FAM_Entry` / `importSource` / `importSourceId` /
+ * `contentHash` mezőket NEM redefiniáljuk — dsgn-001 §2 a szerződés; ITT a forrás-shape + a
+ * normalizált köztes rekord + a leképezés/flow I/O él.
+ */
+/**
+ * A claude-mem entitás-típusa a normalizált köztes rekordban (dsgn-009 §2). A `observation` a fő
+ * forrás; a `session_summary`/`user_prompt` leszármaztatott entry; a `session` NEM önálló entry
+ * (metaadat — `project`→scope + sessionId/runId hidratálás), ezért NEM a normalizált halmazban.
+ *
+ * Enum-konvenció: key camelCase, value a forrás-tábla neve (a `importSourceId` prefixe is ez).
+ */
+var FAM_ClaudeMemEntity_Type;
+(function (FAM_ClaudeMemEntity_Type) {
+    /** observations — a migráció gerince (`type`-tól függő cél-tár, dsgn-009 §4). */
+    FAM_ClaudeMemEntity_Type["observation"] = "observations";
+    /** session_summaries — `memory` (`kind=summary`). */
+    FAM_ClaudeMemEntity_Type["sessionSummary"] = "session_summaries";
+    /** user_prompts — opcionális (`memory`, `kind=user_prompt`); default OFF. */
+    FAM_ClaudeMemEntity_Type["userPrompt"] = "user_prompts";
+})(FAM_ClaudeMemEntity_Type || (exports.FAM_ClaudeMemEntity_Type = FAM_ClaudeMemEntity_Type = {}));

package/build/src/_modules/migration/_services/fam-claude-mem-export-reader.service.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemExportReader_Service = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_claude_mem_source_type_enum_1 = require("../_enums/fam-claude-mem-source.type-enum");
+const fam_claude_mem_normalize_util_1 = require("../_collections/fam-claude-mem-normalize.util");
+/**
+ * `FAM_ClaudeMemExportReader_Service` (SP-11.1) — az **export-JSON reader** (MVP1 DEFAULT,
+ * függőség-mentes). A claude-mem export-wrapper-t (`{ observations[], sessions[], summaries[],
+ * prompts[] }`, dsgn-009 §1.1) `JSON.parse`-olja, majd a közös normalizálóra adja. Statikus util-szerű
+ * service (nincs DB-/external-függőség; egy belépési pont). NEM az LLM-facing MCP-toolokon megy át —
+ * közvetlenül a fájlból olvas (dsgn-009 §1 dedikált bulk import adapter).
+ *
+ * **Defenzív parse (dsgn-009 §9):** fájl-hiány / nem-JSON / nem-objektum → tiszta strukturált hiba
+ * (`FAM-IMP-SOURCE-001`), NEM hang/crash; hiányzó vagy nem-tömb mező → warning + üres lista (a többi
+ * mező feldolgozva). A deklarált `total*` és a tényleges hossz eltérése drift-warning.
+ */
+class FAM_ClaudeMemExportReader_Service {
+    static _instance;
+    /** Default issuer (a forrás-hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_ClaudeMemExportReader_Service';
+    static getInstance() {
+        if (!FAM_ClaudeMemExportReader_Service._instance) {
+            FAM_ClaudeMemExportReader_Service._instance = new FAM_ClaudeMemExportReader_Service();
+        }
+        return FAM_ClaudeMemExportReader_Service._instance;
+    }
+    /**
+     * Az export-JSON fájl beolvasása + parse + normalizálás (SP-11.1). A `path` az export-fájl
+     * útvonala. Fájl-hiány / parse-hiba → `FAM-IMP-SOURCE-001` (deskriptív). A normalizált rekordokat
+     * + a session-metaadatot + a counts-ot + a defenzív warning-okat adja.
+     */
+    read(set) {
+        if (!set.path || !set.path.trim().length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: 'Az export-JSON importhoz `path` kötelező (a claude-mem export-fájl útvonala).',
+                issuer: this.issuer,
+                context: { operation: 'import-read-export-json' },
+            });
+        }
+        if (!fs.existsSync(set.path)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem export-JSON fájl nem található: '${set.path}'. Ellenőrizd az útvonalat `
+                    + '(a default forrás `~/.claude-mem`-ből exportált JSON).',
+                issuer: this.issuer,
+                context: { operation: 'import-read-export-json' },
+            });
+        }
+        const rawText = this.readFile(set.path);
+        const wrapper = this.parseWrapper(rawText, set.path);
+        const warnings = [];
+        const observations = this.asArray(wrapper.observations, 'observations', warnings);
+        const summaries = this.asArray(wrapper.summaries, 'summaries', warnings);
+        const prompts = this.asArray(wrapper.prompts, 'prompts', warnings);
+        const sessions = this.asArray(wrapper.sessions, 'sessions', warnings);
+        // Drift-ellenőrzés: a deklarált total* és a tényleges hossz eltérése (nem-néma, csak warning).
+        this.checkDrift(wrapper.totalObservations, observations.length, 'observations', warnings);
+        this.checkDrift(wrapper.totalSummaries, summaries.length, 'summaries', warnings);
+        this.checkDrift(wrapper.totalPrompts, prompts.length, 'prompts', warnings);
+        this.checkDrift(wrapper.totalSessions, sessions.length, 'sessions', warnings);
+        const normalized = fam_claude_mem_normalize_util_1.FAM_ClaudeMemNormalize_Util.normalizeAll({
+            from: fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.exportJson,
+            observations: observations, summaries: summaries, prompts: prompts, sessions: sessions,
+            includePrompts: set.includePrompts,
+        });
+        normalized.warnings = [...warnings, ...normalized.warnings];
+        return normalized;
+    }
+    /** A fájl beolvasása UTF-8-ként; I/O-hiba → `FAM-IMP-SOURCE-001`. */
+    readFile(path) {
+        try {
+            return fs.readFileSync(path, 'utf-8');
+        }
+        catch (error) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem export-JSON fájl nem olvasható: '${path}'.`,
+                issuer: this.issuer,
+                context: { operation: 'import-read-export-json' },
+                cause: error,
+            });
+        }
+    }
+    /** A nyers szöveg parse-olása export-wrapper-ré; nem-JSON / nem-objektum → `FAM-IMP-SOURCE-001`. */
+    parseWrapper(rawText, path) {
+        let parsed;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch (error) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem export-JSON nem érvényes JSON: '${path}'.`,
+                issuer: this.issuer,
+                context: { operation: 'import-read-export-json' },
+                cause: error,
+            });
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem export-JSON gyökere nem objektum (várt: { observations[], sessions[], `
+                    + `summaries[], prompts[] }): '${path}'.`,
+                issuer: this.issuer,
+                context: { operation: 'import-read-export-json' },
+            });
+        }
+        return parsed;
+    }
+    /** Egy mező tömbként; hiányzó/nem-tömb → warning + []. */
+    asArray(value, field, warnings) {
+        if (value === undefined || value === null) {
+            return [];
+        }
+        if (!Array.isArray(value)) {
+            warnings.push(`A '${field}' mező nem tömb az export-JSON-ban — üres listaként kezelve.`);
+            return [];
+        }
+        return value;
+    }
+    /** A deklarált total és a tényleges hossz eltérésének warning-ja (nem-néma drift-jelzés). */
+    checkDrift(declared, actual, field, warnings) {
+        if (typeof declared === 'number' && declared !== actual) {
+            warnings.push(`A '${field}' deklarált száma (${declared}) eltér a tényleges hossztól (${actual}) — `
+                + 'lehetséges export-drift.');
+        }
+    }
+}
+exports.FAM_ClaudeMemExportReader_Service = FAM_ClaudeMemExportReader_Service;