@futdevpro/fdp-agent-memory 1.1.119 → 1.1.130

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@futdevpro/fdp-agent-memory",
-    "version": "1.1.119",
+    "version": "1.1.130",
     "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
     "private": false,
     "publishConfig": {

package/build/src/_cli/_commands/read.command.js

@@ -89,18 +89,41 @@ class FAM_Read_Util {
             humanFormatter: (data) => FAM_Read_Util.formatHuman(data),
         });
     }
-    /** Ember-olvasható read-kimenet: query-nként a hits + a dense-jelzés kötelező kiemelése (REQ-007). */
+    /**
+     * Ember-olvasható read-kimenet: query-nként a `summary` (operatív visszajelzés) + a találatok ÚTVONALLAL, majd a
+     * konkrét következő lépések (`hints`). 2026-07-29 bővítés: eddig csak `[score] id + előnézet` volt — sem az
+     * ÚTVONAL (a „nem állnak össze a fájl-útvonalak" panasz), sem a „mennyiből mennyit látok" nem látszott.
+     */
     static formatHuman(data) {
         const results = data.results ?? [];
         const lines = [];
         for (const block of results) {
-            lines.push(`\n● "${block.query ?? ''}"  [${(block.tables ?? []).join(', ')}]  (${block.totalRelevant ?? block.hits?.length ?? 0} relevant)`);
+            lines.push(`\n● "${block.query ?? ''}"  [${(block.tables ?? []).join(', ')}]`);
+            if (block.summary) {
+                lines.push(`  ${block.summary}`);
+            }
+            else {
+                lines.push(`  (${block.totalRelevant ?? block.hits?.length ?? 0} relevant)`);
+            }
             if (block.denseResults) {
                 lines.push(`  ⚑ DENSE RESULTS — szűkítsd: ${(block.suggestions ?? []).join(' | ') || '(adj scope-ot/tag-et)'}`);
             }
             for (const hit of block.hits ?? []) {
                 const preview = (hit.content ?? '').replace(/\s+/g, ' ').slice(0, 100);
-                lines.push(`  - [${(hit.score ?? 0).toFixed(3)}] ${hit.id ?? ''}  ${preview}`);
+                // A MEGNYITHATÓ útvonal + a fájlon belüli hely — enélkül a találatból nem lehetett visszatalálni a forráshoz.
+                const location = hit.path
+                    ? `${hit.path}${hit.lines ? `:${hit.lines}` : ''}`
+                    : (hit.id ?? '');
+                lines.push(`  - [${(hit.score ?? 0).toFixed(3)}] ${location}`);
+                if (hit.heading) {
+                    lines.push(`      ${hit.heading}`);
+                }
+                if (preview) {
+                    lines.push(`      ${preview}`);
+                }
+            }
+            for (const hint of block.hints ?? []) {
+                lines.push(`  → ${hint}`);
             }
         }
         return lines.join('\n');

package/build/src/_cli/_commands/remote.command.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Remote_Util = void 0;
+const commander_1 = require("commander");
+const fam_remote_config_util_1 = require("../../_collections/fam-remote-config.util");
+const fam_output_util_1 = require("../_collections/fam-output.util");
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+const fam_client_service_1 = require("../_services/fam-client.service");
+/**
+ * `fam remote show|set|clear` — a TÁVOLI ELÉRÉS beállítása (user-FR 2026-07-28: „kéne építsünk a FAM-hoz beállítást,
+ * hogy távoli elérésként is működhessen — pl. virtuális gépről a host-ra kapcsolva, hogy a host futtat, de a VM is
+ * eléri, más címen/útvonalon").
+ *
+ * A beállítás a gép-lokális `~/.fam/config.json`-ben él (NEM a DB-config — az a szerveren van, amihez épp csatlakozni
+ * akarunk; és NEM új env-var — a hookok/MCP/CLI külön process-ek, egy fájl mindnek szól).
+ *
+ * **Tipikus VM→host setup:**
+ * - HOST-on: `fam remote set --bind 192.168.56.1` (a host-only adapter IP-je) + `fam serve --restart`
+ * - VM-ben:  `fam remote set --url http://192.168.56.1:39265` → a VM CLI/hook/MCP a hostot használja
+ * - Reverse proxy mögött: `fam remote set --url https://host.local/fam` (az útvonal-prefix támogatott)
+ */
+class FAM_Remote_Util {
+    /** A `remote` parancs-deszkriptor (show/set/clear alparanccsal). */
+    static command() {
+        const command = new commander_1.Command('remote');
+        command.description('Távoli elérés beállítása (~/.fam/config.json): kliens szerver-URL + szerver bind-host');
+        command.addCommand(FAM_Remote_Util.showCommand());
+        command.addCommand(FAM_Remote_Util.setCommand());
+        command.addCommand(FAM_Remote_Util.clearCommand());
+        return command;
+    }
+    /** `remote show` — az aktuális (feloldott) beállítás + a tényleges elérhetőség. */
+    static showCommand() {
+        const command = new commander_1.Command('show');
+        command
+            .description('A jelenlegi távoli-elérés beállítás + elérhetőség-próba')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Remote_Util.runShow(command));
+        });
+        return command;
+    }
+    /** `remote set` — a szerver-URL és/vagy a bind-host beállítása. */
+    static setCommand() {
+        const command = new commander_1.Command('set');
+        command
+            .description('A kliens szerver-URL és/vagy a szerver bind-host beállítása')
+            .option('--url <url>', 'KLIENS: a FAM szerver base-URL-je (útvonal-prefix is lehet, pl. https://host/fam)')
+            .option('--bind <host>', 'SZERVER: bind-host (127.0.0.1 = csak lokális, 0.0.0.0 vagy "*" = minden interfész, '
+            + 'vagy egy konkrét adapter-IP). Csak a szerver ÚJRAINDÍTÁSA után lép életbe.')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Remote_Util.runSet(command));
+        });
+        return command;
+    }
+    /** `remote clear` — a beállítások törlése (vissza a lokális default-ra). */
+    static clearCommand() {
+        const command = new commander_1.Command('clear');
+        command
+            .description('A távoli-elérés beállítások törlése (vissza a lokális default-ra)')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Remote_Util.runClear(command));
+        });
+        return command;
+    }
+    /** A `remote show` futtatása: a feloldott értékek + honnan jönnek + elérhető-e a szerver. */
+    static async runShow(command) {
+        const globals = command.optsWithGlobals();
+        const file = fam_remote_config_util_1.FAM_RemoteConfig_Util.load();
+        const serverUrl = fam_remote_config_util_1.FAM_RemoteConfig_Util.resolveServerUrl({
+            override: globals.serverUrl, env: process.env.FAM_SERVER_URL, file: file,
+        });
+        const bindHost = fam_remote_config_util_1.FAM_RemoteConfig_Util.resolveBindHost({ env: process.env.FAM_SERVER_HOST, file: file });
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        return fam_output_util_1.FAM_Output_Util.success({
+            options: globals,
+            command: 'remote show',
+            data: {
+                configPath: fam_remote_config_util_1.FAM_RemoteConfig_Util.CONFIG_PATH,
+                serverUrl: serverUrl,
+                serverUrlFrom: FAM_Remote_Util.describeSource(globals.serverUrl, process.env.FAM_SERVER_URL, file.serverUrl),
+                bindHost: bindHost,
+                bindHostFrom: FAM_Remote_Util.describeSource(undefined, process.env.FAM_SERVER_HOST, file.bindHost),
+                bindIsLoopbackOnly: fam_remote_config_util_1.FAM_RemoteConfig_Util.isLoopbackHost(bindHost),
+                reachable: await client.isReachable(),
+            },
+        });
+    }
+    /** A `remote set` futtatása. */
+    static async runSet(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        if (!local.url && !local.bind) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals, command: 'remote set',
+                error: {
+                    errorCode: 'FAM-CLI-REMOTE-001',
+                    message: 'Adj meg legalább egyet: `--url` (kliens) vagy `--bind` (szerver).',
+                    fixHint: 'Pl. VM-ből a hostra: `fam remote set --url http://192.168.56.1:39265`; '
+                        + 'a hoston: `fam remote set --bind 192.168.56.1` + `fam serve --restart`.',
+                },
+                exitCode: fam_cli_const_1.FAM_CliExitCode.usageError,
+            });
+        }
+        const saved = fam_remote_config_util_1.FAM_RemoteConfig_Util.save({ serverUrl: local.url, bindHost: local.bind });
+        const notes = [];
+        if (local.bind) {
+            notes.push('A bind-host CSAK a szerver újraindítása után lép életbe: `fam serve --restart`.');
+            const effective = fam_remote_config_util_1.FAM_RemoteConfig_Util.resolveBindHost({ file: saved });
+            if (!fam_remote_config_util_1.FAM_RemoteConfig_Util.isLoopbackHost(effective)) {
+                notes.push('FIGYELEM: a FAM-nak NINCS authentikációja (ADR-004) — a nem-loopback bind a TELJES '
+                    + 'korpuszt elérhetővé teszi az adott hálózaton. Csak megbízható (host-only / VPN) hálón használd.');
+            }
+        }
+        return fam_output_util_1.FAM_Output_Util.success({
+            options: globals, command: 'remote set',
+            data: { configPath: fam_remote_config_util_1.FAM_RemoteConfig_Util.CONFIG_PATH, config: saved, notes: notes },
+        });
+    }
+    /** A `remote clear` futtatása. */
+    static async runClear(command) {
+        const globals = command.optsWithGlobals();
+        const saved = fam_remote_config_util_1.FAM_RemoteConfig_Util.save({ serverUrl: null, bindHost: null });
+        return fam_output_util_1.FAM_Output_Util.success({
+            options: globals, command: 'remote clear',
+            data: { configPath: fam_remote_config_util_1.FAM_RemoteConfig_Util.CONFIG_PATH, config: saved,
+                notes: ['Vissza a lokális default-ra (kliens: http://127.0.0.1:39265, bind: 127.0.0.1). '
+                        + 'A bind változás a szerver újraindításakor lép életbe.'] },
+        });
+    }
+    /** Melyik forrásból jött a feloldott érték (flag > env > fájl > default) — a `show` átláthatóságához (PURE). */
+    static describeSource(flag, env, file) {
+        if (flag?.trim()) {
+            return 'flag (--server-url)';
+        }
+        if (env?.trim()) {
+            return 'env';
+        }
+        return file?.trim() ? 'config-fájl (~/.fam/config.json)' : 'beépített default';
+    }
+}
+exports.FAM_Remote_Util = FAM_Remote_Util;

package/build/src/_cli/_services/fam-client.service.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_CliClient_Service = void 0;
-const fam_cli_const_1 = require("../_collections/fam-cli.const");
+const fam_remote_config_util_1 = require("../../_collections/fam-remote-config.util");
 /**
  * `FAM_CliClient_Service` — a CLI → szerver elérési réteg (dsgn-010 §9). A `read`/`write`/`scan`/
  * `stats`/`errors`/`config`/`capabilities` parancsok ezen át hívják a futó szerver REST-felületét
@@ -25,8 +25,12 @@ class FAM_CliClient_Service {
      *        `FAM_SERVER_URL`, különben a `FAM_DEFAULT_SERVER_URL`.
      */
     constructor(serverUrlOverride) {
-        const raw = serverUrlOverride || process.env.FAM_SERVER_URL || fam_cli_const_1.FAM_DEFAULT_SERVER_URL;
-        this.baseUrl = raw.replace(/\/+$/, '');
+        // TÁVOLI ELÉRÉS (user-FR 2026-07-28): a `~/.fam/config.json` `serverUrl`-je is beleszól — így egy VM-ből a
+        // host-on futó FAM elérhető anélkül, hogy MINDEN hívóhoz (CLI/hook/MCP külön process!) env-et kellene fűzni.
+        // Precedencia: `--server-url` flag > `FAM_SERVER_URL` env > config-fájl > `http://127.0.0.1:39265`.
+        this.baseUrl = fam_remote_config_util_1.FAM_RemoteConfig_Util.resolveServerUrl({
+            override: serverUrlOverride, env: process.env.FAM_SERVER_URL, file: fam_remote_config_util_1.FAM_RemoteConfig_Util.load(),
+        });
     }
     /** A feloldott szerver base-URL (a fix-tippekhez / diaghoz). */
     getBaseUrl() {

package/build/src/_cli/register-commands.js

@@ -17,6 +17,7 @@ const seed_command_1 = require("./_commands/seed.command");
 const import_command_1 = require("./_commands/import.command");
 const export_command_1 = require("./_commands/export.command");
 const capture_command_1 = require("./_commands/capture.command");
+const remote_command_1 = require("./_commands/remote.command");
 /**
  * Regisztrálja az összes FDP Agent Memory-specifikus CLI command-ot (dsgn-010 §2 `buildCli()`).
  *
@@ -52,6 +53,7 @@ function registerFAMCommands(program, version) {
         export_command_1.FAM_Export_Util.command(),
         capture_command_1.FAM_Capture_Util.command(),
         config_command_1.FAM_Config_Util.command(),
+        remote_command_1.FAM_Remote_Util.command(),
         stats_command_1.FAM_Stats_Util.command(),
         find_duplicates_command_1.FAM_FindDuplicates_Util.command(),
         errors_command_1.FAM_Errors_Util.command(),

package/build/src/_collections/config-catalog.const.js

@@ -71,12 +71,36 @@ exports.CONFIG_CATALOG = {
     // --- 4.1. Read / retrieval limitek (fogyasztó: dsgn-005) ---
     'read.topK': {
         type: 'number', default: 5, min: 1, max: 200, integer: true, levels: ALL_LEVELS,
-        description: 'Alap visszaadott találat-szám (CCAP DEFAULT_TOP_K=5).',
+        // PER-TÁR default (user-FR 2026-07-28): „amikor rule-okat vagy más FONTOS dolgot keresünk, ott nagyobb max
+        // találattal kell dolgozni, hogy MINDEN fontos elem/szabály MINDIG belekerüljön". A `rules` a legkritikusabb
+        // (egy hard-rule kimaradása = rossz döntés), utána a kurált `coding_patterns` / `knowledge` / `memory`. A
+        // `documents`/`codebase` marad az 5-ös alapon (ott a nagy korpusz miatt a szűk top-N a helyes — a `depth:'deep'`
+        // (`read.deepTopK`) adja a mély feltárást).
+        defaultsByTable: {
+            [fam_table_type_enum_1.FAM_Table.rules]: 30,
+            [fam_table_type_enum_1.FAM_Table.codingPatterns]: 20,
+            [fam_table_type_enum_1.FAM_Table.knowledge]: 15,
+            [fam_table_type_enum_1.FAM_Table.memory]: 15,
+        },
+        description: 'Alap visszaadott találat-szám (CCAP DEFAULT_TOP_K=5). **Per-tár default** (user-FR 2026-07-28): '
+            + '`rules` 30 · `coding_patterns` 20 · `knowledge`/`memory` 15 — hogy a FONTOS elemek (kanonikus szabályok, '
+            + 'kurált minták/tanulságok) MIND beleférjenek, ne csak a top-5. A `documents`/`codebase` marad 5 (nagy '
+            + 'korpusz → szűk top-N; a mély feltárás a `depth:"deep"` / `read.deepTopK`). Bármely EXPLICIT beállítás '
+            + '(scope/table/global) felülírja a per-tár default-ot.',
     },
     'read.deepTopK': {
         type: 'number', default: 25, min: 1, max: 200, integer: true, levels: ALL_LEVELS,
+        // A mély feltárás a FONTOS tárakon még bőségesebb (a normál per-tár topK FÖLÖTT kell maradnia — user-FR 2026-07-28).
+        defaultsByTable: {
+            [fam_table_type_enum_1.FAM_Table.rules]: 60,
+            [fam_table_type_enum_1.FAM_Table.codingPatterns]: 40,
+            [fam_table_type_enum_1.FAM_Table.knowledge]: 35,
+            [fam_table_type_enum_1.FAM_Table.memory]: 35,
+        },
         description: 'A `depth:"deep"` (mély feltárás) read-mód találat-száma: ennyit ad vissza, ha a query NEM '
-            + 'ad explicit topK-t. Sokkal több chunk/kontextus egy-egy mély feltáráshoz (a query topK felülírja).',
+            + 'ad explicit topK-t. Sokkal több chunk/kontextus egy-egy mély feltáráshoz (a query topK felülírja). '
+            + '**Per-tár default:** `rules` 60 · `coding_patterns` 40 · `knowledge`/`memory` 35 — a fontos tárak mély '
+            + 'feltárása a normál per-tár topK FÖLÖTT maradjon.',
     },
     'read.maxResults': {
         type: 'number', default: 50, min: 1, max: 500, integer: true, levels: ALL_LEVELS,
@@ -84,6 +108,14 @@ exports.CONFIG_CATALOG = {
     },
     'read.maxTokens': {
         type: 'number', default: 4000, min: 256, max: 32000, integer: true, levels: ALL_LEVELS,
+        // A megemelt per-tár topK ÖNMAGÁBAN nem elég: a token-budget levágná a többletet (a 30 szabály ~15k char ≈
+        // 3,7k token → a 4000-es budget pont elvágná). A fontos tárakon ezért a budget is arányosan nő (user-FR 2026-07-28).
+        defaultsByTable: {
+            [fam_table_type_enum_1.FAM_Table.rules]: 12000,
+            [fam_table_type_enum_1.FAM_Table.codingPatterns]: 8000,
+            [fam_table_type_enum_1.FAM_Table.knowledge]: 8000,
+            [fam_table_type_enum_1.FAM_Table.memory]: 8000,
+        },
         description: 'Az agent context védelme + a read-válasz INLINE-tartása (max token; ~4 char/token). A read-tool '
             + 'ÉRVÉNYESÍTI (FAM-REV: korábban dead-config volt → korlátlan hit-tartalom → a host fájlba mentette a választ). '
             + 'A budget felett a hit-tartalom levágódik + a túlcsorduló hit-ek elhagyva (`truncated:true`).',

package/build/src/_collections/fam-remote-config.util.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RemoteConfig_Util = void 0;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/**
+ * `FAM_RemoteConfig_Util` — a gép-lokális `~/.fam/config.json` olvasása/írása + a TÁVOLI ELÉRÉS feloldása
+ * (user-FR 2026-07-28: „kéne építsünk a FAM-hoz beállítást, hogy távoli elérésként is működhessen — pl. virtuális
+ * gépről a host-ra kapcsolva, hogy a host futtat, de a VM is eléri, más címen/útvonalon").
+ *
+ * **Miért fájl és nem (új) env-var?** Az env csak abban a process-fában él, ahol beállították — a CC-hookok, az MCP-
+ * adapter és a CLI KÜLÖN process-ek, így env-vel mindegyiket külön kéne felkonfigurálni (és a workspace-guardrail is
+ * tiltja az új env-kulcsok szaporítását). A fájl EGY helyen, perzisztensen, minden hívónak érvényes. A MEGLÉVŐ
+ * `FAM_SERVER_URL` env továbbra is működik és ERŐSEBB a fájlnál (ad-hoc felülírás).
+ *
+ * **Precedencia (kliens):** `--server-url` flag > `FAM_SERVER_URL` env > `~/.fam/config.json` > `http://127.0.0.1:39265`.
+ * **Precedencia (szerver bind):** `FAM_SERVER_HOST` env > `~/.fam/config.json` > `127.0.0.1`.
+ */
+class FAM_RemoteConfig_Util {
+    /** A gép-lokális config-fájl útja (`~/.fam/config.json`). */
+    static CONFIG_PATH = (0, path_1.join)((0, os_1.homedir)(), '.fam', 'config.json');
+    /** A kliens-default (változatlan visszafelé-kompatibilis érték). */
+    static DEFAULT_SERVER_URL = 'http://127.0.0.1:39265';
+    /**
+     * A szerver BIND-default: **loopback**. Biztonsági alapállás — a FAM-nak nincs authja (ADR-004), ezért
+     * alapból NEM hallgatózik a hálózaton; a távoli elérés EXPLICIT opt-in (`bindHost`).
+     */
+    static DEFAULT_BIND_HOST = '127.0.0.1';
+    /**
+     * A config-fájl beolvasása. Best-effort: hiányzó/olvashatatlan/érvénytelen JSON → üres objektum (a FAM
+     * default-okkal indul; egy elrontott fájl SOHA nem akadályozhatja meg a szerver indulását).
+     */
+    static load() {
+        try {
+            if (!(0, fs_1.existsSync)(FAM_RemoteConfig_Util.CONFIG_PATH)) {
+                return {};
+            }
+            const parsed = JSON.parse((0, fs_1.readFileSync)(FAM_RemoteConfig_Util.CONFIG_PATH, 'utf8'));
+            if (!parsed || typeof parsed !== 'object') {
+                return {};
+            }
+            const raw = parsed;
+            return {
+                serverUrl: typeof raw.serverUrl === 'string' && raw.serverUrl.trim() ? raw.serverUrl.trim() : undefined,
+                bindHost: typeof raw.bindHost === 'string' && raw.bindHost.trim() ? raw.bindHost.trim() : undefined,
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    /** A config-fájl MÓDOSÍTÁSA (merge a meglévővel; a mappát létrehozza). A `null` érték TÖRLI a kulcsot. */
+    static save(patch) {
+        const current = FAM_RemoteConfig_Util.load();
+        const next = { ...current };
+        if (patch.serverUrl !== undefined) {
+            next.serverUrl = patch.serverUrl === null ? undefined : patch.serverUrl.trim();
+        }
+        if (patch.bindHost !== undefined) {
+            next.bindHost = patch.bindHost === null ? undefined : patch.bindHost.trim();
+        }
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(FAM_RemoteConfig_Util.CONFIG_PATH), { recursive: true });
+        (0, fs_1.writeFileSync)(FAM_RemoteConfig_Util.CONFIG_PATH, `${JSON.stringify(next, null, 4)}\n`, 'utf8');
+        return next;
+    }
+    /**
+     * A KLIENS szerver-URL feloldása (PURE, tesztelhető — a bemenetek explicitek).
+     * Precedencia: flag > env > fájl > default. A záró `/`-eket levágja (a hívó `${base}/api/...`-t fűz).
+     */
+    static resolveServerUrl(set) {
+        const raw = set.override?.trim()
+            || set.env?.trim()
+            || set.file?.serverUrl?.trim()
+            || FAM_RemoteConfig_Util.DEFAULT_SERVER_URL;
+        return raw.replace(/\/+$/, '');
+    }
+    /**
+     * A SZERVER bind-host feloldása (PURE). Precedencia: env > fájl > loopback-default.
+     * A `'*'` kényelmi alias a `0.0.0.0`-ra (minden interfész).
+     */
+    static resolveBindHost(set) {
+        const raw = set.env?.trim() || set.file?.bindHost?.trim() || FAM_RemoteConfig_Util.DEFAULT_BIND_HOST;
+        return raw === '*' ? '0.0.0.0' : raw;
+    }
+    /**
+     * Loopback-e a bind (PURE)? A nem-loopback bind FIGYELMEZTETÉST érdemel: a FAM auth NÉLKÜLI (ADR-004), így a
+     * hálózaton bárki írhatja/olvashatja a teljes korpuszt. Csak megbízható (host-only/VPN) hálón indokolt.
+     */
+    static isLoopbackHost(host) {
+        return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+    }
+}
+exports.FAM_RemoteConfig_Util = FAM_RemoteConfig_Util;

package/build/src/_modules/mcp/_collections/fam-read-response-shape.util.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ReadResponseShape_Util = void 0;
+/**
+ * `FAM_ReadResponseShape_Util` — a `read` VÁLASZ-FORMÁZÁSA az agent-fogyasztóknak (user-FR 2026-07-29, agent-panaszok:
+ * „a FAM túl nagy csomag válaszokat ad" / „formázatlan, tördeletlen egy soros válaszokat kapnak" / „az eredményekből
+ * kiolvasható fájl elérési útvonalak nem állnak össze").
+ *
+ * **Alapelv: NULLA információ-veszteség.** Nem dobunk el tudást — csak (a) a DUPLIKÁCIÓT szüntetjük meg (ugyanaz az
+ * útvonal 3 mezőben, ugyanaz az abszolút út a `source`-ban is), (b) az agent számára HASZNÁLHATATLAN belső kulcsokat
+ * hagyjuk el (`contentHash` dedup-kulcs, opak `scopeId`-k), (c) a 17-jegyű float-okat értelmes pontosságra kerekítjük.
+ * Minden megmaradó tény továbbra is elérhető, csak EGY, egyértelmű helyen.
+ *
+ * A transzformáció a read-tool KIMENETÉN fut, így az MCP és a REST `/api/read` is ezt kapja; a belső retrieval-DTO
+ * (és a kliens/CLI fogyasztói) érintetlenek.
+ */
+class FAM_ReadResponseShape_Util {
+    /** A score-ok megjelenítési pontossága (0.5530494673617745 → 0.5530) — a rangsorhoz bőven elég. */
+    static SCORE_DECIMALS = 4;
+    /**
+     * Egy hit KOMPAKT, agent-barát alakja. **Útvonal-SSOT (a #3 panasz gyökere):** eddig HÁROM különböző útvonal-mező
+     * volt HÁROM különböző bázissal (`sourceFilePath` a scan-root-hoz relatív → az agent nem tudta feloldani;
+     * `absolutePath`; `source.repoRelativePath`), ezért „nem álltak össze". Mostantól:
+     * - **`path`** — a MEGNYITHATÓ útvonal: abszolút, VAGY a `basePath`-hoz relatív, ha a hívó adott ilyet. EZ a SSOT.
+     * - **`repoPath`** — repo-relatív út + repo-név (git-hivatkozáshoz), CSAK ha ismert.
+     * A régi mezők (`sourceFilePath`/`absolutePath`) MEGMARADNAK a visszafelé-kompatibilitásért, de a `path` az elsődleges.
+     */
+    static compactHit(hit) {
+        const source = hit.source;
+        const round = (value) => typeof value === 'number' ? Number(value.toFixed(FAM_ReadResponseShape_Util.SCORE_DECIMALS)) : undefined;
+        const compact = {
+            id: hit.id,
+            table: hit.table,
+            // ÚTVONAL-SSOT: a `sourceFilePath` már a hívó `basePath`-jához igazított (rebaseToBasePath), különben az
+            // abszolút út — így MINDIG feloldható. A régi mezőket lentebb megtartjuk (kompatibilitás).
+            path: hit.sourceFilePath ?? hit.absolutePath ?? null,
+            score: round(hit.score),
+            finalScore: round(hit.finalScore),
+        };
+        if (hit.lexicalScore !== undefined) {
+            compact.lexicalScore = round(hit.lexicalScore);
+        }
+        if (hit.weight !== undefined && hit.weight !== 1) {
+            compact.weight = hit.weight;
+        }
+        // Lokáció a fájlon BELÜL (melyik szekció / hányadik sor) — a „hol nézzem meg" kérdésre.
+        if (hit.headingPath?.length) {
+            compact.heading = hit.headingPath.join(' › ');
+        }
+        const position = hit.position;
+        if (position?.lineStart) {
+            compact.lines = position.lineEnd && position.lineEnd !== position.lineStart
+                ? `${position.lineStart}-${position.lineEnd}`
+                : String(position.lineStart);
+        }
+        if (hit.chunkType) {
+            compact.chunkType = hit.chunkType;
+        }
+        if (hit.kind) {
+            compact.kind = hit.kind;
+        }
+        if (hit.tags?.length) {
+            compact.tags = hit.tags;
+        }
+        // Scope: az opak `scopeId`-k helyett ember/agent-olvasható `layer=név` lánc (a szűkítéshez ezt kell megadni).
+        const scopePath = (hit.scopePath ?? []);
+        if (scopePath.length) {
+            compact.scope = scopePath.map((ref) => `${ref.layer}=${ref.canonicalName}`).join('/');
+        }
+        // Repo-hivatkozás (git-link) — csak ha van; a `source` többi mezője (root/path/absolutePath) DUPLIKÁCIÓ volt.
+        if (source?.repoName && source?.repoRelativePath) {
+            compact.repoPath = `${source.repoName}:${source.repoRelativePath}`;
+        }
+        if (source?.type) {
+            compact.sourceType = source.type;
+        }
+        // Rules-specifikus kurátor-mezők (ha vannak) — ezek döntik el, MENNYIRE kötelező a szabály.
+        for (const key of ['ruleId', 'ruleScope', 'importance', 'userApproved', 'category']) {
+            const value = hit[key];
+            if (value !== undefined && value !== null) {
+                compact[key] = value;
+            }
+        }
+        if (hit.lastModifiedMs) {
+            compact.lastModified = new Date(hit.lastModifiedMs).toISOString().slice(0, 10);
+        }
+        // A TARTALOM a végére — így a metaadat-fej egyben olvasható a hosszú szöveg előtt.
+        if (hit.content !== undefined) {
+            compact.content = hit.content;
+        }
+        // Visszafelé-kompatibilitás: a `sourceFilePath` MEGMARAD (a kliens `ma-search` erre a mezőnévre épül) — értéke
+        // AZONOS a `path`-szal, tehát alias, nem harmadik igazság. Az `absolutePath` viszont CSAK akkor kerül bele, ha
+        // ténylegesen ELTÉR (azaz `basePath`-rebase történt, és így külön információt hordoz) — különben szó szerinti
+        // duplikáció lenne, ami épp a panaszolt „nagy csomag" + „az útvonalak nem állnak össze" problémát okozta.
+        compact.sourceFilePath = hit.sourceFilePath ?? null;
+        if (hit.absolutePath && hit.absolutePath !== compact.path) {
+            compact.absolutePath = hit.absolutePath;
+        }
+        return compact;
+    }
+    /**
+     * OPERATÍV VISSZAJELZÉS (user-FR 2026-07-29 — általános MCP-követelmény): „a tool-ok adjanak visszajelzést a
+     * működésről: összesen N elem között kerestünk, M tűnik relevánsnak, K megjelenítve + mit tegyél, hogy mindet
+     * lásd / fájlba írd / célzottabban keress". PURE — a számokból épít egy mondatot + konkrét, MÁSOLHATÓ tippeket.
+     */
+    static buildSummary(set) {
+        const scope = set.tables.length ? set.tables.join('+') : 'minden tár';
+        const searched = set.searchedCount > 0
+            ? `${FAM_ReadResponseShape_Util.humanCount(set.searchedCount)} elem között kerestünk`
+            : 'a keresés lefutott';
+        const relevant = `${set.totalRelevant} tűnik magabiztosan relevánsnak`;
+        const shown = set.truncated
+            ? `${set.shown} megjelenítve (topK=${set.topK} vágta)`
+            : `mind a ${set.shown} megjelenítve`;
+        return `[${scope}] ${searched} · ${relevant} · ${shown}.`;
+    }
+    /** A summary melletti, KONKRÉT következő lépések (csak a releváns tippek — nincs zaj). PURE. */
+    static buildHints(set) {
+        const hints = [];
+        if (set.truncated) {
+            const all = Math.max(set.totalRelevant, set.shown);
+            hints.push(`MIND: futtasd újra \`topK: ${all}\`-val (vagy \`depth: "deep"\`-pel a mélyebb feltárásért).`);
+            hints.push('FÁJLBA: a CLI-vel `fam read --query "…" --json > talalatok.json` (nagy találat-halmaznál ez '
+                + 'a javasolt út — a chat-választ nem terheli).');
+        }
+        if (set.totalRelevant > set.shown * 3 && !set.hasScopeFilter) {
+            hints.push('CÉLZOTTABBAN: szűkíts `scope`-pal (pl. `{"layer":"project","name":"<projekt>"}`), `tags`-szel '
+                + 'vagy `kind`-dal — a sok találat általában túl tág kérdést jelez.');
+        }
+        if (!set.totalRelevant) {
+            hints.push('NINCS magabiztos találat: próbálj más megfogalmazást/kulcsszavakat, vagy emeld a `topK`-t; '
+                + 'a `minScore: 0` a leggyengébb tippeket is visszaadja.');
+        }
+        return hints;
+    }
+    /** Rövid, ember-olvasható darabszám (12 400 → „12.4k"). PURE. */
+    static humanCount(count) {
+        if (count < 1000) {
+            return String(count);
+        }
+        if (count < 1000000) {
+            const thousands = count / 1000;
+            return `${thousands >= 100 ? Math.round(thousands) : Number(thousands.toFixed(1))}k`;
+        }
+        return `${Number((count / 1000000).toFixed(1))}M`;
+    }
+    /** Egy teljes result-blokk formázása: kompakt hit-ek + summary + hints (a result többi mezője érintetlen). */
+    static shapeResult(set) {
+        const hits = set.result.hits ?? [];
+        const shaped = { ...set.result };
+        shaped.summary = FAM_ReadResponseShape_Util.buildSummary({
+            tables: set.tables, searchedCount: set.searchedCount, totalRelevant: set.result.totalRelevant ?? 0,
+            shown: hits.length, truncated: Boolean(set.result.truncated), topK: set.topK,
+        });
+        const hints = FAM_ReadResponseShape_Util.buildHints({
+            totalRelevant: set.result.totalRelevant ?? 0, shown: hits.length,
+            truncated: Boolean(set.result.truncated), hasScopeFilter: Boolean(set.hasScopeFilter),
+        });
+        if (hints.length) {
+            shaped.hints = hints;
+        }
+        shaped.searchedCount = set.searchedCount;
+        shaped.hits = hits.map((hit) => FAM_ReadResponseShape_Util.compactHit(hit));
+        return shaped;
+    }
+}
+exports.FAM_ReadResponseShape_Util = FAM_ReadResponseShape_Util;

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

@@ -110,13 +110,18 @@ class FAM_Mcp_Adapter_Service {
         }
         return 'Ismeretlen hiba a tool-végrehajtás során.';
     }
-    /** JSON-stringify (a transport text-content payload-ja). */
+    /**
+     * JSON-stringify (a transport text-content payload-ja) — **TÖRDELVE** (user-FR 2026-07-29, agent-panasz:
+     * „formázatlan, tördeletlen egy soros válaszokat kapnak"). A 2-szóközös indentálás soronként EGY mezőt ad, így a
+     * válasz olvasható/diffelhető; a token-költség elhanyagolható a beágyazott `content`-ek mellett, cserébe az agent
+     * (és a `truncate`-elő host) sokkal jobban tudja kezelni.
+     */
     stringify(data) {
         try {
-            return JSON.stringify(data);
+            return JSON.stringify(data, null, 2);
         }
         catch {
-            return JSON.stringify({ ok: false, error: { message: 'A válasz nem szerializálható JSON-ra.' } });
+            return JSON.stringify({ ok: false, error: { message: 'A válasz nem szerializálható JSON-ra.' } }, null, 2);
         }
     }
 }